blib/lib/Stats/LikeR/Usage.pm

filter: Statementstmt 100% 147 / 147 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 2 / 2 Podpod n/a totaltotal 100% 149 / 149 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« LikeR.xs ↑ Summary
1 package Stats::LikeR::Usage;
2 # The help screens that Stats::LikeR prints above an error in how a function was
3 # called, laid out as Python's argparse lays out its own (Lib/argparse.py,
4 # HelpFormatter): the usage line, a one-line description, the positional
5 # arguments, the options with their defaults, and an example. The error itself
6 # follows on the last line, as "fn: error: ...", where argparse's
7 # ArgumentParser.error() puts its own.
8 #
9 # This file is required only when such an error is raised, by
10 # Stats::LikeR::_usage_text(), so a correct call never compiles it. Every
11 # exported function has a screen here; t/usage.t checks that, and checks the
12 # layout every screen must keep:
13 #
14 # - the first line is "usage: fn(", and a usage too long for one line wraps
15 # onto lines indented to start under its first argument, after "usage:
16 # fn(", as argparse indents under its first after "usage: prog ";
17 # - the sections are "positional arguments:", "options:" and "example:", in
18 # that order, the first two left out when a function has nothing to put in
19 # them;
20 # - an entry's name and its help are two columns, and a name too wide for its
21 # column puts its help on the next line, as argparse does. argparse starts
22 # the help at most at column 25 (max_help_position=24, counted from 0) and
23 # sooner when every name is short; here it is column 26 in every screen, so
24 # that all of them line up with one another, and with df2h's, the first;
25 # - no line is wider than 80 columns, there are no tabs, and the screen ends
26 # with one blank line, above the error.
27 #
28 # A name that is a second name for another function (aoh2h, rbind) is in
29 # %ALIAS, and shows the screen of the function it is; that function's messages
30 # already name it.
31 221 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
32 221 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
33  
34 221 our %ALIAS = (
35 aoh2h => 'df2h',
36 rbind => 'concat',
37 );
38  
39 221 our %SCREEN;
40  
41 221 $SCREEN{df2h} = <<'END';
42 usage: df2h(DF [, var_name => KEY] [, value_name => VALUE]
43 [, duplicates => {die,first,last}])
44  
45 Fold the two columns of a data frame into a flat hash: { KEY => VALUE, ... }.
46  
47 positional arguments:
48 DF the data frame: an AoH, AoA, HoA or HoH
49  
50 options:
51 var_name => KEY column whose cells become the hash keys
52 (default: 'variable'; for an AoA, position 0)
53 value_name => VALUE column whose cells become the hash values
54 (default: 'value'; for an AoA, position 1)
55 duplicates => MODE what a repeated key does: die, first or last
56 (default: die; a HoH accepts only die)
57  
58 example:
59 df2h([ { variable => 'a', value => 1 }, { variable => 'b', value => 2 } ])
60 # returns { a => 1, b => 2 }
61  
62 END
63  
64 # Screens, part 1.
65  
66 221 $SCREEN{add_data} = <<'END';
67 usage: add_data(TARGET, NEW)
68  
69 Add NEW's rows or columns to TARGET, in place, coercing NEW to TARGET's shape.
70  
71 positional arguments:
72 TARGET the hash or array ref added to; it is changed in place
73 NEW the hash or array ref whose data is added (copied)
74  
75 example:
76 my $d = { x => [1, 2] };
77 add_data($d, { x => [3] });
78 # $d is now { x => [1, 2, 3] }
79  
80 END
81  
82 221 $SCREEN{agg} = <<'END';
83 usage: agg(DF, agg => { COL => FUNC, ... } [, by => COL] [, skipna => {1,0}]
84 [, sort => {1,0}] [, output_type => {aoa,aoh,hoa,hoh}])
85  
86 Aggregate the columns of a data frame, whole or by group.
87  
88 positional arguments:
89 DF the data frame: an AoA, AoH, HoA or HoH
90  
91 options:
92 agg => SPEC required: { COL => FUNC }, FUNC an aggregator name
93 (mean median sum sd var min max count n nunique
94 first last mode), a list of them, or a coderef
95 by => COL a grouping column, or an arrayref of them
96 (default: none, one row for the whole frame)
97 skipna => BOOL ignore undef cells in numeric aggregators
98 (default: 1)
99 sort => BOOL sort the groups by key; 0 keeps first-seen order
100 (default: 1)
101 output_type => TYPE the shape returned (default: the shape of DF)
102  
103 example:
104 agg([ { g => 'a', x => 1 }, { g => 'a', x => 3 }, { g => 'b', x => 5 } ],
105 by => 'g', agg => { x => 'mean' })
106 # returns [ { g => 'a', x => 2 }, { g => 'b', x => 5 } ]
107  
108 END
109  
110 221 $SCREEN{aoh2hoa} = <<'END';
111 usage: aoh2hoa(AOH)
112  
113 Transpose an array of hashes (rows) into a hash of arrays (columns).
114  
115 positional arguments:
116 AOH an arrayref of hashrefs, one per row
117  
118 example:
119 aoh2hoa([ { a => 1, b => 2 }, { a => 3 } ])
120 # returns { a => [1, 3], b => [2, undef] }
121  
122 END
123  
124 221 $SCREEN{aoh2hoh} = <<'END';
125 usage: aoh2hoh(AOH, KEY)
126  
127 Index an array of hashes by one column, into a hash of hashes.
128  
129 positional arguments:
130 AOH an arrayref of hashrefs, one per row
131 KEY the column whose (unique) value names each row
132  
133 example:
134 aoh2hoh([ { id => 'p1', kd => 12.4 }, { id => 'p2', kd => 3.1 } ], 'id')
135 # returns { p1 => { id => 'p1', kd => 12.4 },
136 # p2 => { id => 'p2', kd => 3.1 } }
137  
138 END
139  
140 221 $SCREEN{assign} = <<'END';
141 usage: assign(DF, NAME => VALUE [, NAME => VALUE ...])
142  
143 Add or overwrite columns of a data frame, in place, and return it.
144  
145 positional arguments:
146 DF the data frame: an AoH, HoA or HoH
147  
148 options:
149 NAME => VALUE the column NAME, set from VALUE: a coderef called
150 once per row with the row in $_, an arrayref holding
151 the whole column, or a map_cell { ... } block that
152 edits the column NAME cell by cell
153  
154 example:
155 assign([ { w => 70, h => 1.75 } ], bmi => sub { $_->{w} / $_->{h}**2 })
156 # returns [ { w => 70, h => 1.75, bmi => 22.8571428571429 } ]
157  
158 END
159  
160 221 $SCREEN{avals} = <<'END';
161 usage: avals(DF, COLUMN)
162  
163 Return one column of a data frame as a list (vals() returns it as an arrayref).
164  
165 positional arguments:
166 DF the data frame: an AoH, HoA or HoH
167 COLUMN the name of the column
168  
169 example:
170 avals([ { age => 30 }, { age => 41 } ], 'age')
171 # returns (30, 41)
172  
173 END
174  
175 221 $SCREEN{bfill} = <<'END';
176 usage: bfill(DF [, cols => [COL, ...]] [, limit => N])
177  
178 Fill each undef cell with the next defined value below it in its column.
179  
180 positional arguments:
181 DF the data frame: an AoA, AoH, HoA or HoH
182  
183 options:
184 cols => [COL, ...] the columns to fill (default: every column)
185 limit => N fill at most N undef cells in a row in each gap
186 (default: no limit)
187  
188 example:
189 bfill({ x => [undef, 2, undef, 4] })
190 # returns { x => [2, 2, 4, 4] }
191  
192 END
193  
194 221 $SCREEN{ffill} = <<'END';
195 usage: ffill(DF [, cols => [COL, ...]] [, limit => N])
196  
197 Fill each undef cell with the last defined value above it in its column.
198  
199 positional arguments:
200 DF the data frame: an AoA, AoH, HoA or HoH
201  
202 options:
203 cols => [COL, ...] the columns to fill (default: every column)
204 limit => N fill at most N undef cells in a row in each gap
205 (default: no limit)
206  
207 example:
208 ffill({ x => [1, undef, 3, undef] })
209 # returns { x => [1, 1, 3, 3] }
210  
211 END
212  
213 221 $SCREEN{fillna} = <<'END';
214 usage: fillna(DF, value => VALUE [, cols => [COL, ...]])
215  
216 Replace undef cells with a constant, in a new data frame.
217  
218 positional arguments:
219 DF the data frame: an AoA, AoH, HoA or HoH
220  
221 options:
222 value => VALUE required: the fill for every column, or a hashref
223 { COL => VALUE, ... } of a fill per column
224 cols => [COL, ...] the columns a single VALUE fills; not with a hashref
225 (default: every column)
226  
227 example:
228 fillna({ x => [1, undef], y => [undef, 'b'] }, value => 0)
229 # returns { x => [1, 0], y => [0, 'b'] }
230  
231 END
232  
233 221 $SCREEN{chunk} = <<'END';
234 usage: chunk(ARRAY, size => N | parts => K)
235  
236 Split an array into contiguous groups, in order.
237  
238 positional arguments:
239 ARRAY the arrayref to split; its contents are not examined
240  
241 options:
242 size => N N elements in each group, the last group holding
243 what is left
244 parts => K K groups of as equal a size as possible; give
245 exactly one of size and parts
246  
247 example:
248 chunk([1 .. 5], size => 2)
249 # returns ([1, 2], [3, 4], [5])
250  
251 END
252  
253 221 $SCREEN{col} = <<'END';
254 usage: col(NAME)
255  
256 Name a column in a filter() predicate: col('x') > 0, combined with & | !.
257  
258 positional arguments:
259 NAME the name of the column
260  
261 example:
262 filter([ { age => 15 }, { age => 30 } ], col('age') >= 18)
263 # returns [ { age => 30 } ]
264  
265 END
266  
267 221 $SCREEN{col2col} = <<'END';
268 usage: col2col(DATA, COMMAND [, COLS [, na => {pairwise,omit,keep}]
269 [, skip_errors => {1,0}] [, rm_undef => {1,0}]])
270  
271 Apply a two-column function to every pair of columns, into a hash of hashes.
272  
273 positional arguments:
274 DATA the table: an AoH, HoA or HoH
275 COMMAND a coderef called as COMMAND->(\@a, \@b), or the
276 name of a function, such as 'cor'
277 COLS the "from" columns: one name, an arrayref of names,
278 or undef for every column (default: every column);
279 or, in its place, a hashref of the options below
280  
281 options:
282 na => MODE undef cells: pairwise drops a row from both
283 columns, omit drops it from its own column, keep
284 passes it through (default: pairwise)
285 skip_errors => BOOL store a failing pair's error as its cell, rather
286 than dying (default: 1)
287 rm_undef => BOOL the older na: 1 is pairwise and 0 is keep; also
288 spelt rm_na, and not given with na
289  
290 example:
291 col2col({ x => [1, 2, 3], y => [2, 4, 7] }, 'cor')
292 # returns { x => { y => 0.993399267798783 },
293 # y => { x => 0.993399267798783 } }
294  
295 END
296  
297 221 $SCREEN{colnames} = <<'END';
298 usage: colnames(DF)
299  
300 Return the column names of a data frame, or their count in scalar context.
301  
302 positional arguments:
303 DF the data frame: an AoA, AoH, HoA or HoH
304  
305 example:
306 colnames([ { b => 1, a => 2 }, { c => 3 } ])
307 # returns ('a', 'b', 'c')
308  
309 END
310  
311 221 $SCREEN{concat} = <<'END';
312 usage: concat(DF [, DF ...])
313  
314 Stack data frames of one shape, row-wise, as R's rbind() does.
315  
316 positional arguments:
317 DF a data frame: an AoA, AoH, HoA or HoH; every
318 non-empty one must have the same shape
319  
320 example:
321 concat({ x => [1, 2] }, { x => [3], y => ['a'] })
322 # returns { x => [1, 2, 3], y => [undef, undef, 'a'] }
323  
324 END
325  
326 221 $SCREEN{csort} = <<'END';
327 usage: csort(DF, BY [, OUTPUT_TYPE] [, ROW_NAME_COL])
328  
329 Return a copy of a data frame sorted by a column or a comparator.
330  
331 positional arguments:
332 DF the data frame: an AoA, AoH, HoA or HoH
333 BY a column name (AoH, HoA, HoH), a column index (AoA),
334 or a comparator coderef using $a and $b
335 OUTPUT_TYPE the shape returned: {aoh,hoa,aoa}
336 (default: the shape of DF, a HoH giving an AoH)
337 ROW_NAME_COL for a HoH, the column that holds the row names
338 (default: 'row_name')
339  
340 example:
341 csort([ { n => 3 }, { n => 1 }, { n => 2 } ], 'n')
342 # returns [ { n => 1 }, { n => 2 }, { n => 3 } ]
343  
344 END
345  
346 # Screens, part 2.
347  
348 221 $SCREEN{cfilter} = <<'END';
349 usage: cfilter(DATA, (keep => SELECTOR | remove => SELECTOR)
350 [, na => {keep,omit}] [, against => COLUMN])
351  
352 Select the columns of a table by name, pattern or test, in the same shape.
353  
354 positional arguments:
355 DATA the table: an AoH, HoA or HoH
356  
357 options:
358 keep => SELECTOR the columns to keep: an arrayref of names, a qr//
359 matched against the names, or a code ref or function
360 name that a column's cells must pass
361 remove => SELECTOR the columns to remove, chosen as for keep; give one
362 of keep and remove
363 na => NA for a code ref or function: keep hands it undef
364 cells, omit leaves them out (default: keep)
365 against => COLUMN for a two-column test such as cor: the column each
366 column is paired with, over the rows defined in both
367  
368 example:
369 cfilter({ x => [1, 2], y => [3, 4], z => [0, 0] }, keep => ['x', 'y'])
370 # returns { x => [1, 2], y => [3, 4] }
371  
372 END
373  
374 221 $SCREEN{dftype} = <<'END';
375 usage: dftype(DATA)
376  
377 Name the shape of DATA: AoA, AoH, HoA, HoH, array, hash, scalar or undef.
378  
379 positional arguments:
380 DATA any scalar, or a reference to anything
381  
382 example:
383 dftype([ { a => 1 }, { a => 2 } ])
384 # returns 'AoH'
385  
386 END
387  
388 221 $SCREEN{drop_cols} = <<'END';
389 usage: drop_cols(DF, COLUMN [, COLUMN ...])
390  
391 Return a new data frame without the named columns.
392  
393 positional arguments:
394 DF the data frame: an AoH, AoA, HoA or HoH
395 COLUMN a column to drop: a name, or for an AoA a 0-based
396 position; several may also come as one arrayref
397  
398 example:
399 drop_cols({ a => [1, 4], b => [2, 5], c => [3, 6] }, 'b')
400 # returns { a => [1, 4], c => [3, 6] }
401  
402 END
403  
404 221 $SCREEN{drop_duplicates} = <<'END';
405 usage: drop_duplicates(DF [, subset => COLUMNS]
406 [, keep => {first,last,0}])
407  
408 Remove duplicate rows, keeping one occurrence of each.
409  
410 positional arguments:
411 DF the data frame: an AoH, AoA or HoA (not a HoH)
412  
413 options:
414 subset => COLUMNS the column, or arrayref of columns, whose cells make
415 two rows equal (default: every column)
416 keep => KEEP which occurrence survives: first, last, or 0 (also
417 'none') to drop every duplicated row (default: first)
418  
419 example:
420 drop_duplicates({ id => [1, 1, 2], v => [10, 20, 30] }, subset => 'id')
421 # returns { id => [1, 2], v => [10, 30] }
422  
423 END
424  
425 221 $SCREEN{dropna} = <<'END';
426 usage: dropna(DF, (cols => COLUMNS | rows => ROWS) [, how => {any,all}])
427  
428 Drop the rows of a data frame that hold undef in given columns, or given rows.
429  
430 positional arguments:
431 DF the data frame: an AoH, HoA or HoH
432  
433 options:
434 cols => COLUMNS arrayref of columns: drop the rows undef in them
435 rows => ROWS arrayref of rows to delete outright: indices for an
436 AoH or HoA, row names for a HoH; give one of cols
437 and rows
438 how => HOW with cols, drop a row when any or when all of them
439 are undef (default: any)
440  
441 example:
442 dropna({ A => [1, 2, undef], B => [1, 2, 3] }, cols => ['A'])
443 # returns { A => [1, 2], B => [1, 2] }
444  
445 END
446  
447 221 $SCREEN{filter} = <<'END';
448 usage: filter(DF, PREDICATE [, output_type => {aoh,hoa}])
449  
450 Keep the rows of a data frame for which a predicate is true.
451  
452 positional arguments:
453 DF the data frame: an AoH, HoA or HoH
454 PREDICATE a code ref called with each row as $_, or a col()
455 expression such as col('x') > 0
456  
457 options:
458 output_type => TYPE the shape of the result, aoh or hoa
459 (default: the shape of DF)
460  
461 example:
462 filter([ { x => 1 }, { x => 5 } ], sub { $_->{x} > 2 })
463 # returns [ { x => 5 } ]
464  
465 END
466  
467 221 $SCREEN{get_union} = <<'END';
468 usage: get_union(ARRAY [, ARRAY ...])
469  
470 Return every distinct value in any of the arrays, in first-seen order.
471  
472 positional arguments:
473 ARRAY an array ref, read as a set; at least one
474  
475 example:
476 get_union([1, 2, 3, 3], [3, 4])
477 # returns (1, 2, 3, 4), or 4 in scalar context
478  
479 END
480  
481 221 $SCREEN{group_by} = <<'END';
482 usage: group_by(DATA, VALUE_COLUMN, GROUP_COLUMN [, FILTER ...])
483  
484 Split the values of one column by the levels of another, as R's split() does.
485  
486 positional arguments:
487 DATA the data frame: an AoH, HoA or HoH
488 VALUE_COLUMN the column whose values are collected
489 GROUP_COLUMN the column whose levels key the result
490 FILTER a hashref { column => sub { ... } }; a row is kept
491 only when each sub is true of that cell, in $_
492  
493 example:
494 group_by([ { g => 'a', v => 1 }, { g => 'b', v => 2 }, { g => 'a', v => 3 } ],
495 'v', 'g')
496 # returns { a => [1, 3], b => [2] }
497  
498 END
499  
500 221 $SCREEN{h2aoh} = <<'END';
501 usage: h2aoh(HASH [, var_name => KEY] [, value_name => VALUE]
502 [, sort => {key,value,none}])
503  
504 Unfold a flat hash into a two-column AoH, one row per pair.
505  
506 positional arguments:
507 HASH a hash ref whose values are plain scalars
508  
509 options:
510 var_name => KEY name of the column that receives the keys
511 (default: 'variable')
512 value_name => VALUE name of the column that receives the values
513 (default: 'value')
514 sort => ORDER the row order: key, value (largest first), or none
515 (default: key)
516  
517 example:
518 h2aoh({ a => 1, b => 2 })
519 # returns [ { variable => 'a', value => 1 },
520 # { variable => 'b', value => 2 } ]
521  
522 END
523  
524 221 $SCREEN{hoa2aoh} = <<'END';
525 usage: hoa2aoh(HOA)
526  
527 Turn a hash of arrays into an array of hashes, one hash per row.
528  
529 positional arguments:
530 HOA a hash ref whose values are array refs, one per
531 column
532  
533 example:
534 hoa2aoh({ id => [1, 2], name => ['a', 'b'] })
535 # returns [ { id => 1, name => 'a' }, { id => 2, name => 'b' } ]
536  
537 END
538  
539 221 $SCREEN{hoa2hoh} = <<'END';
540 usage: hoa2hoh(HOA, KEY)
541  
542 Turn a hash of arrays into a hash of hashes keyed by one of its columns.
543  
544 positional arguments:
545 HOA a hash ref whose values are array refs, one per
546 column
547 KEY the column whose values name the rows; it stays in
548 each row
549  
550 example:
551 hoa2hoh({ id => ['a', 'b'], x => [1, 2] }, 'id')
552 # returns { a => { id => 'a', x => 1 }, b => { id => 'b', x => 2 } }
553  
554 END
555  
556 221 $SCREEN{hoh2hoa} = <<'END';
557 usage: hoh2hoa(HOH [, undef_val => FILL] [, row_names => COLUMN])
558  
559 Turn a hash of hashes into a hash of arrays, its rows in sorted order.
560  
561 positional arguments:
562 HOH a hash ref whose values are hash refs, one per row
563  
564 options:
565 undef_val => FILL the value for a missing or undef cell
566 (default: undef)
567 row_names => COLUMN add a column of this name holding the row names
568 (default: none)
569  
570 example:
571 hoh2hoa({ r1 => { a => 1, b => 2 }, r2 => { a => 3 } })
572 # returns { a => [1, 3], b => [2, undef] }
573  
574 END
575  
576 221 $SCREEN{interpolate} = <<'END';
577 usage: interpolate(DF [, method => METHOD] [, cols => COLUMNS] [, order => N]
578 [, x => X] [, limit => N]
579 [, limit_direction => {forward,backward,both}]
580 [, limit_area => {inside,outside}])
581  
582 Fill undef cells along the rows by interpolation, as pandas' interpolate does.
583  
584 positional arguments:
585 DF the data frame: an AoH, AoA, HoA or HoH
586  
587 options:
588 method => METHOD linear, index, values, time, slinear, nearest, zero,
589 pad, ffill, bfill, backfill, quadratic, cubic,
590 cubicspline, pchip, akima, barycentric, krogh,
591 polynomial or spline (default: linear)
592 cols => COLUMNS arrayref of the columns to fill (default: all)
593 order => N the degree, which polynomial and spline require
594 x => X the abscissae: a column, or an arrayref
595 (default: the row positions)
596 limit => N the most cells filled in one run of undefs
597 (default: no limit)
598 limit_direction => DIRECTION
599 which way limit counts: forward, backward or both
600 (default: forward)
601 limit_area => AREA fill only inside or only outside the known values
602 (default: both)
603  
604 example:
605 interpolate({ v => [1, undef, 3] })
606 # returns { v => [1, 2, 3] }
607  
608 END
609  
610 221 $SCREEN{intersection} = <<'END';
611 usage: intersection(ARRAY [, ARRAY ...])
612  
613 Return the distinct values found in every one of the arrays.
614  
615 positional arguments:
616 ARRAY an array ref, read as a set; at least one
617  
618 example:
619 intersection([1, 2, 3], [2, 3, 4])
620 # returns (2, 3), or 2 in scalar context
621  
622 END
623  
624 221 $SCREEN{is_equivalent} = <<'END';
625 usage: is_equivalent(ARRAY, ARRAY [, ARRAY ...])
626  
627 Return 1 if every array holds the same set of distinct values, and 0 if not.
628  
629 positional arguments:
630 ARRAY an array ref, read as a set; at least two
631  
632 example:
633 is_equivalent([1, 2, 3], [3, 2, 1])
634 # returns 1
635  
636 END
637  
638 221 $SCREEN{ljoin} = <<'END';
639 usage: ljoin(H, I)
640  
641 Add I's columns to the rows of H that I also has, modifying H in place.
642  
643 positional arguments:
644 H a hash of hashes, { row => { column => value } }
645 I a hash whose rows are hash refs, or array refs of
646 column => value pairs
647  
648 example:
649 my %h = (jack => { age => 30 });
650 ljoin(\%h, { jack => { dept => 'IT' }, jane => { age => 25 } })
651 # %h is now (jack => { age => 30, dept => 'IT' })
652  
653 END
654  
655 221 $SCREEN{Lonly} = <<'END';
656 usage: Lonly(ARRAY [, ARRAY ...])
657  
658 Return the distinct values of the first array that are in no other array.
659  
660 positional arguments:
661 ARRAY an array ref, read as a set; at least one
662  
663 example:
664 Lonly([1, 2, 3], [3, 4, 5])
665 # returns (1, 2), or 2 in scalar context
666  
667 END
668  
669 221 $SCREEN{map_cell} = <<'END';
670 usage: map_cell(BLOCK)
671  
672 Wrap a block for assign(), which runs it on each cell of a column as $_.
673  
674 positional arguments:
675 BLOCK a block, map_cell { ... }, run once per row with $_
676 a copy of the cell; $_ is then stored back
677  
678 example:
679 assign([ { x => 'A:1' } ], x => map_cell { s/^[A-Z]:// })
680 # returns [ { x => '1' } ]
681  
682 END
683  
684 221 $SCREEN{Ronly} = <<'END';
685 usage: Ronly(ARRAY [, ARRAY ...])
686  
687 Return the distinct values of the last array that are in no other array.
688  
689 positional arguments:
690 ARRAY an array ref, read as a set; at least one
691  
692 example:
693 Ronly([1, 2, 3], [3, 4, 5])
694 # returns (4, 5), or 2 in scalar context
695  
696 END
697  
698 # Screens, part 3.
699  
700 221 $SCREEN{matrix} = <<'END';
701 usage: matrix(DATA [, NROW] [, NCOL] [, BYROW])
702  
703 Shape a flat list of numbers into a matrix, as an array of rows, like R's.
704  
705 positional arguments:
706 DATA array ref of the cells, filled column by column; also
707 data => DATA
708 NROW number of rows; also nrow => NROW (default: from NCOL,
709 else every cell in one column)
710 NCOL number of columns; also ncol => NCOL (default: from
711 NROW, else 1)
712 BYROW fill row by row instead; also byrow => 1 (default: 0)
713  
714 example:
715 matrix([1..6], 2) # same as matrix(data => [1..6], nrow => 2)
716 # returns [ [1, 3, 5], [2, 4, 6] ]
717  
718 END
719  
720 221 $SCREEN{melt} = <<'END';
721 usage: melt(DF [, id_vars => COLS] [, value_vars => COLS] [, var_name => NAME]
722 [, value_name => NAME] [, output_type => {aoa,aoh,hoa,hoh}])
723  
724 Unpivot a wide data frame into long form, like pandas' DataFrame.melt.
725  
726 positional arguments:
727 DF the data frame: an AoH, AoA, HoA or HoH
728  
729 options:
730 id_vars => COLS a column or array ref of columns kept and repeated down
731 the output (default: none)
732 value_vars => COLS a column or array ref of columns to unpivot (default:
733 every column not in id_vars)
734 var_name => NAME name of the column-name column (default: 'variable')
735 value_name => NAME name of the value column (default: 'value')
736 output_type => TYPE aoa, aoh, hoa or hoh (default: the shape of DF)
737  
738 example:
739 melt([ { A => 'a', B => 1, C => 2 } ], id_vars => 'A')
740 # returns [ { A => 'a', variable => 'B', value => 1 },
741 # { A => 'a', variable => 'C', value => 2 } ]
742  
743 END
744  
745 221 $SCREEN{merge} = <<'END';
746 usage: merge(LEFT, RIGHT [, how => {inner,left,right,outer,cross}]
747 [, on => COLS] [, left_on => COLS, right_on => COLS]
748 [, suffixes => [X, Y]] [, output_type => {aoh,hoa}])
749  
750 Join two data frames on key columns, like R's merge and pandas' DataFrame.merge.
751  
752 positional arguments:
753 LEFT the left data frame: an AoH, HoA or HoH
754 RIGHT the right data frame: an AoH, HoA or HoH
755  
756 options:
757 how => HOW inner, left, right, outer (or full) or cross (default:
758 inner)
759 on => COLS a column or array ref of columns in both frames; also
760 by (default: every column the two share)
761 left_on => COLS the left key columns, given with right_on; also by_x
762 right_on => COLS the right key columns, given with left_on; also by_y
763 suffixes => [X, Y] appended to a non-key column found in both (default:
764 ['.x', '.y'])
765 output_type => TYPE aoh or hoa; also out (default: hoa for a HoA left
766 frame, else aoh)
767  
768 example:
769 merge([ { id => 1, x => 'a' }, { id => 2, x => 'b' } ],
770 [ { id => 1, y => 'c' } ], on => 'id')
771 # returns [ { id => 1, x => 'a', y => 'c' } ]
772  
773 END
774  
775 221 $SCREEN{ncol} = <<'END';
776 usage: ncol(DF)
777  
778 Count the columns of a data frame; a flat array is one column.
779  
780 positional arguments:
781 DF the data frame: an AoH, AoA, HoA, HoH or a plain array
782 ref
783  
784 example:
785 ncol([ { a => 1, b => 2 } ]) # returns 2
786  
787 END
788  
789 221 $SCREEN{nrow} = <<'END';
790 usage: nrow(DF)
791  
792 Count the rows of a data frame; a flat array has one row per element.
793  
794 positional arguments:
795 DF the data frame: an AoH, AoA, HoA, HoH or a plain array
796 ref
797  
798 example:
799 nrow([ { a => 1 }, { a => 2 } ]) # returns 2
800  
801 END
802  
803 221 $SCREEN{pivot_table} = <<'END';
804 usage: pivot_table(DF, columns => COLS [, index => COLS] [, values => COLS]
805 [, aggfunc => FUNC] [, fill_value => X] [, skipna => {0,1}]
806 [, sort => {0,1}] [, sep => STR]
807 [, output_type => {aoa,aoh,hoa,hoh}])
808  
809 Spread a long data frame into a wide one, like pandas' pivot_table.
810  
811 positional arguments:
812 DF the data frame: an AoH, AoA, HoA or HoH
813  
814 options:
815 columns => COLS a column or array ref of columns whose values name the
816 output columns (required)
817 index => COLS a column or array ref of columns that key the output
818 rows (default: none, one row)
819 values => COLS the columns to aggregate (default: every column not in
820 index or columns)
821 aggfunc => FUNC mean, median, sum, sd, var, min, max, count, n,
822 nunique, first, last or mode, a code ref, or an array
823 ref of these (default: mean)
824 fill_value => X put in place of an undef result cell (default: leave it
825 undef)
826 skipna => {0,1} drop undef cells before a numeric reduction (default:
827 1)
828 sort => {0,1} sort the output rows and columns; 0 keeps first-seen
829 order (default: 1)
830 sep => STR joins the pieces of a generated column name (default:
831 '.')
832 output_type => TYPE aoa, aoh, hoa or hoh (default: the shape of DF)
833  
834 example:
835 pivot_table([ { k => 'a', y => 1, v => 2 }, { k => 'a', y => 1, v => 4 } ],
836 index => 'k', columns => 'y', values => 'v')
837 # returns [ { k => 'a', 1 => 3 } ]
838  
839 END
840  
841 221 $SCREEN{qcut} = <<'END';
842 usage: qcut(DATA, Q [, edges => {0,1}] [, codes => {0,1}] [, labels => LABELS]
843 [, duplicates => {raise,drop}])
844  
845 Cut numbers into equal-frequency bins, like pandas' qcut.
846  
847 positional arguments:
848 DATA array ref of numbers; undef is missing
849 Q the number of bins, or an array ref of probabilities in
850 [0, 1]
851  
852 options:
853 edges => {0,1} return the bin edges (default: 1, or 0 when codes are
854 asked for)
855 codes => {0,1} return each value's 0-based bin code (default: 0)
856 labels => LABELS an array ref of one label per bin, or 'interval';
857 implies codes => 1
858 duplicates => MODE raise dies on a repeated edge, drop merges it (default:
859 raise)
860  
861 example:
862 my @edges = qcut([1..8], 4) # returns (1, 2.75, 4.5, 6.25, 8)
863 my $codes = qcut([1..8], 2, codes => 1)
864 # returns [0, 0, 0, 0, 1, 1, 1, 1]
865  
866 END
867  
868 221 $SCREEN{read_table} = <<'END';
869 usage: read_table(FILE [, sep => SEP] [, header => {0,1}] [, col_names => NAMES]
870 [, output_type => {aoa,aoh,hoa,hoh}] [, row_names => COL]
871 [, auto_row_names => NAME] [, comment => STR] [, quote => Q]
872 [, filter => FILTER] [, na_strings => STRS]
873 [, colClasses => CLASSES] [, keep_cols => COLS]
874 [, drop_cols => COLS]
875 [, sheet => SHEET] [, explode => {0,1}])
876  
877 Read a delimited text, VCF or .xlsx file into a data frame, like R's read.table.
878  
879 positional arguments:
880 FILE the file; .gz and .bz2 are read through, .xlsx is read
881 as Excel
882  
883 options:
884 sep => SEP a literal separator or a qr// regex; also delim
885 (default: tab for .tsv and .vcf, else ',')
886 header => {0,1} the first line names the columns (default: 1)
887 col_names => NAMES array ref of column names, used in place of the header
888 (default: the header, or V1, V2, ...)
889 output_type => TYPE aoa, aoh, hoa or hoh (default: aoh; hoh for an exploded
890 VCF)
891 row_names => COL hoh only: the column that keys the rows (default: the
892 first)
893 auto_row_names => NAME
894 read R's write.table output, whose header lacks the
895 row-name field; 1 names the column row_name (default:
896 off)
897 comment => STR lines starting with it are skipped (default: '#', '##'
898 for a VCF)
899 quote => Q '"' quotes fields, '' turns quoting off (default: '"')
900 filter => FILTER a hash ref of code refs by column name or 1-based field
901 (0 is the whole row), or one code ref for the row; a
902 row is kept when every one returns true
903 na_strings => STRS a string or array ref of field texts read as undef;
904 also na_values or undef_val (default: none)
905 colClasses => CLASSES numeric, integer or character: one for all columns, an
906 array ref by position or a hash ref by name (default:
907 text, with an integer such as 42 stored as a number)
908 keep_cols => COLS a column name, a qr// regex, or an array ref of
909 either: only the columns with one of the names, or
910 whose name matches one of the regexes, are stored, in
911 the file's order; a hoh's row_names column is always
912 kept (default: every column is kept)
913 drop_cols => COLS a column name, a qr// regex, or an array ref of
914 either: a column with one of the names, or whose name
915 matches one of the regexes, is left out of the table
916 and never stored (default: every column is kept)
917 sheet => SHEET .xlsx only: a sheet name or 1-based index (default: the
918 first sheet)
919 explode => {0,1} VCF only: split each sample column by its FORMAT keys
920 (default: 1)
921  
922 example:
923 my $aoh = read_table('cohort.csv', sep => ',', output_type => 'aoh')
924 # returns [ { id => 1, age => 41, ... }, ... ], one hash per row
925  
926 END
927  
928 221 $SCREEN{rename_cols} = <<'END';
929 usage: rename_cols(DF, OLD => NEW, ...)
930  
931 Rename columns of a data frame; in void context the frame itself is renamed.
932  
933 positional arguments:
934 DF the data frame: an AoH, HoA or HoH (an AoA has no
935 names)
936 OLD => NEW one or more pairs, or one hash ref { OLD => NEW, ... }
937  
938 example:
939 rename_cols([ { a => 1 } ], a => 'b') # returns [ { b => 1 } ]
940  
941 END
942  
943 221 $SCREEN{rownames} = <<'END';
944 usage: rownames(DF)
945  
946 List the row names of a data frame: a HoH's keys, else 0 .. n-1.
947  
948 positional arguments:
949 DF the data frame: an AoH, AoA, HoA or HoH
950  
951 example:
952 rownames({ r1 => { a => 1 }, r2 => { a => 2 } }) # returns ('r1', 'r2')
953  
954 END
955  
956 221 $SCREEN{select_cols} = <<'END';
957 usage: select_cols(DF, COL, ...)
958  
959 Keep only the named columns of a data frame, in the order given.
960  
961 positional arguments:
962 DF the data frame: an AoH, AoA, HoA or HoH
963 COL one or more column names (positions for an AoA), or one
964 array ref of them
965  
966 example:
967 select_cols([ { a => 1, b => 2 } ], 'a') # returns [ { a => 1 } ]
968  
969 END
970  
971 221 $SCREEN{table_one} = <<'END';
972 usage: table_one(DF [, by => COL] [, vars => COLS] [, types => TYPES]
973 [, nonparametric => {0,1}] [, digits => N] [, pct_digits => N])
974  
975 Build the descriptive "Table 1" of a clinical paper, one row per variable.
976  
977 positional arguments:
978 DF the data frame: an AoH, AoA, HoA or HoH
979  
980 options:
981 by => COL the column whose groups are compared (default: none)
982 vars => COLS array ref of the columns to summarise (default: every
983 column but by)
984 types => TYPES hash ref of column => 'continuous' or 'categorical'
985 (default: continuous when every value is a number)
986 nonparametric => {0,1}
987 Wilcoxon or Kruskal-Wallis in place of t-test or ANOVA
988 (default: 0)
989 digits => N decimal places of a mean and sd (default: 2)
990 pct_digits => N decimal places of a percentage (default: 1)
991  
992 example:
993 table_one([ { arm => 'A', age => 30 }, { arm => 'A', age => 40 },
994 { arm => 'B', age => 50 }, { arm => 'B', age => 60 } ],
995 by => 'arm')
996 # returns [ { variable => 'age', A => '35.00 (7.07)',
997 # B => '55.00 (7.07)', Overall => '45.00 (12.91)',
998 # test => 't-test', ... } ]
999  
1000 END
1001  
1002 221 $SCREEN{transpose} = <<'END';
1003 usage: transpose(DATA)
1004  
1005 Swap the rows and columns of an array of arrays or a hash of hashes.
1006  
1007 positional arguments:
1008 DATA an AoA, whose rows must be one length, or a HoH
1009  
1010 example:
1011 transpose([ [1, 2, 3], [4, 5, 6] ]) # returns [ [1, 4], [2, 5], [3, 6] ]
1012  
1013 END
1014  
1015 221 $SCREEN{uniq} = <<'END';
1016 usage: uniq(VALUE, ...)
1017  
1018 List the distinct values of its arguments, in first-seen order.
1019  
1020 positional arguments:
1021 VALUE scalars or array refs, which are expanded one level
1022  
1023 example:
1024 uniq(1, 2, 2, 3, 1) # returns (1, 2, 3); in scalar context, 3
1025  
1026 END
1027  
1028 221 $SCREEN{vals} = <<'END';
1029 usage: vals(DF, COL)
1030  
1031 Pull one column of a data frame out as an array ref, like pandas' to_list.
1032  
1033 positional arguments:
1034 DF the data frame: an AoH, HoA or HoH (a HoH in sorted key
1035 order)
1036 COL the column name
1037  
1038 example:
1039 vals([ { age => 30 }, { age => 41 } ], 'age') # returns [30, 41]
1040  
1041 END
1042  
1043 221 $SCREEN{value_counts} = <<'END';
1044 usage: value_counts(DATA [, KEY])
1045  
1046 Count how many times each value occurs.
1047  
1048 positional arguments:
1049 DATA a list of values, an array ref, or an AoH, AoA, HoA or
1050 HoH
1051 KEY the column to count: a name, or a position for an AoA
1052  
1053 example:
1054 value_counts('a', 'b', 'b') # returns { a => 1, b => 2 }
1055 value_counts([ { d => 'x' }, { d => 'y' }, { d => 'x' } ], 'd')
1056 # returns { x => 2, y => 1 }
1057  
1058 END
1059  
1060 221 $SCREEN{view} = <<'END';
1061 usage: view(DF [, n => N] [, cols => COLS] [, row_names => COL] [, na => STR]
1062 [, max_width => N] [, ellipsis => STR] [, gap => N] [, width => N]
1063 [, color => {auto,0,1}] [, colors => COLORS] [, to => FH]
1064 [, return_only => {0,1}] [, size => {0,1}])
1065  
1066 Print the first rows of a data frame as an aligned table, like R's head.
1067  
1068 positional arguments:
1069 DF the data frame: an AoH, AoA, HoA or HoH
1070  
1071 options:
1072 n => N rows to show; also rows (default: 6)
1073 cols => COLS array ref fixing which columns show, in order; also
1074 columns
1075 row_names => COL the column used as the row label
1076 na => STR shown for an undef cell (default: 'undef')
1077 max_width => N cut a cell wider than this (default: 80)
1078 ellipsis => STR marks a cut cell (default: '...')
1079 gap => N spaces between columns (default: 2)
1080 width => N terminal width that wide tables are split at (default:
1081 $ENV{COLUMNS}, else 80)
1082 color => MODE auto colours only when printing to a terminal (default:
1083 auto)
1084 colors => COLORS hash ref of colour overrides
1085 to => FH filehandle to print to (default: STDOUT)
1086 return_only => {0,1} return the text and print nothing (default: 0)
1087 size => {0,1} say how much memory the data takes, in the first line
1088 (default: 1)
1089  
1090 example:
1091 my $text = view([ { a => 1, b => 'x' } ], return_only => 1)
1092 # returns the table as a string; view() always returns it
1093  
1094 END
1095  
1096 221 $SCREEN{write_table} = <<'END';
1097 usage: write_table(DATA, FILE [, sep => SEP] [, col_names => NAMES]
1098 [, row_names => ROWS] [, undef_val => STR] [, quiet => {0,1}]
1099 [, tex => {0,1}] [, tex_* => ...] [, xlsx => {0,1}]
1100 [, xlsx_* => ...])
1101  
1102 Write a data frame to a delimited text, LaTeX or .xlsx file.
1103  
1104 positional arguments:
1105 DATA the data frame: an AoH, AoA, HoA, HoH or flat hash;
1106 also data => DATA
1107 FILE the file; .gz and .bz2 compress, .tex and .xlsx pick
1108 the format; also file => FILE
1109  
1110 options:
1111 sep => SEP field separator; also delim (default: tab for .tsv,
1112 else ',')
1113 col_names => NAMES array ref of the columns to write, in order; for an
1114 AoA, its header
1115 row_names => ROWS 1 writes a row-name column, 0 none, a name uses that
1116 column (default: 1 for a HoH, else 0)
1117 undef_val => STR written for an undef cell (default: '')
1118 quiet => {0,1} do not print the "wrote FILE" line (default: 0)
1119 tex => {0,1} write a LaTeX tabular (default: 1 for a .tex FILE)
1120 tex_col_align => A c, l or r for every column (default: c)
1121 tex_size => CMD a size command such as \small
1122 tex_comment => TEXT a string or array ref of % comment lines
1123 tex_bold_1st_col => {0,1}
1124 bold the first column (default: 1)
1125 tex_format => {0,1} print numbers as %.4g (default: 0)
1126 tex_longtable => {0,1}
1127 write a longtable body (default: 0)
1128 tex_longtable_head => H
1129 longtable header rows, with H as the continued caption
1130 xlsx => {0,1} write an Excel workbook (default: 1 for an .xlsx FILE)
1131 xlsx_sheet => NAME the sheet name (default: 'Sheet1')
1132 xlsx_comment => TEXT a string or array ref of lines for the provenance
1133 comment
1134 xlsx_freeze_rows => N leading rows to freeze (default: 1, the header row;
1135 0 for none)
1136 xlsx_freeze_cols => N leading columns to freeze (default: 0)
1137  
1138 example:
1139 write_table([ { id => 1, age => 41 } ], 'cohort.tsv')
1140 # writes cohort.tsv, tab-separated, and returns nothing
1141  
1142 END
1143  
1144 # Screens, part 4.
1145  
1146 221 $SCREEN{min} = <<'END';
1147 usage: min(X [, X ...])
1148  
1149 The smallest of the values, as R's min(); a NaN anywhere makes it NaN.
1150  
1151 positional arguments:
1152 X a number, or an array ref of numbers; every argument is
1153 pooled into one sample
1154  
1155 example:
1156 min(1, [4, 2], 3)
1157 # returns 1
1158  
1159 END
1160  
1161 221 $SCREEN{max} = <<'END';
1162 usage: max(X [, X ...])
1163  
1164 The largest of the values, as R's max(); a NaN anywhere makes it NaN.
1165  
1166 positional arguments:
1167 X a number, or an array ref of numbers; every argument is
1168 pooled into one sample
1169  
1170 example:
1171 max(1, [4, 2], 3)
1172 # returns 4
1173  
1174 END
1175  
1176 221 $SCREEN{mean} = <<'END';
1177 usage: mean(X [, X ...])
1178  
1179 The arithmetic mean of the values, as R's mean().
1180  
1181 positional arguments:
1182 X a number, or an array ref of numbers; every argument is
1183 pooled into one sample
1184  
1185 example:
1186 mean([1, 2], [3, 4])
1187 # returns 2.5
1188  
1189 END
1190  
1191 221 $SCREEN{median} = <<'END';
1192 usage: median(X [, X ...])
1193  
1194 The median of the values, as R's median().
1195  
1196 positional arguments:
1197 X a number, or an array ref of numbers; every argument is
1198 pooled into one sample
1199  
1200 example:
1201 median(3, 1, 2, 10)
1202 # returns 2.5
1203  
1204 END
1205  
1206 221 $SCREEN{sum} = <<'END';
1207 usage: sum(X [, X ...])
1208  
1209 The sum of the values, compensated as R's sum() is.
1210  
1211 positional arguments:
1212 X a number, or an array ref of numbers; every argument is
1213 pooled into one sample
1214  
1215 example:
1216 sum(1, 2, 3, 4)
1217 # returns 10
1218  
1219 END
1220  
1221 221 $SCREEN{sd} = <<'END';
1222 usage: sd(X [, X ...])
1223  
1224 The sample standard deviation (n - 1 denominator), as R's sd().
1225  
1226 positional arguments:
1227 X a number, or an array ref of numbers; every argument is
1228 pooled into one sample; at least two values
1229  
1230 example:
1231 sd(2, 4, 4, 4, 5, 5, 7, 9)
1232 # returns 2.1380899352994
1233  
1234 END
1235  
1236 221 $SCREEN{var} = <<'END';
1237 usage: var(X [, X ...])
1238  
1239 The sample variance (n - 1 denominator), as R's var().
1240  
1241 positional arguments:
1242 X a number, or an array ref of numbers; every argument is
1243 pooled into one sample; at least two values
1244  
1245 example:
1246 var(2, 4, 4, 4, 5, 5, 7, 9)
1247 # returns 4.57142857142857
1248  
1249 END
1250  
1251 221 $SCREEN{mode} = <<'END';
1252 usage: mode(X [, X ...])
1253  
1254 The most common value or values, in the order each was first seen.
1255  
1256 positional arguments:
1257 X a value (number or string), or an array ref of values;
1258 every argument is pooled
1259  
1260 example:
1261 mode('a', 'a', 'c', 'c', 'z')
1262 # returns ('a', 'c')
1263  
1264 END
1265  
1266 221 $SCREEN{skew} = <<'END';
1267 usage: skew(X [, X ...] [, x => ARRAYREF] [, type => {1,2,3}])
1268  
1269 Sample skewness of the values.
1270  
1271 positional arguments:
1272 X a number, or an array ref of numbers; every argument is
1273 pooled into one sample
1274  
1275 options:
1276 x => ARRAYREF the data by name, pooled with any X
1277 type => {1,2,3} the estimator: 1 = the plain moment ratio, 2 = the
1278 adjusted one SAS, SPSS and Excel use, 3 = e1071's
1279 default (default: 2; type 2 needs at least 3 values)
1280  
1281 example:
1282 skew(2, 4, 4, 4, 5, 5, 7, 9)
1283 # returns 0.8184875533568
1284  
1285 END
1286  
1287 221 $SCREEN{kurtosis} = <<'END';
1288 usage: kurtosis(X [, X ...] [, x => ARRAYREF] [, type => {1,2,3}])
1289  
1290 Sample excess kurtosis of the values (a normal sample gives about 0).
1291  
1292 positional arguments:
1293 X a number, or an array ref of numbers; every argument is
1294 pooled into one sample
1295  
1296 options:
1297 x => ARRAYREF the data by name, pooled with any X
1298 type => {1,2,3} the estimator: 1 = the plain moment ratio, 2 = the
1299 adjusted one SAS, SPSS and Excel use, 3 = e1071's
1300 default (default: 2; type 2 needs at least 4 values)
1301  
1302 example:
1303 kurtosis(2, 4, 4, 4, 5, 5, 7, 9)
1304 # returns 0.940625
1305  
1306 END
1307  
1308 221 $SCREEN{quantile} = <<'END';
1309 usage: quantile(X [, probs => ARRAYREF])
1310  
1311 Sample quantiles by R's type 7 interpolation, keyed '25%' and so on.
1312  
1313 positional arguments:
1314 X the data, an array ref; undef values are dropped
1315  
1316 options:
1317 x => ARRAYREF the data by name, in place of X
1318 probs => ARRAYREF probabilities in [0, 1], or one number (default: [0,
1319 0.25, 0.5, 0.75, 1]); an undef or NaN prob gives
1320 undef or NaN under the key ''
1321  
1322 example:
1323 quantile([1 .. 9], probs => [0.25, 0.5])
1324 # returns { '25%' => 3, '50%' => 5 }
1325  
1326 END
1327  
1328 221 $SCREEN{rank} = <<'END';
1329 usage: rank(X [, X ...] [, ties_method => METHOD] [, na_last => WHERE])
1330  
1331 The ranks of the values in input order, as R's rank(); undef and NaN are NA.
1332  
1333 positional arguments:
1334 X a number, or an array ref of numbers; every argument is
1335 pooled into one sample
1336  
1337 options:
1338 ties_method => METHOD how tied values share ranks: average, first, last,
1339 random, max or min (default: average)
1340 na_last => WHERE where NAs go: true (ranked last), false (ranked first),
1341 keep (left undef), or na or undef (dropped) (default:
1342 true)
1343  
1344 example:
1345 rank([3, 1, 4, 1, 5], ties_method => 'min')
1346 # returns (3, 1, 4, 1, 5)
1347  
1348 END
1349  
1350 221 $SCREEN{scale} = <<'END';
1351 usage: scale(X [, X ...] [, center => C] [, scale => S])
1352  
1353 Centre and scale the values, as R's scale(); an AoA is scaled by column.
1354  
1355 positional arguments:
1356 X a number, or an array ref of numbers; every argument is
1357 pooled into one sample, or one array of arrays, a
1358 matrix of rows
1359  
1360 options:
1361 center => C mean, true or 1 subtracts the mean; none, false, 0 or
1362 '' subtracts nothing; any other number is subtracted,
1363 and an array ref gives one number per column
1364 (default: mean)
1365 scale => S sd, true or 1 divides by sqrt(sum(x^2)/(n-1)) of the
1366 centred column, the sd when centred on the mean; none,
1367 false, 0 or '' divides by nothing; any other number,
1368 or an array ref of one per column, is divided by
1369 (default: sd)
1370 { center => C, scale => S }
1371 the same options as a trailing hash ref
1372  
1373 example:
1374 scale(1, 2, 3)
1375 # returns (-1, 0, 1)
1376  
1377 END
1378  
1379 221 $SCREEN{seq} = <<'END';
1380 usage: seq(FROM, TO [, BY])
1381  
1382 A sequence from FROM to TO, as R's seq() (base::seq.default).
1383  
1384 positional arguments:
1385 FROM the first value, a finite number
1386 TO the last value, a finite number, reached exactly or not
1387 passed
1388 BY the step (default: none, which counts by 1 or -1 to TO,
1389 as R's from:to)
1390  
1391 example:
1392 seq(1, 2, 0.25)
1393 # returns (1, 1.25, 1.5, 1.75, 2)
1394  
1395 END
1396  
1397 221 $SCREEN{cov} = <<'END';
1398 usage: cov(X, Y [, METHOD])
1399  
1400 The covariance of two samples, as R's cov().
1401  
1402 positional arguments:
1403 X the first sample, an array ref
1404 Y the second sample, an array ref of the same length
1405 METHOD pearson, spearman or kendall (default: pearson)
1406  
1407 example:
1408 cov([1, 2, 3, 4], [2, 4, 6, 9])
1409 # returns 3.83333333333333
1410  
1411 END
1412  
1413 221 $SCREEN{cor} = <<'END';
1414 usage: cor(X [, Y [, METHOD]])
1415  
1416 The correlation of two samples, or the correlation matrix of one, as R's cor().
1417  
1418 positional arguments:
1419 X a sample (an array ref), or a matrix (an array of
1420 arrays of rows)
1421 Y a second sample, a matrix with as many rows as X, or
1422 undef to leave it out (default: undef)
1423 METHOD pearson, spearman or kendall (default: pearson)
1424  
1425 example:
1426 cor([1, 2, 3, 4], [2, 4, 6, 8], 'spearman')
1427 # returns 1
1428  
1429 END
1430  
1431 221 $SCREEN{hist} = <<'END';
1432 usage: hist(X [, breaks => N])
1433  
1434 Histogram counts over R's pretty() breakpoints, as R's hist().
1435  
1436 positional arguments:
1437 X the data, an array ref of numbers; non-finite values
1438 are dropped
1439  
1440 options:
1441 breaks => N the suggested number of bins, also accepted as a bare
1442 second argument (default: Sturges' rule,
1443 ceiling(log2(n) + 1))
1444  
1445 example:
1446 hist([1, 2, 2, 3, 3, 3, 4, 4, 5], breaks => 4)
1447 # returns { breaks => [1, 2, 3, 4, 5], counts => [3, 3, 2, 1],
1448 # mids => [...], density => [...] }
1449  
1450 END
1451  
1452 221 $SCREEN{density} = <<'END';
1453 usage: density(X [, bw => BW] [, adjust => A] [, kernel => K] [, n => N]
1454 [, weights => ARRAYREF] [, from => F] [, to => T] [, cut => C]
1455 [, OPTION => VALUE ...])
1456  
1457 Kernel density estimate of a sample, as R's density().
1458  
1459 positional arguments:
1460 X the data, an array ref of numbers
1461  
1462 options:
1463 x => ARRAYREF the data by name, in place of X
1464 bw => BW the bandwidth: a number, or a rule: nrd0, nrd, ucv,
1465 bcv, SJ, SJ-ste or SJ-dpi (default: nrd0)
1466 adjust => A a multiplier on the bandwidth (default: 1)
1467 kernel => K the kernel: gaussian, epanechnikov, rectangular,
1468 triangular, biweight, cosine or optcosine (default:
1469 gaussian)
1470 n => N the number of points the estimate is given at (default:
1471 512)
1472 weights => ARRAYREF a non-negative weight for each value (default: equal
1473 weights)
1474 from => F, to => T the ends of the grid (default: cut bandwidths beyond
1475 the smallest and largest value)
1476 cut => C how many bandwidths the grid runs past the data
1477 (default: 3)
1478 na_rm => BOOL drop undef and NaN values rather than die (default: 0)
1479 width => W the kernel's support, used when bw is not given
1480 (default: none)
1481 window => K the kernel, as R's window (default: none)
1482 ext => E, nb => NB as R's density(): grid extension (default: 4) and bins
1483 for the bandwidth rules (default: 1000)
1484 give_rkern => BOOL return R(K), the kernel's roughness, and no estimate
1485 (default: 0)
1486 subdensity => BOOL allow weights that sum to less than 1 (default: 0)
1487 warn_wbw => BOOL warn when weights are given with a bw rule (default:
1488 true when the weights vary)
1489 old_coords => BOOL R's coordinates before R 4.4.0 (default: 0)
1490  
1491 example:
1492 density([1, 2, 3, 4, 5], n => 4)
1493 # returns { x => [-1.92075386855191, 1.3597487104827, ...],
1494 # y => [...], bw => 0.973584622850636, ... }
1495  
1496 END
1497  
1498 221 $SCREEN{bw_nrd0} = <<'END';
1499 usage: bw_nrd0(X)
1500  
1501 Silverman's rule-of-thumb bandwidth, as R's bw.nrd0().
1502  
1503 positional arguments:
1504 X the data, an array ref of at least two finite numbers
1505  
1506 options:
1507 x => ARRAYREF the data by name, in place of X
1508  
1509 example:
1510 bw_nrd0([1, 2, 3, 4, 5])
1511 # returns 0.973584622850636
1512  
1513 END
1514  
1515 221 $SCREEN{bw_nrd} = <<'END';
1516 usage: bw_nrd(X)
1517  
1518 Scott's variant of the rule-of-thumb bandwidth, as R's bw.nrd().
1519  
1520 positional arguments:
1521 X the data, an array ref of at least two finite numbers
1522  
1523 options:
1524 x => ARRAYREF the data by name, in place of X
1525  
1526 example:
1527 bw_nrd([1, 2, 3, 4, 5])
1528 # returns 1.14666633357964
1529  
1530 END
1531  
1532 221 $SCREEN{bw_ucv} = <<'END';
1533 usage: bw_ucv(X [, nb => NB] [, lower => L] [, upper => U] [, tol => TOL])
1534  
1535 Bandwidth by unbiased cross-validation, as R's bw.ucv().
1536  
1537 positional arguments:
1538 X the data, an array ref of at least two finite numbers
1539  
1540 options:
1541 x => ARRAYREF the data by name, in place of X
1542 nb => NB the number of bins (default: 1000)
1543 lower => L the low end of the search (default: 0.1 * hmax)
1544 upper => U the high end of the search (default: hmax, from the
1545 data)
1546 tol => TOL the search's tolerance (default: 0.1 * lower)
1547  
1548 example:
1549 bw_ucv([1, 2, 3, 4, 5, 10, 11, 12, 13, 14])
1550 # returns 2.29000986442776
1551  
1552 END
1553  
1554 221 $SCREEN{bw_bcv} = <<'END';
1555 usage: bw_bcv(X [, nb => NB] [, lower => L] [, upper => U] [, tol => TOL])
1556  
1557 Bandwidth by biased cross-validation, as R's bw.bcv().
1558  
1559 positional arguments:
1560 X the data, an array ref of at least two finite numbers
1561  
1562 options:
1563 x => ARRAYREF the data by name, in place of X
1564 nb => NB the number of bins (default: 1000)
1565 lower => L the low end of the search (default: 0.1 * hmax)
1566 upper => U the high end of the search (default: hmax, from the
1567 data)
1568 tol => TOL the search's tolerance (default: 0.1 * lower)
1569  
1570 example:
1571 bw_bcv([2, 10, 10, (11) x 4, 12, 12, 13, (14) x 4, (15) x 5, (16) x 3,
1572 (17) x 4, 18, 19, 20, 27])
1573 # returns 2.29124659635325
1574  
1575 END
1576  
1577 221 $SCREEN{bw_sj} = <<'END';
1578 usage: bw_sj(X [, method => {ste,dpi}] [, nb => NB] [, lower => L]
1579 [, upper => U] [, tol => TOL])
1580  
1581 The Sheather & Jones bandwidth, as R's bw.SJ().
1582  
1583 positional arguments:
1584 X the data, an array ref of at least two finite numbers
1585  
1586 options:
1587 x => ARRAYREF the data by name, in place of X
1588 method => {ste,dpi} solve-the-equation or direct plug-in (default: ste)
1589 nb => NB the number of bins (default: 1000)
1590 lower => L the low end of the search (default: 0.1 * hmax, widened
1591 until it brackets the answer)
1592 upper => U the high end of the search (default: hmax, from the
1593 data, widened the same way)
1594 tol => TOL the search's tolerance (default: 0.1 * lower)
1595  
1596 example:
1597 bw_sj([1, 2, 3, 4, 5, 10, 11, 12, 13, 14], method => 'dpi')
1598 # returns 2.30587442647329
1599  
1600 END
1601  
1602 221 $SCREEN{summary} = <<'END';
1603 usage: summary(DATA [, nrows => N] [, return_only => BOOL]
1604 [, VIEW_OPTION => VALUE ...])
1605  
1606 Count, quartiles, median and mean of each numeric variable, as R's summary().
1607  
1608 positional arguments:
1609 DATA a list of numbers, or a ref to a vector, an AoA, AoH,
1610 HoA or HoH
1611  
1612 options:
1613 nrows => N the most rows to show; also nrow, n or rows (default:
1614 10)
1615 return_only => BOOL return the table without printing it (default: 0)
1616 color => BOOL colour the table (default: on when printing to a
1617 terminal)
1618 VIEW_OPTION na, colors, max_width, ellipsis, gap, width or to, as
1619 view() takes them
1620  
1621 example:
1622 summary([1, 2, 3, 4, 5], return_only => 1)
1623 # returns the table as a string: 5 values, Min. 1, Median 3, Max. 5
1624  
1625 END
1626  
1627 # Screens, part 5.
1628  
1629 221 $SCREEN{dnorm} = <<'END';
1630 usage: dnorm(X [, mean => MEAN] [, sd => SD] [, log => BOOL])
1631  
1632 The normal density at X, as R's dnorm().
1633  
1634 positional arguments:
1635 X a number, or an array reference of them, which gives
1636 one back (an undef in it is NaN)
1637  
1638 options:
1639 mean => MEAN mean of the distribution (default: 0)
1640 sd => SD standard deviation (default: 1)
1641 log => BOOL return the log of the density (default: 0)
1642  
1643 example:
1644 dnorm(0)
1645 # returns 0.398942280401433
1646  
1647 END
1648  
1649 221 $SCREEN{pnorm} = <<'END';
1650 usage: pnorm(Q [, mean => MEAN] [, sd => SD] [, lower => BOOL] [, log => BOOL])
1651  
1652 The normal distribution function at Q, as R's pnorm().
1653  
1654 positional arguments:
1655 Q a number, or an array reference of them, which gives
1656 one back (an undef in it is NaN)
1657  
1658 options:
1659 mean => MEAN mean of the distribution (default: 0)
1660 sd => SD standard deviation (default: 1)
1661 lower => BOOL 1 for the lower tail, 0 for the upper (default: 1);
1662 also spelled lower_tail
1663 log => BOOL return the log of the probability (default: 0); also
1664 spelled log_p
1665  
1666 example:
1667 pnorm(1.96)
1668 # returns 0.97500210485178
1669  
1670 END
1671  
1672 221 $SCREEN{qnorm} = <<'END';
1673 usage: qnorm(P [, MEAN [, SD]] [, lower => BOOL] [, log => BOOL])
1674  
1675 The normal quantile function at P, as R's qnorm(): the inverse of pnorm().
1676  
1677 positional arguments:
1678 P a probability, or an array reference of them, which
1679 gives one back (an undef in it is NaN)
1680 MEAN mean of the distribution (default: 0); or mean => MEAN
1681 SD standard deviation (default: 1); or sd => SD
1682  
1683 options:
1684 lower => BOOL 1 for the lower tail, 0 for the upper (default: 1);
1685 also spelled lower_tail
1686 log => BOOL P is given as a log (default: 0); also spelled log_p
1687  
1688 example:
1689 qnorm(0.975)
1690 # returns 1.95996398454005
1691  
1692 END
1693  
1694 221 $SCREEN{pt} = <<'END';
1695 usage: pt(Q, DF [, lower => BOOL] [, log => BOOL])
1696  
1697 The Student t distribution function at Q, as R's pt().
1698  
1699 positional arguments:
1700 Q a number, or an array reference of them, which gives
1701 one back (an undef in it is NaN)
1702 DF degrees of freedom (required); or df => DF
1703  
1704 options:
1705 lower => BOOL 1 for the lower tail, 0 for the upper (default: 1);
1706 also spelled lower_tail
1707 log => BOOL return the log of the probability (default: 0); also
1708 spelled log_p
1709  
1710 example:
1711 pt(2.5, 10)
1712 # returns 0.984276577881696
1713  
1714 END
1715  
1716 221 $SCREEN{qt} = <<'END';
1717 usage: qt(P, DF [, lower => BOOL] [, log => BOOL])
1718  
1719 The Student t quantile function at P, as R's qt().
1720  
1721 positional arguments:
1722 P a probability, or an array reference of them, which
1723 gives one back (an undef in it is NaN)
1724 DF degrees of freedom (required); or df => DF
1725  
1726 options:
1727 lower => BOOL 1 for the lower tail, 0 for the upper (default: 1);
1728 also spelled lower_tail
1729 log => BOOL P is given as a log (default: 0); also spelled log_p
1730  
1731 example:
1732 qt(0.975, 10)
1733 # returns 2.22813885198627
1734  
1735 END
1736  
1737 221 $SCREEN{pchisq} = <<'END';
1738 usage: pchisq(Q, DF [, lower => BOOL] [, log => BOOL])
1739  
1740 The chi-square distribution function at Q, as R's pchisq().
1741  
1742 positional arguments:
1743 Q a number, or an array reference of them, which gives
1744 one back (an undef in it is NaN)
1745 DF degrees of freedom (required); or df => DF
1746  
1747 options:
1748 lower => BOOL 1 for the lower tail, 0 for the upper (default: 1);
1749 also spelled lower_tail
1750 log => BOOL return the log of the probability (default: 0); also
1751 spelled log_p
1752  
1753 example:
1754 pchisq(3.84, 1)
1755 # returns 0.949956478751295
1756  
1757 END
1758  
1759 221 $SCREEN{qchisq} = <<'END';
1760 usage: qchisq(P, DF [, lower => BOOL] [, log => BOOL])
1761  
1762 The chi-square quantile function at P, as R's qchisq().
1763  
1764 positional arguments:
1765 P a probability, or an array reference of them, which
1766 gives one back (an undef in it is NaN)
1767 DF degrees of freedom (required); or df => DF
1768  
1769 options:
1770 lower => BOOL 1 for the lower tail, 0 for the upper (default: 1);
1771 also spelled lower_tail
1772 log => BOOL P is given as a log (default: 0); also spelled log_p
1773  
1774 example:
1775 qchisq(0.95, 1)
1776 # returns 3.84145882069412
1777  
1778 END
1779  
1780 221 $SCREEN{pf} = <<'END';
1781 usage: pf(Q, DF1, DF2 [, lower => BOOL] [, log => BOOL])
1782  
1783 The F distribution function at Q, as R's pf().
1784  
1785 positional arguments:
1786 Q a number, or an array reference of them, which gives
1787 one back (an undef in it is NaN)
1788 DF1 numerator degrees of freedom (required); or df1 => DF1
1789 DF2 denominator degrees of freedom (required); or df2 =>
1790 DF2
1791  
1792 options:
1793 lower => BOOL 1 for the lower tail, 0 for the upper (default: 1);
1794 also spelled lower_tail
1795 log => BOOL return the log of the probability (default: 0); also
1796 spelled log_p
1797  
1798 example:
1799 pf(3, 2, 10)
1800 # returns 0.904632568359375
1801  
1802 END
1803  
1804 221 $SCREEN{qf} = <<'END';
1805 usage: qf(P, DF1, DF2 [, lower => BOOL] [, log => BOOL])
1806  
1807 The F quantile function at P, as R's qf().
1808  
1809 positional arguments:
1810 P a probability, or an array reference of them, which
1811 gives one back (an undef in it is NaN)
1812 DF1 numerator degrees of freedom (required); or df1 => DF1
1813 DF2 denominator degrees of freedom (required); or df2 =>
1814 DF2
1815  
1816 options:
1817 lower => BOOL 1 for the lower tail, 0 for the upper (default: 1);
1818 also spelled lower_tail
1819 log => BOOL P is given as a log (default: 0); also spelled log_p
1820  
1821 example:
1822 qf(0.95, 2, 10)
1823 # returns 4.1028210151304
1824  
1825 END
1826  
1827 221 $SCREEN{pbinom} = <<'END';
1828 usage: pbinom(Q, SIZE, PROB [, lower => BOOL] [, log => BOOL])
1829  
1830 The binomial distribution function at Q, as R's pbinom().
1831  
1832 positional arguments:
1833 Q a number, or an array reference of them, which gives
1834 one back (an undef in it is NaN)
1835 SIZE number of trials (required); or size => SIZE
1836 PROB probability of success on each trial (required); or
1837 prob => PROB
1838  
1839 options:
1840 lower => BOOL 1 for the lower tail, 0 for the upper (default: 1);
1841 also spelled lower_tail
1842 log => BOOL return the log of the probability (default: 0); also
1843 spelled log_p
1844  
1845 example:
1846 pbinom(3, 10, 0.25)
1847 # returns 0.775875091552734
1848  
1849 END
1850  
1851 221 $SCREEN{ptukey} = <<'END';
1852 usage: ptukey(Q, NMEANS, DF [, nranges => N] [, lower_tail => BOOL]
1853 [, log_p => BOOL])
1854  
1855 The studentized range distribution function at Q, as R's ptukey().
1856  
1857 positional arguments:
1858 Q the studentized range, a number
1859 NMEANS number of groups
1860 DF degrees of freedom
1861  
1862 options:
1863 nranges => N number of groups whose range is taken (default: 1)
1864 lower_tail => BOOL 1 for the lower tail, 0 for the upper (default: 1)
1865 log_p => BOOL return the log of the probability (default: 0)
1866  
1867 example:
1868 ptukey(3.5, 3, 12)
1869 # returns 0.930004514724551
1870  
1871 END
1872  
1873 221 $SCREEN{qtukey} = <<'END';
1874 usage: qtukey(P, NMEANS, DF [, nranges => N] [, lower_tail => BOOL]
1875 [, log_p => BOOL])
1876  
1877 The studentized range quantile function at P, as R's qtukey().
1878  
1879 positional arguments:
1880 P a probability, a number
1881 NMEANS number of groups
1882 DF degrees of freedom
1883  
1884 options:
1885 nranges => N number of groups whose range is taken (default: 1)
1886 lower_tail => BOOL 1 for the lower tail, 0 for the upper (default: 1)
1887 log_p => BOOL P is given as a log (default: 0)
1888  
1889 example:
1890 qtukey(0.95, 3, 12)
1891 # returns 3.77292895940834
1892  
1893 END
1894  
1895 221 $SCREEN{rbinom} = <<'END';
1896 usage: rbinom(n => N, size => SIZE, prob => PROB)
1897  
1898 Draw N binomial variates, as R's rbinom(); all three are required.
1899  
1900 options:
1901 n => N number of draws
1902 size => SIZE number of trials in each draw
1903 prob => PROB probability of success, in [0, 1]
1904  
1905 example:
1906 rbinom(n => 3, size => 10, prob => 0.5)
1907 # returns an array reference of 3 whole numbers in 0 .. 10
1908  
1909 END
1910  
1911 221 $SCREEN{rnorm} = <<'END';
1912 usage: rnorm(N [, MEAN [, SD]])
1913  
1914 Draw N normal variates, as R's rnorm(); each may also be given by name.
1915  
1916 positional arguments:
1917 N number of draws (required); or n => N
1918 MEAN mean (default: 0); or mean => MEAN
1919 SD standard deviation, >= 0 (default: 1); or sd => SD
1920  
1921 example:
1922 rnorm(3, 10, 2)
1923 # returns an array reference of 3 numbers drawn from N(10, 2^2)
1924  
1925 END
1926  
1927 221 $SCREEN{runif} = <<'END';
1928 usage: runif(N [, MIN [, MAX]])
1929  
1930 Draw N uniform variates, as R's runif(); each may also be given by name.
1931  
1932 positional arguments:
1933 N number of draws (required); or n => N
1934 MIN lower bound (default: 0); or min => MIN
1935 MAX upper bound (default: 1); or max => MAX
1936  
1937 example:
1938 runif(3, 0, 10)
1939 # returns an array reference of 3 numbers in [0, 10)
1940  
1941 END
1942  
1943 221 $SCREEN{sample} = <<'END';
1944 usage: sample(DATA [, N])
1945  
1946 Draw N elements of an array, or N keys of a hash, without replacement.
1947  
1948 positional arguments:
1949 DATA an array reference, or a hash reference
1950 N how many to draw, at most the number there are
1951 (default: 1)
1952  
1953 example:
1954 sample([10, 20, 30], 2)
1955 # returns an array reference of 2 of the values, such as [30, 10]
1956 sample({ a => 1, b => 2, c => 3 }, 2)
1957 # returns a hash reference of 2 of the pairs, such as { c => 3, a => 1 }
1958  
1959 END
1960  
1961 221 $SCREEN{power_t_test} = <<'END';
1962 usage: power_t_test([n => N] [, delta => DELTA] [, sd => SD]
1963 [, sig_level => ALPHA] [, power => POWER]
1964 [, type => {two.sample,one.sample,paired}]
1965 [, alternative => {two.sided,one.sided,greater,less}]
1966 [, strict => BOOL] [, tol => TOL])
1967  
1968 As R's power.t.test(): whichever one of the first five is undef is solved for.
1969  
1970 options:
1971 n => N observations per group, at least 2
1972 delta => DELTA true difference in means
1973 sd => SD standard deviation (default: 1)
1974 sig_level => ALPHA significance level, in [0, 1] (default: 0.05)
1975 power => POWER power of the test, in [0, 1]; left out, it is solved
1976 for
1977 type => TYPE two.sample, one.sample or paired (default: two.sample)
1978 alternative => ALT two.sided, one.sided, greater or less (default:
1979 two.sided)
1980 strict => BOOL count both tails in a two-sided power (default: 0)
1981 tol => TOL relative tolerance on a solved-for root (default:
1982 1e-12)
1983  
1984 example:
1985 power_t_test(n => 20, delta => 1)
1986 # returns { power => 0.868952801692123, n => 20, delta => 1, ... }
1987  
1988 END
1989  
1990 221 $SCREEN{p_adjust} = <<'END';
1991 usage: p_adjust(P [, METHOD] [, columns => COLS])
1992  
1993 Adjust p-values for multiple testing, as R's p.adjust().
1994  
1995 positional arguments:
1996 P an array reference of p-values, or an AoA, AoH, HoA or
1997 HoH data frame
1998 METHOD holm, hochberg, hommel, bonferroni, BH, BY, fdr or
1999 none, in any case (default: holm); or method => METHOD
2000  
2001 options:
2002 columns => COLS the column, or an array reference of the columns,
2003 holding p-values in a frame (default: all of them);
2004 also spelled column, cols or col
2005  
2006 example:
2007 p_adjust([0.01, 0.04, 0.03, 0.2], 'BH')
2008 # returns (0.04, 0.0533333333333333, 0.0533333333333333, 0.2)
2009  
2010 END
2011  
2012 # Screens, part 6.
2013  
2014 221 $SCREEN{binom_test} = <<'END';
2015 usage: binom_test(X, N [, p => P] [, alternative => {two.sided,less,greater}]
2016 [, conf_level => LEVEL])
2017  
2018 Exact binomial test of X successes in N trials against a success rate P.
2019  
2020 positional arguments:
2021 X the number of successes, or [SUCCESSES, FAILURES]
2022 N the number of trials; left out when X is an array ref
2023  
2024 options:
2025 p => P the success rate under the null (default: 0.5)
2026 alternative => ALT two.sided, less or greater (default: two.sided)
2027 conf_level => LEVEL confidence level of conf_int (default: 0.95)
2028  
2029 example:
2030 binom_test(6, 10, p => 0.5)
2031 # returns { p_value => 0.7539, estimate => 0.6, conf_int => [...], ... }
2032  
2033 END
2034  
2035 221 $SCREEN{chisq_test} = <<'END';
2036 usage: chisq_test(DATA [, correct => BOOL] [, p => PROBS]
2037 [, rescale_p => BOOL])
2038  
2039 Pearson's chi-squared test: goodness of fit for a 1D table, independence for 2D.
2040  
2041 positional arguments:
2042 DATA counts: an array ref or hash ref (goodness of fit),
2043 or an AoA or HoH (a contingency table)
2044  
2045 options:
2046 correct => BOOL Yates' continuity correction, 2x2 tables only
2047 (default: 1)
2048 p => PROBS null probabilities for goodness of fit, an array ref
2049 in DATA's order or a hash ref keyed as DATA
2050 (default: uniform)
2051 rescale_p => BOOL divide p by its sum first (default: 0)
2052  
2053 example:
2054 chisq_test([89, 37, 30, 28, 2], p => [0.40, 0.20, 0.20, 0.19, 0.01])
2055 # returns { statistic => { 'X-squared' => 5.7947 },
2056 # parameter => { df => 4 }, p_value => 0.2150, ... }
2057  
2058 END
2059  
2060 221 $SCREEN{cmh_test} = <<'END';
2061 usage: cmh_test(STRATA [, correct => BOOL] [, conf_level => LEVEL])
2062  
2063 Cochran-Mantel-Haenszel test of association across stratified 2x2 tables.
2064  
2065 positional arguments:
2066 STRATA an array ref of 2x2 tables, each [a, b, c, d] as in
2067 epi_2x2
2068  
2069 options:
2070 correct => BOOL continuity correction (default: 1)
2071 conf_level => LEVEL confidence level of the common odds ratio's conf_int
2072 (default: 0.95)
2073  
2074 example:
2075 cmh_test([ [10, 3, 5, 12], [8, 4, 6, 9] ])
2076 # returns { statistic => 6.2823, p_value => 0.0122, estimate => 4.8,
2077 # conf_int => [...], k => 2, ... }
2078  
2079 END
2080  
2081 221 $SCREEN{cor_test} = <<'END';
2082 usage: cor_test(X, Y [, method => {pearson,kendall,spearman}]
2083 [, alternative => {two.sided,less,greater}] [, exact => BOOL]
2084 [, conf_level => LEVEL] [, continuity => BOOL])
2085  
2086 Test for correlation between paired samples, over their complete pairs.
2087  
2088 positional arguments:
2089 X, Y two array refs of the same length; may also be given
2090 as x => X, y => Y
2091  
2092 options:
2093 method => METHOD pearson, kendall or spearman (default: pearson)
2094 alternative => ALT two.sided, less or greater (default: two.sided)
2095 exact => BOOL exact p-value for kendall and spearman (default: as
2096 R decides, from n and ties)
2097 conf_level => LEVEL confidence level of pearson's conf_int
2098 (default: 0.95)
2099 continuity => BOOL continuity correction for kendall and spearman's
2100 normal approximation (default: 0)
2101  
2102 example:
2103 cor_test([1, 2, 3, 4, 5], [2, 1, 4, 3, 6])
2104 # returns { estimate => 0.8220, statistic => 2.5, parameter => 3,
2105 # p_value => 0.0877, conf_int => [...], ... }
2106  
2107 END
2108  
2109 221 $SCREEN{fisher_test} = <<'END';
2110 usage: fisher_test(TABLE [, alternative => {two.sided,less,greater}]
2111 [, conf_level => LEVEL])
2112  
2113 Fisher's exact test of independence in an R x C table of counts.
2114  
2115 positional arguments:
2116 TABLE counts, at least 2x2: an AoA, or a HoH of rows
2117  
2118 options:
2119 alternative => ALT two.sided, less or greater; 2x2 tables only
2120 (default: two.sided)
2121 conf_level => LEVEL confidence level of the odds ratio's conf_int, 2x2
2122 tables only (default: 0.95)
2123  
2124 example:
2125 fisher_test([ [10, 2], [3, 15] ])
2126 # returns { p_value => 0.000537, estimate => { 'odds ratio' => 21.3053 },
2127 # conf_int => [2.7534, 300.6828], ... }
2128  
2129 END
2130  
2131 221 $SCREEN{kruskal_test} = <<'END';
2132 usage: kruskal_test(X, G | GROUPS)
2133  
2134 Kruskal-Wallis rank-sum test that every group has the same distribution.
2135  
2136 positional arguments:
2137 X an array ref of observations; also x => X
2138 G an array ref of group labels, as long as X; also
2139 g => G
2140 GROUPS instead of X and G, a hash ref of array refs, one
2141 per group; also h => GROUPS
2142  
2143 example:
2144 kruskal_test({ normal => [2.9, 3.0, 2.5, 2.6, 3.2],
2145 airway => [3.8, 2.7, 4.0, 2.4],
2146 asbestosis => [2.8, 3.4, 3.7, 2.2, 2.0] })
2147 # returns { statistic => 0.7714, parameter => 2, p_value => 0.6800,
2148 # group_stats => { size => {...}, mean => {...} }, ... }
2149  
2150 END
2151  
2152 221 $SCREEN{ks_test} = <<'END';
2153 usage: ks_test(X, Y | CDF [, alternative => {two.sided,less,greater}]
2154 [, exact => BOOL])
2155  
2156 Kolmogorov-Smirnov test: two samples, or one sample against a reference CDF.
2157  
2158 positional arguments:
2159 X an array ref of observations; also x => X
2160 Y a second array ref, for the two-sample test; also
2161 y => Y
2162 CDF instead of Y, the name of a reference CDF for the
2163 one-sample test; only 'pnorm' (standard normal)
2164  
2165 options:
2166 alternative => ALT two.sided, less or greater (default: two.sided)
2167 exact => BOOL exact p-value, 1, or asymptotic, 0 (default: exact
2168 when nx*ny < 10000, or n < 100 for one sample)
2169  
2170 example:
2171 ks_test([0.61, 0.29, 0.06, 0.59, -1.73], [-0.4, 1.9, 2.3, 1.1, 3.0])
2172 # returns { statistic => 0.8, p_value => 0.0794, method => ...,
2173 # alternative => 'two.sided' }
2174  
2175 END
2176  
2177 221 $SCREEN{oneway_test} = <<'END';
2178 usage: oneway_test(DATA [, var_equal => BOOL] [, formula => FORMULA])
2179  
2180 One-way test for equal group means; Welch's, unequal variances, by default.
2181  
2182 positional arguments:
2183 DATA the groups: a hash of arrays, one key per group, or
2184 an array of arrays; with formula, a hash of columns
2185  
2186 options:
2187 var_equal => BOOL assume equal variances, the classic F test
2188 (default: 0, Welch's test)
2189 formula => FORMULA 'response ~ factor', splitting DATA's response
2190 column by its factor column; hash DATA only
2191  
2192 example:
2193 oneway_test({ a => [5.5, 5.4, 5.8], b => [4.5, 4.8, 4.2],
2194 c => [6.1, 6.6, 5.9] })
2195 # returns { Group => { 'F value' => 18.5772, 'Pr(>F)' => 0.0110, ... },
2196 # Residuals => { Df => 3.7886, ... }, group_stats => {...} }
2197  
2198 END
2199  
2200 221 $SCREEN{prop_test} = <<'END';
2201 usage: prop_test(X, N [, p => P] [, alternative => {two.sided,less,greater}]
2202 [, conf_level => LEVEL] [, correct => BOOL])
2203  
2204 Test of one proportion against P, or of two or more proportions for equality.
2205  
2206 positional arguments:
2207 X successes: a number, or an array ref with one per
2208 group
2209 N trials: a number, or an array ref as long as X
2210  
2211 options:
2212 p => P null probability, one number or one per group
2213 (default: 0.5 for one group, else the pooled rate)
2214 alternative => ALT two.sided, less or greater (default: two.sided)
2215 conf_level => LEVEL confidence level of conf_int (default: 0.95)
2216 correct => BOOL Yates' continuity correction, one or two groups only
2217 (default: 1)
2218  
2219 example:
2220 prop_test([83, 90], [100, 100])
2221 # returns { statistic => 1.5414, parameter => 1, p_value => 0.2144,
2222 # estimate => [0.83, 0.9], conf_int => [...], ... }
2223  
2224 END
2225  
2226 221 $SCREEN{mcnemar_test} = <<'END';
2227 usage: mcnemar_test(TABLE | X, Y [, correct => BOOL] [, exact => BOOL])
2228  
2229 McNemar's test of symmetry for paired categorical data.
2230  
2231 positional arguments:
2232 TABLE a square k x k matrix of counts, as an AoA
2233 X, Y two array refs of paired observations, the same
2234 length, cross-tabulated over their levels
2235  
2236 options:
2237 correct => BOOL Yates' continuity correction, 2x2 only (default: 1)
2238 exact => BOOL exact binomial test instead, 2x2 only (default: 0)
2239  
2240 example:
2241 mcnemar_test([ [794, 86], [150, 570] ])
2242 # returns { statistic => 16.8178, parameter => 1, p_value => 4.1e-05,
2243 # method => ... }
2244  
2245 END
2246  
2247 221 $SCREEN{friedman_test} = <<'END';
2248 usage: friedman_test(MATRIX)
2249  
2250 Friedman rank-sum test for an unreplicated complete block design.
2251  
2252 positional arguments:
2253 MATRIX an array ref of rows, one block (subject) per row and
2254 one treatment (condition) per column
2255  
2256 example:
2257 friedman_test([ [7, 9, 8], [6, 6, 7], [9, 10, 9], [8, 8, 6] ])
2258 # returns { statistic => 2, parameter => 2, p_value => 0.3679,
2259 # n => 4, ... }
2260  
2261 END
2262  
2263 221 $SCREEN{dunn_test} = <<'END';
2264 usage: dunn_test(VALUES, GROUPS
2265 [, method => {none,bonferroni,sidak,holm,hs,bh,by}])
2266  
2267 Dunn's post-hoc test: every pairwise comparison after a Kruskal-Wallis test.
2268  
2269 positional arguments:
2270 VALUES an array ref of numeric observations
2271 GROUPS an array ref of group labels, as long as VALUES
2272  
2273 options:
2274 method => METHOD p-value adjustment: none, bonferroni, sidak, holm,
2275 hs (Holm-Sidak), bh (also fdr) or by (default: holm)
2276  
2277 example:
2278 dunn_test([2.1, 3.4, 1.9, 6.1, 7.3, 5.9], ['A', 'A', 'A', 'B', 'B', 'B'])
2279 # returns [ { comparison => 'A - B', Z => -1.9640, p_value => 0.0495,
2280 # p_adjust => 0.0495, ... } ], one hash per pair
2281  
2282 END
2283  
2284 221 $SCREEN{shapiro_test} = <<'END';
2285 usage: shapiro_test(X)
2286  
2287 Shapiro-Wilk test of whether a sample is normally distributed.
2288  
2289 positional arguments:
2290 X an array ref of 3 to 5000 numbers, once undef and
2291 NaN are dropped
2292  
2293 example:
2294 shapiro_test([1, 2, 3, 4, 5])
2295 # returns { W => 0.9868, statistic => 0.9868, p_value => 0.9672 }
2296  
2297 END
2298  
2299 221 $SCREEN{t_test} = <<'END';
2300 usage: t_test(X [, Y] [, mu => MU] [, paired => BOOL] [, var_equal => BOOL]
2301 [, alternative => {two.sided,less,greater}]
2302 [, conf_level => LEVEL])
2303  
2304 Student's or Welch's t-test: one sample, two samples, or paired.
2305  
2306 positional arguments:
2307 X an array ref of the first sample; also x => X
2308 Y an array ref of the second sample, for a two-sample
2309 or paired test; also y => Y
2310  
2311 options:
2312 mu => MU the mean, or difference of means, under the null
2313 (default: 0)
2314 paired => BOOL paired test; X and Y the same length (default: 0)
2315 var_equal => BOOL pooled variance instead of Welch's (default: 0)
2316 alternative => ALT two.sided, less or greater (default: two.sided)
2317 conf_level => LEVEL confidence level of conf_int, 0 to 1
2318 (default: 0.95)
2319  
2320 example:
2321 t_test([5.1, 4.9, 5.6, 5.8, 6.0], mu => 5)
2322 # returns { statistic => 2.3041, df => 4, p_value => 0.0826,
2323 # estimate => 5.48, conf_int => [4.9016, 6.0584], ... }
2324  
2325 END
2326  
2327 221 $SCREEN{var_test} = <<'END';
2328 usage: var_test(X, Y [, ratio => RATIO]
2329 [, alternative => {two.sided,less,greater}]
2330 [, conf_level => LEVEL])
2331  
2332 F test that two samples from normal populations have the same variance.
2333  
2334 positional arguments:
2335 X an array ref of the first sample; also x => X
2336 Y an array ref of the second sample; also y => Y
2337  
2338 options:
2339 ratio => RATIO the ratio of the variances under the null, positive
2340 and finite (default: 1)
2341 alternative => ALT two.sided, less or greater (default: two.sided)
2342 conf_level => LEVEL confidence level of conf_int, strictly between 0 and
2343 1 (default: 0.95)
2344  
2345 example:
2346 var_test([2.9, 3.0, 2.5, 2.6, 3.2], [3.8, 2.7, 4.0, 2.4])
2347 # returns { statistic => 0.1319, parameter => [4, 3], p_value => 0.0796,
2348 # estimate => 0.1319, conf_int => [...], ... }
2349  
2350 END
2351  
2352 221 $SCREEN{wilcox_test} = <<'END';
2353 usage: wilcox_test(X [, Y] [, paired => BOOL] [, mu => MU]
2354 [, alternative => {two.sided,less,greater}]
2355 [, exact => BOOL] [, correct => BOOL]
2356 [, edgeworth => {0,1,2,3}] [, conf_int => BOOL]
2357 [, conf_level => LEVEL] [, digits_rank => DIGITS]
2358 [, tol_root => TOL])
2359  
2360 Wilcoxon rank-sum (Mann-Whitney) or signed-rank test.
2361  
2362 positional arguments:
2363 X an array ref of the first sample; also x => X
2364 Y an array ref of the second sample; also y => Y.
2365 Left out, or undef, for the one-sample test
2366  
2367 options:
2368 paired => BOOL signed-rank test on X - Y; Y the same length
2369 (default: 0)
2370 mu => MU location shift under the null, finite (default: 0)
2371 alternative => ALT two.sided, less or greater (default: two.sided)
2372 exact => BOOL exact p-value, 1, or the normal approximation, 0
2373 (default: undef, exact when the samples are < 50)
2374 correct => BOOL continuity correction on the normal approximation
2375 (default: 1)
2376 edgeworth => TERMS Edgeworth terms refining the normal approximation
2377 (default: 0)
2378 conf_int => BOOL also the Hodges-Lehmann estimate and conf_int
2379 (default: 0)
2380 conf_level => LEVEL requested level of conf_int, between 0 and 1
2381 (default: 0.95)
2382 digits_rank => DIGITS
2383 significant digits to round to before ranking
2384 (default: undef, no rounding)
2385 tol_root => TOL tolerance of the asymptotic interval's root search,
2386 positive (default: 1e-4)
2387  
2388 example:
2389 wilcox_test([1.83, 0.50, 1.62, 2.48, 1.68], [0.88, 0.65, 0.60, 2.05, 1.06],
2390 paired => 1)
2391 # returns { statistic => 14, statistic_name => 'V', p_value => 0.125,
2392 # method => ..., alternative => 'two.sided', ... }
2393  
2394 END
2395  
2396 221 $SCREEN{TukeyHSD} = <<'END';
2397 usage: TukeyHSD(FIT, data => DATA [, response => NAME | formula => FORMULA]
2398 [, which => FACTORS] [, conf_level => LEVEL]
2399 [, ordered => BOOL])
2400  
2401 Tukey's honest significant differences between the levels of each factor.
2402  
2403 positional arguments:
2404 FIT a fit from aov, lm or glm
2405  
2406 options:
2407 data => DATA the data frame the model was fitted to (required);
2408 a hash of groups for aov's no-formula form
2409 response => NAME the response column (or give formula)
2410 formula => FORMULA 'response ~ ...', read for its response
2411 which => FACTORS a factor name or an array ref of them (default: every
2412 factor in FIT); names the result in the wide form
2413 conf_level => LEVEL family-wise confidence level, between 0 and 1
2414 (default: 0.95)
2415 ordered => BOOL order each factor's levels by increasing mean
2416 (default: 0)
2417  
2418 example:
2419 my %pw = (ctrl => [4.17, 5.58, 5.18], trt => [4.81, 4.17, 4.41]);
2420 TukeyHSD(aov(\%pw), data => \%pw)
2421 # returns { group => [ { comparison => 'trt-ctrl', diff => -0.5133,
2422 # lwr => -1.7883, upr => 0.7616, 'p adj' => 0.3262 } ],
2423 # conf_level => 0.95, ordered => 0 }
2424  
2425 END
2426  
2427 221 $SCREEN{anova} = <<'END';
2428 usage: anova(DATA, FORMULA [, FORMULA ...] | FIT, FIT [, FIT ...]
2429 [, test => {F,Chisq,LRT}] [, dispersion => DISPERSION])
2430  
2431 Sequential (Type-I) ANOVA table of a linear model, or a comparison of models.
2432  
2433 positional arguments:
2434 DATA the data frame: a hash of columns, or an AoH
2435 FORMULA 'response ~ terms'; two or more compare the nested
2436 models in turn
2437 FIT instead of DATA and FORMULA, two or more lm or glm
2438 fits to compare
2439  
2440 options:
2441 test => TEST F, Chisq or LRT; with FITs only (default: F for lm
2442 and gaussian glm, else Chisq)
2443 dispersion => DISPERSION
2444 the dispersion the test scales by; with FITs only
2445 (default: the largest model's)
2446  
2447 example:
2448 anova({ yield => [5.5, 5.4, 5.8, 4.5, 4.8, 4.2],
2449 ctrl => [1, 1, 1, 0, 0, 0] }, 'yield ~ ctrl')
2450 # returns { ctrl => { Df => 1, 'F value' => 25.6, 'Pr(>F)' => 0.0072,
2451 # ... }, Residuals => { Df => 4, ... } }
2452  
2453 END
2454  
2455 221 $SCREEN{aov} = <<'END';
2456 usage: aov(DATA [, FORMULA])
2457  
2458 Analysis of variance: the sequential (Type-I) table of a linear model.
2459  
2460 positional arguments:
2461 DATA the data frame: a hash of columns, or an AoH; with
2462 no FORMULA, a hash of groups, each an array ref
2463 FORMULA 'response ~ terms' (default: none, the groups are
2464 stacked and fitted as Value ~ Group)
2465  
2466 example:
2467 aov({ ctrl => [4.17, 5.58, 5.18], trt => [4.81, 4.17, 4.41] })
2468 # returns { Group => { 'F value' => 1.2497, 'Pr(>F)' => 0.3262, ... },
2469 # Residuals => {...}, coefficients => {...}, ... }
2470  
2471 END
2472  
2473 # Screens, part 7.
2474  
2475 221 $SCREEN{lm} = <<'END';
2476 usage: lm(formula => FORMULA, data => DF)
2477  
2478 Fit a linear model by least squares, as R's lm().
2479  
2480 options:
2481 formula => FORMULA 'y ~ x1 + x2'; takes +, :, *, ^, ., - and -1 as R's
2482 formulas do (required)
2483 data => DF the data: a HoA, AoH or HoH; rows are named from a
2484 row_names column if there is one (required)
2485  
2486 example:
2487 lm(formula => 'y ~ x', data => { x => [1, 2, 3, 4], y => [3, 5, 7, 10] })
2488 # returns { coefficients => { Intercept => 0.5, x => 2.3 }, summary,
2489 # r_squared, f_pvalue, fitted_values, residuals, ... }
2490  
2491 END
2492  
2493 221 $SCREEN{glm} = <<'END';
2494 usage: glm(formula => FORMULA, data => DF [, family => FAMILY]
2495 [, theta => THETA] [, conf_level => LEVEL] [, offset => OFFSET]
2496 [, weights => W] [, vcov => TYPE] [, cluster => CLUSTER]
2497 [, absorb => FACTORS] [, maxit => N] [, epsilon => TOL])
2498  
2499 Fit a generalized linear model by IRLS, as R's glm() and MASS::glm.nb().
2500  
2501 options:
2502 formula => FORMULA as lm()'s, plus offset() terms and factors to absorb
2503 after a '|' (required)
2504 data => DF the data: a HoA, AoH or HoH (required)
2505 family => FAMILY {gaussian,binomial,poisson,negbin} (default: gaussian)
2506 theta => THETA negbin dispersion, held fixed (default: estimated)
2507 conf_level => LEVEL level of the confidence intervals (default: 0.95)
2508 offset => OFFSET a column, an expression such as 'log(t)', or an array
2509 ref of one value per row (default: none)
2510 weights => W prior weights: a column or an array ref (default: none)
2511 vcov => TYPE {model,HC0,HC1,HC2,HC3}; also accepted as vcov_type
2512 (default: model, or HC0 with a cluster)
2513 cluster => CLUSTER a column, 'a + b' for multiway clustering, or an array
2514 ref of labels (default: none)
2515 absorb => FACTORS a column name or an array ref of them, absorbed as
2516 fixed effects (default: none)
2517 maxit => N IRLS iteration limit, 1 to 1e6 (default: 25)
2518 epsilon => TOL IRLS convergence tolerance, between 0 and 1 (default:
2519 1e-8)
2520  
2521 example:
2522 glm(formula => 'y ~ x', family => 'poisson',
2523 data => { x => [1, 2, 3, 4, 5], y => [1, 3, 2, 6, 8] })
2524 # returns { coefficients => { Intercept => -0.2087, x => 0.4632 },
2525 # summary, exp, conf_int, deviance, aic, converged, ... }
2526  
2527 END
2528  
2529 221 $SCREEN{predict} = <<'END';
2530 usage: predict(MODEL [, NEWDATA] [, type => TYPE])
2531  
2532 Predict from a fitted lm() or glm() model, as R's predict().
2533  
2534 positional arguments:
2535 MODEL a model returned by lm() or glm()
2536 NEWDATA a HoA, AoH, HoH or flat hash of new rows; leave it out,
2537 or give undef, for the model's own fitted_values
2538  
2539 options:
2540 type => TYPE {response,link}: the response scale, with the inverse
2541 link applied, or the linear predictor (default:
2542 response)
2543  
2544 example:
2545 my $fit = lm(formula => 'y ~ x',
2546 data => { x => [1, 2, 3, 4], y => [3, 5, 7, 10] });
2547 predict($fit, { x => [5, 6] })
2548 # returns { 1 => 12, 2 => 14.3 }
2549  
2550 END
2551  
2552 221 $SCREEN{prcomp} = <<'END';
2553 usage: prcomp(X [, center => BOOL] [, scale => BOOL] [, retx => BOOL]
2554 [, tol => TOL] [, rank => N])
2555  
2556 Principal component analysis, as R's prcomp().
2557  
2558 positional arguments:
2559 X the data: an AoA, AoH, HoA or HoH; x => X also works
2560  
2561 options:
2562 center => BOOL shift each column to mean zero first (default: 1)
2563 scale => BOOL scale each column to unit variance first (default: 0)
2564 retx => BOOL return the rotated data as x (default: 1)
2565 tol => TOL leave out of rotation and x the components whose sdev
2566 is at most tol times the first's (default: undef, keep
2567 all); sdev always has all of them, as in R
2568 rank => N return at most N components in rotation and x
2569 (default: undef, all)
2570  
2571 example:
2572 prcomp([ [2, 4], [4, 2], [6, 6] ])
2573 # returns { sdev => [2.4495, 1.4142], rotation, x, center, scale }
2574  
2575 END
2576  
2577 221 $SCREEN{vif} = <<'END';
2578 usage: vif(DF, FORMULA)
2579  
2580 Variance inflation factors of a model's terms, as car::vif().
2581  
2582 positional arguments:
2583 DF the data: a HoA, AoH or HoH
2584 FORMULA a formula read as lm() reads it, such as 'y ~ a + b +
2585 c', or an array ref of column names, which is '~ a + b
2586 + c'
2587  
2588 example:
2589 vif({ a => [1, 2, 3, 4, 5, 6], b => [2, 1, 4, 3, 6, 5],
2590 c => [1, 3, 2, 5, 4, 7] }, [qw(a b c)])
2591 # returns { a => 134.9, b => 36.9, c => 56.0 }, or a { GVIF, Df,
2592 # 'GVIF^(1/(2*Df))' } hash per term when a term has more than one column
2593  
2594 END
2595  
2596 221 $SCREEN{hosmer_lemeshow} = <<'END';
2597 usage: hosmer_lemeshow(OBSERVED, PREDICTED [, g => G])
2598  
2599 Hosmer-Lemeshow goodness-of-fit test of a logistic model, as hoslem.test().
2600  
2601 positional arguments:
2602 OBSERVED array ref of the observed 0/1 outcomes
2603 PREDICTED array ref of the model's predicted probabilities, one
2604 per outcome
2605  
2606 options:
2607 g => G number of risk groups, an integer of at least 3
2608 (default: 10)
2609  
2610 example:
2611 hosmer_lemeshow(\@obs, \@prob, g => 10)
2612 # returns { statistic, parameter, p_value, groups, table }
2613  
2614 END
2615  
2616 221 $SCREEN{survfit} = <<'END';
2617 usage: survfit(TIME, STATUS [, group => GROUP] [, conf_level => LEVEL])
2618  
2619 Kaplan-Meier survival curves, as survival::survfit().
2620  
2621 positional arguments:
2622 TIME array ref of survival or censoring times
2623 STATUS array ref of event flags: 1 = event, 0 = censored; or
2624 2 = event, 1 = censored, when the largest is 2
2625  
2626 options:
2627 group => GROUP array ref of group labels, for one curve per group
2628 (default: one curve)
2629 conf_level => LEVEL level of the confidence intervals (default: 0.95)
2630  
2631 example:
2632 survfit([1, 2, 3, 4, 5], [1, 0, 1, 1, 0])
2633 # returns { strata => { '' => { time, n_risk, n_event, surv => [0.8, 0.8,
2634 # 0.5333, 0.2667, 0.2667], lower, upper, median => 4, ... } } }
2635  
2636 END
2637  
2638 221 $SCREEN{logrank_test} = <<'END';
2639 usage: logrank_test(TIME, STATUS, GROUP [, rho => RHO])
2640  
2641 Log-rank (Mantel-Cox) test that survival curves differ, as survival::survdiff().
2642  
2643 positional arguments:
2644 TIME array ref of survival or censoring times
2645 STATUS array ref of event flags: 1 = event, 0 = censored; or
2646 2 = event, 1 = censored, when the largest is 2
2647 GROUP array ref of group labels, two or more groups
2648  
2649 options:
2650 rho => RHO weight each event time by S(t-)^RHO, the pooled
2651 Kaplan-Meier curve; 1 is Peto & Peto's test (default:
2652 0, the log-rank test)
2653  
2654 example:
2655 logrank_test([1, 2, 3, 4, 5, 6], [1, 1, 0, 1, 1, 1], [qw(a a a b b b)])
2656 # returns { statistic => 2.4694, parameter => 1, p_value => 0.1161,
2657 # observed => [2, 3], expected => [0.9, 4.1],
2658 # groups => ['a', 'b'], rho => 0, method }
2659  
2660 END
2661  
2662 221 $SCREEN{coxph} = <<'END';
2663 usage: coxph(TIME, STATUS, COVARIATES [, OPTION => VALUE ...])
2664  
2665 Cox proportional-hazards regression, as survival::coxph().
2666  
2667 positional arguments:
2668 TIME array ref of stop times; or leave out all three and
2669 give formula => and data =>
2670 STATUS array ref of event flags: 1 = event, 0 = censored; or
2671 2 = event, 1 = censored, when the largest is 2
2672 COVARIATES an array ref of one covariate, or [\@x1, \@x2, ...]
2673  
2674 options:
2675 formula => FORMULA 'Surv(time, status) ~ x' or 'Surv(start, stop, status)
2676 ~ x', with strata() and cluster() terms, in place of
2677 the three arrays
2678 data => DF the data the formula names: a HoA, AoH or HoH
2679 names => NAMES array ref of covariate names (default: x1, x2, ...)
2680 ties => TIES {efron,breslow} (default: efron)
2681 conf_level => LEVEL level of the confidence intervals (default: 0.95)
2682 maxit => N Newton iteration limit, 0 to 1e6; also iter_max
2683 (default: 20)
2684 eps => TOL convergence tolerance, between 0 and 1 (default: 1e-9)
2685 start => START array ref of interval start times, for (start, stop]
2686 data (default: none)
2687 strata => STRATA array ref of stratum labels (default: none)
2688 cluster => CLUSTER array ref of cluster labels, or with a formula a column
2689 name (default: none)
2690 weights => W case weights (default: none)
2691 offset => OFFSET one offset per row (default: none)
2692 robust => BOOL report the robust variance (default: 0, or 1 with a
2693 cluster)
2694  
2695 example:
2696 coxph(\@time, \@status, [\@age, \@sex], names => ['age', 'sex'])
2697 # returns { coef, exp_coef, se, z, p_value, conf_int, names, loglik,
2698 # lr_stat, lr_p_value, n, nevent, converged, ... }
2699  
2700 END
2701  
2702 221 $SCREEN{zerotrunc} = <<'END';
2703 usage: zerotrunc(formula => FORMULA, data => DF [, dist => DIST]
2704 [, theta => THETA] [, offset => OFFSET] [, weights => W]
2705 [, conf_level => LEVEL])
2706  
2707 Zero-truncated count regression, as countreg::zerotrunc().
2708  
2709 options:
2710 formula => FORMULA as glm()'s, with offset() terms allowed; the response
2711 is a count of at least 1 (required)
2712 data => DF the data: a HoA, AoH or HoH (required)
2713 dist => DIST {poisson,negbin,geometric} (default: poisson)
2714 theta => THETA a fixed negbin dispersion, greater than 0 (default:
2715 estimated)
2716 offset => OFFSET a column, an expression or an array ref (default: none)
2717 weights => W case weights (default: none)
2718 conf_level => LEVEL level of the confidence intervals (default: 0.95)
2719  
2720 example:
2721 zerotrunc(formula => 'days ~ hours + age', data => \%admitted,
2722 dist => 'negbin')
2723 # returns { coefficients, summary, vcov, theta, SE_logtheta, loglik, aic,
2724 # nobs, converged, fitted_values, residuals, ... }
2725  
2726 END
2727  
2728 221 $SCREEN{hurdle} = <<'END';
2729 usage: hurdle(formula => FORMULA, data => DF [, dist => DIST]
2730 [, zero_dist => DIST] [, link => LINK] [, offset => OFFSET]
2731 [, weights => W] [, conf_level => LEVEL])
2732  
2733 Hurdle model for counts with excess zeros, as pscl::hurdle().
2734  
2735 options:
2736 formula => FORMULA 'y ~ count terms' or 'y ~ count terms | zero terms'
2737 (required)
2738 data => DF the data: a HoA, AoH or HoH (required)
2739 dist => DIST the count part: {poisson,negbin,geometric} (default:
2740 poisson)
2741 zero_dist => DIST the zero part: {binomial,poisson,negbin,geometric}
2742 (default: binomial)
2743 link => LINK the binomial zero part's link; only logit is
2744 implemented (default: logit)
2745 offset => OFFSET a column, an expression or an array ref, for the count
2746 part (default: none)
2747 weights => W case weights (default: none)
2748 conf_level => LEVEL level of the confidence intervals (default: 0.95)
2749  
2750 example:
2751 hurdle(formula => 'days ~ hours + age | hours', data => \%d, dist => 'negbin')
2752 # returns { coefficients => { count => {...}, zero => {...} }, summary,
2753 # vcov, loglik, aic, nobs, converged, fitted_values, ... }
2754  
2755 END
2756  
2757 221 $SCREEN{svyglm} = <<'END';
2758 usage: svyglm(formula => FORMULA, data => DF [, family => FAMILY]
2759 [, weights => W] [, strata => STRATA] [, cluster => PSU]
2760 [, fpc => FPC] [, nest => BOOL] [, offset => OFFSET]
2761 [, conf_level => LEVEL])
2762  
2763 Design-based regression for complex survey data, as survey::svyglm().
2764  
2765 options:
2766 formula => FORMULA as glm()'s, with offset() terms allowed (required)
2767 data => DF the data: a HoA, AoH or HoH (required)
2768 family => FAMILY {gaussian,binomial,quasibinomial,poisson,quasipoisson}
2769 (default: gaussian)
2770 weights => W sampling weights: a column name or an array ref
2771 (default: 1)
2772 strata => STRATA stratum of each row: a column name or an array ref
2773 (default: none)
2774 cluster => PSU the PSU of each row; also ids, id or psu (default: one
2775 PSU per row)
2776 fpc => FPC finite population correction: stratum size or sampling
2777 fraction (default: none)
2778 nest => BOOL PSU labels are unique only within strata (default: 0)
2779 offset => OFFSET a column, an expression or an array ref (default: none)
2780 conf_level => LEVEL level of the confidence intervals (default: 0.95)
2781  
2782 example:
2783 svyglm(formula => 'y ~ x', data => \%d, weights => 'pw', strata => 'st',
2784 cluster => 'psu')
2785 # returns { coefficients, summary, vcov, conf_int, degf, n_psu, n_strata,
2786 # nobs, converged, fitted_values, ... }
2787  
2788 END
2789  
2790 221 $SCREEN{ivreg} = <<'END';
2791 usage: ivreg(formula => FORMULA, data => DF [, weights => W] [, vcov => TYPE]
2792 [, cluster => CLUSTER] [, conf_level => LEVEL])
2793  
2794 Instrumental-variables regression by two-stage least squares, as ivreg::ivreg().
2795  
2796 options:
2797 formula => FORMULA 'y ~ regressors | instruments' or 'y ~ exogenous |
2798 endogenous | instruments' (required)
2799 data => DF the data: a HoA, AoH or HoH (required)
2800 weights => W weights: a column name or an array ref (default: none)
2801 vcov => TYPE {model,HC0,HC1}; also vcov_type (default: model, or HC0
2802 with a cluster)
2803 cluster => CLUSTER a column name or an array ref of labels (default: none)
2804 conf_level => LEVEL level of the confidence intervals (default: 0.95)
2805  
2806 example:
2807 ivreg(formula => 'y ~ x + w | z + w', data => \%d)
2808 # returns { coefficients, summary, vcov, conf_int, diagnostics => { weak,
2809 # wu_hausman, sargan }, r_squared, sigma, nobs, ... }
2810  
2811 END
2812  
2813 221 $SCREEN{lmer} = <<'END';
2814 usage: lmer(formula => FORMULA, data => DF [, REML => BOOL]
2815 [, conf_level => LEVEL])
2816  
2817 Linear mixed-effects regression, as lme4::lmer() with lmerTest's t tests.
2818  
2819 options:
2820 formula => FORMULA fixed effects plus one or more (terms | group)
2821 random-effects terms (required)
2822 data => DF the data: a HoA, AoH or HoH (required)
2823 REML => BOOL 1 for REML, 0 for maximum likelihood; also reml
2824 (default: 1)
2825 conf_level => LEVEL level of the confidence intervals (default: 0.95)
2826  
2827 example:
2828 lmer(formula => 'Reaction ~ Days + (Days | Subject)', data => \%sleepstudy)
2829 # returns { coefficients, summary, vcov, conf_int, varcor, sigma, theta,
2830 # loglik, AIC, BIC, nobs, converged, singular, ... }
2831  
2832 END
2833  
2834 # Screens, part 8.
2835  
2836 221 $SCREEN{age_standardize} = <<'END';
2837 usage: age_standardize(COUNT, POP, STDPOP [, per => SCALE]
2838 [, conf_level => LEVEL])
2839  
2840 Directly standardized rate, with the Fay-Feuer gamma confidence interval.
2841  
2842 positional arguments:
2843 COUNT events per stratum (or named: count => COUNT, or
2844 rate => RATE to give stratum rates instead)
2845 POP population or person-time per stratum (or named:
2846 pop => POP)
2847 STDPOP standard-population weight per stratum (or named:
2848 stdpop => STDPOP)
2849  
2850 options:
2851 per => SCALE multiplier for every reported rate (default: 1)
2852 conf_level => LEVEL confidence level, between 0 and 1 (default: 0.95)
2853  
2854 example:
2855 age_standardize([5, 20, 55, 60], [1000, 3000, 4000, 2000],
2856 [2000, 3000, 3000, 2000], per => 100_000)
2857 # returns { adj_rate => 1312.5, conf_int => [1097.8, 1569.6], ... }
2858  
2859 END
2860  
2861 221 $SCREEN{auc} = <<'END';
2862 usage: auc(SCORES, LABELS [, positive => LABEL] [, direction => {>,<}])
2863  
2864 Area under the ROC curve: the chance a positive outscores a negative.
2865  
2866 positional arguments:
2867 SCORES array ref of scores
2868 LABELS array ref of class labels, one per score
2869  
2870 options:
2871 positive => LABEL the label of the positive class, compared as a
2872 string (default: 1)
2873 direction => {>,<} '>' if a higher score is more positive, '<' if a
2874 lower one is (default: '>')
2875  
2876 example:
2877 auc([0.9, 0.4, 0.8, 0.3], [1, 1, 0, 0])
2878 # returns 0.75
2879  
2880 END
2881  
2882 221 $SCREEN{auroc} = <<'END';
2883 usage: auroc(LABELS, SCORES [, positive => LABEL] [, direction => {>,<}]
2884 [, cutoff => X | active_frac => FRAC]
2885 [, active_side => {high,low}])
2886  
2887 Area under the ROC curve, with sklearn's roc_auc_score() argument order.
2888  
2889 positional arguments:
2890 LABELS array ref of class labels, or of a numeric truth
2891 column with cutoff or active_frac
2892 SCORES array ref of scores, one per label
2893  
2894 options:
2895 positive => LABEL the label of the positive class, compared as a
2896 string (default: 1)
2897 direction => {>,<} '>' if a higher score is more positive, '<' if a
2898 lower one is (default: '>')
2899 cutoff => X call a truth value >= X positive
2900 active_frac => FRAC call this fraction of the truth values positive,
2901 strictly between 0 and 1, from one tail
2902 active_side => SIDE the tail active_frac takes: high or low
2903 (default: high)
2904  
2905 example:
2906 auroc([1, 1, 0, 0], [0.9, 0.4, 0.8, 0.3])
2907 # returns 0.75
2908  
2909 END
2910  
2911 221 $SCREEN{bedroc} = <<'END';
2912 usage: bedroc(SCORES, LABELS [, alpha => ALPHA] [, positive => LABEL]
2913 [, cutoff => X | active_frac => FRAC]
2914 [, active_side => {high,low}] [, direction => {>,<}]
2915 [, top => FRAC])
2916  
2917 Boltzmann-Enhanced Discrimination of ROC, an early-recognition metric.
2918  
2919 positional arguments:
2920 SCORES array ref of ranking scores
2921 LABELS array ref of class labels, or of a numeric truth
2922 column with cutoff or active_frac
2923  
2924 options:
2925 alpha => ALPHA early-recognition weight, > 0 and finite
2926 (default: 20)
2927 positive => LABEL the label of an active, compared as a string
2928 (default: 1)
2929 cutoff => X call a truth value >= X active
2930 active_frac => FRAC call this fraction of the truth values active,
2931 strictly between 0 and 1, from one tail
2932 active_side => SIDE the tail active_frac takes: high or low
2933 (default: high)
2934 direction => {>,<} '>' if a higher score ranks first, '<' if a lower
2935 one does (default: '>')
2936 top => FRAC also report enrichment in the top fraction, in
2937 (0, 1]
2938  
2939 example:
2940 bedroc([0.9, 0.8, 0.4, 0.3, 0.2, 0.1], [1, 1, 0, 0, 0, 0], alpha => 20)
2941 # returns { bedroc => 1, ... }; bedroc('h') prints a longer help
2942  
2943 END
2944  
2945 221 $SCREEN{roc} = <<'END';
2946 usage: roc(SCORES, LABELS [, positive => LABEL] [, conf_level => LEVEL]
2947 [, direction => {>,<}])
2948  
2949 ROC curve: DeLong AUC and interval, every threshold, and Youden's best cut.
2950  
2951 positional arguments:
2952 SCORES array ref of scores
2953 LABELS array ref of class labels, one per score
2954  
2955 options:
2956 positive => LABEL the label of the positive class, compared as a
2957 string (default: 1)
2958 conf_level => LEVEL confidence level of auc_ci, between 0 and 1
2959 (default: 0.95)
2960 direction => {>,<} '>' if a higher score is more positive, '<' if a
2961 lower one is (default: '>')
2962  
2963 example:
2964 roc([0.9, 0.4, 0.8, 0.3], [1, 1, 0, 0])
2965 # returns { auc => 0.75, auc_ci => [...], youden => {...}, ... }
2966  
2967 END
2968  
2969 221 $SCREEN{cohen_d} = <<'END';
2970 usage: cohen_d(X, Y [, conf_level => LEVEL] [, ci_method => {nct,normal}])
2971  
2972 Cohen's d for two independent groups, with Hedges' g and a confidence interval.
2973  
2974 positional arguments:
2975 X array ref of the first group's values
2976 Y array ref of the second group's values
2977  
2978 options:
2979 conf_level => LEVEL confidence level, between 0 and 1 (default: 0.95)
2980 ci_method => METHOD nct for the noncentral-t interval, normal for
2981 d +- z * se (default: nct)
2982  
2983 example:
2984 cohen_d([1, 2, 3, 4], [3, 4, 5, 6])
2985 # returns { estimate => -1.549, conf_int => [-3.134, 0.125], ... }
2986  
2987 END
2988  
2989 221 $SCREEN{smd} = <<'END';
2990 usage: smd(X, Y)
2991  
2992 Standardized mean difference, over the unweighted mean of the two variances.
2993  
2994 positional arguments:
2995 X array ref of the first group's values
2996 Y array ref of the second group's values
2997  
2998 example:
2999 smd([1, 2, 3, 4], [3, 4, 5, 6])
3000 # returns -1.549
3001  
3002 END
3003  
3004 221 $SCREEN{cramers_v} = <<'END';
3005 usage: cramers_v(TABLE | X, Y)
3006  
3007 Cramer's V for a contingency table, with Bergsma's bias-corrected V.
3008  
3009 positional arguments:
3010 TABLE array ref of rows of counts, at least 2 x 2
3011 X, Y or two parallel array refs of categories, which are
3012 cross-tabulated
3013  
3014 example:
3015 cramers_v([[10, 20, 30], [15, 25, 10]])
3016 # returns { estimate => 0.312, bias_corrected => 0.283, ... }
3017  
3018 END
3019  
3020 221 $SCREEN{eta_squared} = <<'END';
3021 usage: eta_squared(AOV | VALUES, GROUPS)
3022  
3023 Eta-squared, partial eta-squared and omega-squared for a one-way design.
3024  
3025 positional arguments:
3026 AOV a one-way aov() result
3027 VALUES, GROUPS or two parallel array refs: the values and their
3028 group labels
3029  
3030 example:
3031 eta_squared([1, 2, 3, 4, 5, 6], [qw(a a b b c c)])
3032 # returns { eta_sq => 0.914, omega_sq => 0.833, ... }
3033  
3034 END
3035  
3036 221 $SCREEN{epi_2x2} = <<'END';
3037 usage: epi_2x2(A, B, C, D | TABLE [, conf_level => LEVEL]
3038 [, correct => BOOL])
3039  
3040 Odds ratio, risk ratio and risk difference, with intervals, for a 2x2 table.
3041  
3042 positional arguments:
3043 A, B, C, D the cell counts: exposed with and without the
3044 outcome, then unexposed with and without it
3045 TABLE or one array ref, [a, b, c, d] or [[a, b], [c, d]]
3046  
3047 options:
3048 conf_level => LEVEL confidence level, between 0 and 1 (default: 0.95)
3049 correct => BOOL add 0.5 to every cell, as a zero cell does anyway
3050 (default: 0)
3051  
3052 example:
3053 epi_2x2(30, 70, 20, 80)
3054 # returns { odds_ratio => 1.714, odds_ratio_ci => [0.895, 3.285], ... }
3055  
3056 END
3057  
3058 221 1;
3059  
3060 __END__
« LikeR.xs ↑ Summary