| 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 | 218 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 32 | 218 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 33 | |||
| 34 | 218 | our %ALIAS = ( | |
| 35 | aoh2h => 'df2h', | ||
| 36 | rbind => 'concat', | ||
| 37 | ); | ||
| 38 | |||
| 39 | 218 | our %SCREEN; | |
| 40 | |||
| 41 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | $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 | 218 | 1; | |
| 3059 | |||
| 3060 | __END__ | ||