repl.txt (4907B)
1 2 {{alias}}( x[, options] ) 3 Samples elements from an array-like object. 4 5 Parameters 6 ---------- 7 x: ArrayLike 8 Array-like object from which to sample. 9 10 options: Object (optional) 11 Options. 12 13 options.size: integer (optional) 14 Sample size. By default, the function returns an array having the same 15 length as `x`. Specify the `size` option to generate a sample of a 16 different size. 17 18 options.probs: Array<number> (optional) 19 Element probabilities. By default, the probability of sampling an 20 element is the same for all elements. To assign elements different 21 probabilities, set the `probs` option. The `probs` option must be a 22 numeric array consisting of nonnegative values which sum to one. When 23 sampling without replacement, note that the `probs` option denotes the 24 initial element probabilities which are then updated after each draw. 25 26 options.replace: boolean (optional) 27 Boolean indicating whether to sample with replacement. If the `replace` 28 option is set to `false`, the `size` option cannot be an integer larger 29 than the number of elements in `x`. Default: `true`. 30 31 Returns 32 ------- 33 out: Array 34 Sample. 35 36 Examples 37 -------- 38 > var out = {{alias}}( 'abc' ) 39 e.g., [ 'a', 'a', 'b' ] 40 > out = {{alias}}( [ 3, 6, 9 ] ) 41 e.g., [ 3, 9, 6 ] 42 > var bool = ( out.length === 3 ) 43 true 44 45 > out = {{alias}}( [ 3, null, NaN, 'abc', function(){} ] ) 46 e.g., [ 3, 'abc', null, 3, null ] 47 48 // Set sample size: 49 > out = {{alias}}( [ 3, 6, 9 ], { 'size': 10 }) 50 e.g., [ 6, 3, 9, 9, 9, 6, 9, 6, 9, 3 ] 51 > out = {{alias}}( [ 0, 1 ], { 'size': 20 }) 52 e.g., [ 0, 0, 0, 1, 1, 0, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 1, 1, 1, 0 ] 53 54 // Draw without replacement: 55 > out = {{alias}}( [ 1, 2, 3, 4, 5, 6 ], { 'replace': false, 'size': 3 }) 56 e.g., [ 6, 1, 5 ] 57 > out = {{alias}}( [ 0, 1 ], { 'replace': false }) 58 e.g., [ 0, 1 ] 59 60 // Assigning non-uniform element probabilities: 61 > var x = [ 1, 2, 3, 4, 5, 6 ]; 62 > var probs = [ 0.1, 0.1, 0.1, 0.1, 0.1, 0.5 ]; 63 > out = {{alias}}( x, { 'probs': probs }) 64 e.g., [ 5, 6, 6, 5, 6, 4 ] 65 > out = {{alias}}( x, { 'probs': probs, 'size': 3, 'replace': false }) 66 e.g., [ 6, 4, 1 ] 67 68 69 {{alias}}.factory( [pool, ][options] ) 70 Returns a function to sample elements from an array-like object. 71 72 If provided an array-like object `pool`, the returned function will always 73 sample from the supplied object. 74 75 Parameters 76 ---------- 77 pool: ArrayLike (optional) 78 Array-like object from which to sample. 79 80 options: Object (optional) 81 Options. 82 83 options.seed: integer (optional) 84 Integer-valued seed. 85 86 options.size: integer (optional) 87 Sample size. 88 89 options.replace: boolean (optional) 90 Boolean indicating whether to sample with replacement. Default: `true`. 91 92 options.mutate: boolean (optional) 93 Boolean indicating whether to mutate the `pool` when sampling without 94 replacement. If a population from which to sample is provided, the 95 underlying `pool` remains by default constant for each function 96 invocation. To mutate the `pool` by permanently removing observations 97 when sampling without replacement, set the `mutate` option to `true`. 98 The returned function returns `null` after all population units are 99 exhausted. Default: `false`. 100 101 Returns 102 ------- 103 fcn: Function 104 Function to sample elements from an array-like object. 105 106 Examples 107 -------- 108 // Set a seed: 109 > var mysample = {{alias}}.factory({ 'seed': 232 }); 110 > var out = mysample( 'abcdefg' ) 111 e.g., [ 'g', 'd', 'g', 'f', 'c', 'e', 'f' ] 112 113 // Provide `pool` and set a seed plus a default sample size: 114 > var pool = [ 1, 2, 3, 4, 5, 6 ]; 115 > mysample = {{alias}}.factory( pool, { 'seed': 232, 'size': 2 }); 116 > out = mysample() 117 e.g., [ 6, 4 ] 118 > out = mysample() 119 e.g., [ 6, 5 ] 120 121 // Mutate the `pool`: 122 > var opts = { 'seed': 474, 'size': 3, 'mutate': true, 'replace': false }; 123 > pool = [ 1, 2, 3, 4, 5, 6 ]; 124 > mysample = {{alias}}.factory( pool, opts ); 125 > out = mysample() 126 e.g., [ 4, 3, 6 ] 127 > out = mysample() 128 e.g., [ 1, 5, 2 ] 129 > out = mysample() 130 null 131 132 // Override default `size` parameter when invoking created function: 133 > mysample = {{alias}}.factory( [ 0, 1 ], { 'size': 2 }); 134 > out = mysample() 135 e.g., [ 1, 1 ] 136 > out = mysample({ 'size': 10 }) 137 e.g, [ 0, 1, 1, 1, 0, 1, 0, 0, 1, 1 ] 138 139 // Sample with and without replacement: 140 > mysample = {{alias}}.factory( [ 0, 1 ], { 'size': 2 }); 141 > out = mysample() 142 e.g., [ 1, 1 ] 143 > out = mysample({ 'replace': false }) 144 e.g., [ 0, 1 ] or [ 1, 0 ] 145 > out = mysample() 146 e.g., [ 1, 1 ] 147 148 See Also 149 -------- 150