Difference between revisions of "Shuffle"

Latest revision as of 00:39, 10 February 2016

Function Shuffle(a , i)

Shuffle returns a random reordering (permutation) of the values in array «a» over index «i». If you omit «i», by default it shuffles over Run -- i.e. it shuffles a random sample. You can use it generate an independent random sample from an existing probability distribution, «a».

Independent Shuffles

If «a» has two dimensions, say J and Run, Shuffle(a, J) shuffles the sample over J independently for each value of Run. Shuffle(a, Run) -- or Shuffle(a), which is equivalent, because it assumes Run by default -- will shuffle each sample independently for each value of J.

Like other distribution functions, you can add an extra dimension using the «Over» parameter. For example, if B is a sample with no indexes other than Run,

Shuffle(B, Over: J)

returns an array of samples indexed by J, where the sample for each value of J is shuffled independently.

If you want to shuffle the slices of a multidimensional array over index «i», without shuffling the values within each slice, use this method:

A[@I = Shuffle(@I, I)]

This shuffles A over index I, but does not shuffle each slice of A for each value of I.

Shuffling along the implicit index

You cannot shuffle along the implicit index, since the «i» parameter defaults to be the Run index when omitted. So if you want to shuffle along an implicit index, things get tricky.

If you need to shuffle a list, then make sure your list is held by a local variable so that it has a name. Once it has a name, you have a way to refer to it. So for example, this does not have the intended result

Shuffle(1..100)

but this does work because we have a way to name the implicit dimension

Var L:= 1..100 Do Shuffle(L, L)

If you have a multidimensional array, A, where one index is implicit and you want to shuffle along the implicit dimension, you can't obtain a name for the implicit index from A, so you have to introduce a name somehow. This requires creating a new implicit or explicit dimension that has a name, and reindexing the array onto this. This is done as follows.

Var I := 1..Size(A, ListLen: true) Do Shuffle(Slice(A, I), I)

@@ Line 1: / Line 1: @@
 [[Category:Distribution Functions]]
 [[Category:Doc Status C]] <!-- For Lumina use, do not change -->
-= Function Shuffle =
+== Function Shuffle(a '', i'') ==
-Shuffle returns a random permutation of the values in an array along a given index.
+[[Shuffle]] returns a random reordering (permutation) of the values in array «a» over index «i». If you omit «i», by default it shuffles over [[Run]] -- i.e. it shuffles a random sample. You can use it generate an independent random sample from an existing probability distribution, «a».
+== Independent Shuffles ==
+If «a» has two dimensions, say <code>J</code> and [[Run]],  <code>Shuffle(a, J)</code> shuffles the sample over <code>J</code> independently for each value of [[Run]]. <code>Shuffle(a, Run)</code> -- or <code>Shuffle(a)</code>, which is equivalent, because it assumes [[Run]] by default -- will shuffle each sample independently for each value of <code>J</code>.
+Like other distribution functions, you can add an extra dimension using the «Over» parameter. For example, if <code>B</code> is a sample with no indexes other than [[Run]],
+:<code>Shuffle(B, Over: J)</code>
+returns an array of samples indexed by <code>J</code>, where the sample for each value of <code>J</code> is shuffled independently.
+If you want to shuffle the slices of a multidimensional array over index «i», without shuffling the values within each slice, use this method:
+:<code>A[@I = Shuffle(@I, I)]</code>
+This shuffles <code>A</code> over index <code>I</code>, but does not shuffle each slice of <code>A</code> for each value of <code>I</code>.
+== Shuffling along the implicit index ==
-== Declaration ==
+You cannot shuffle along the implicit index, since the «i» parameter defaults to be the [[Run]] index when omitted. So if you want to shuffle along an implicit index, things get tricky.
-  Shuffle(A : Array[I] ; I : IndexType = Run)
+If you need to shuffle a list, then make sure your list is held by a local variable so that it has a name.  Once it has a name, you have a way to refer to it.  So for example, this does not have the intended result
+:<code>Shuffle(1..100)</code>
-If A contains dimensions other than I, each slice of those dimensions will be independently shuffled.
+but this does work because we have a way to name the implicit dimension
+:<code>Var L:= 1..100 Do Shuffle(L, L)</code>
-If you want to shuffle an array along I, but have the same shuffling apply to all slices along other dimensions, you can do this:
+If you have a multidimensional array, <code>A</code>, where one index is implicit and you want to shuffle along the implicit dimension, you can't obtain a name for the implicit index from <code>A</code>, so you have to introduce a name somehow. This requires creating a new implicit or explicit dimension that has a name, and reindexing the array onto this.  This is done as follows.
- Slice(A, I, Shuffle(@I,I))
+:<code>Var I := 1..Size(A, ListLen: true) Do Shuffle(Slice(A, I), I)</code>
-To make all slices of an uncertain result independent, use Shuffle(A), or equivalently, Shuffle(A,Run).
+==See Also==
-(note: I is optional as of build 4.0.0.48)
+* [[Random]]
+* [[Slice]]
+* [[Distribution Functions]]