## `stats::sample` -- the domain of statistical samples

#### Introduction

A sample represents a collection of statistical data, organized as a matrix. Usually, each row refers to an individual of the population described by the sample. Each column represents an attribute.

#### Introduction

`stats::sample``([[a11, ..., a1.n], ..., [a.m.1, ..., a.m.n]])` creates a sample with m rows and n columns, `a.i.j` being the entry in the i-th row, j-th column.

`stats::sample``([a11, ..., a.m.1])` creates a sample with m rows and one column.

#### Creating Elements

`stats::sample([[a11, a12, ...], [a21, a22, ...], ...])`
`stats::sample([a11, a21, ...])`

#### Parameters

`a11, a12, ...` | - | arithmetical expressions or strings.

#### Categories

`Cat::Set`

#### Details

- Each row `[a.i.1, ..., a.i.n]` must contain the same number of entries.
- Elements of domain type `DOM_COMPLEX`, `DOM_EXPR`, `DOM_FLOAT`, `DOM_IDENT`, `DOM_INT`, or `DOM_RAT` are regarded as ``data'' and are stored in a sample as on input. All other types of input parameters are converted to strings (`DOM_STRING`).

  If one element in a column is a string or is converted to a string, then all elements of that column are converted to strings.

  This produces two kinds of columns: data columns and string columns.

#### Method equal: test for equality

- `equal(dom s1, dom s2)`
- - tests, whether the two samples `s1` and `s2` are equal. Returns `TRUE` or `FALSE`, respectively.

#### Method convert: convert a list to a sample

- `convert(list x )`
- - converts the list/list of lists `x` to a sample. Returns `FAIL`, if this is not possible.

#### Method convert_to: convert a sample to a list of lists

- `convert_to(dom s, type T)`
- - Presently, only `T = DOM_LIST` is implemented; a list of all rows of `s` is returned as a list of lists. All other target types `T` yield `FAIL`.

#### Method expr: convert a sample to a list of lists of expressions

- `expr(dom s)`
- - converts `s` to a list of lists. All entries are converted to expressions.

#### Method col2list: return a particular column as a list

- `col2list(dom s, positive integer or range c, ...)`
- - returns the `c`-th column of the sample `s` as a list. It is possible to specify more than one column index or range of column indices.

#### Method append: append a row

- `append(dom s, list row)`
- - appends the list `row` as a row to the sample `s`. The length of the row has to coincide with the number of columns of the sample `s`.

#### Method _concat: create a sample from the rows of several samples

- `_concat(dom s, dom or list s1, ...)`
- - returns a sample consisting of the rows of `s` and the rows of the further arguments. Lists are regarded as samples with one row. All rows must have the same length.

    Note that the dot operator `.` may be used to call this method. Cf. example 4.

  - This method overloads `_concat`.

#### Method delCol: delete one or more columns

- `delCol(dom s, positive integer or range c, ...)`
- - returns the sample obtained by deleting the column(s) of the sample `s` specified by the argument `c`. `NIL` is returned, if all columns of `s` are deleted.

    It is possible to specify more than one column index or range of column indices.

#### Method delRow: delete one or more rows

- `delRow(dom s, positive integer or range r, ...)`
- - returns the sample obtained by deleting the row(s) of the sample `s` specified by the argument `r`. `NIL` is returned, if all rows of `s` are deleted.

    It is possible to specify more than one row index or range of row indices.

#### Method float: map the float function to all entries

- `float(dom s)`
- - applies `float` to all entries of `s`.
  - This method overloads `float`.

#### Method has: test for the occurrence of elements

- `has(dom s, list or set or expression e)`
- - tests, whether an expression `e` is among the entries of `s`. Returns `TRUE` or `FALSE`, respectively.
  - If `e` is a list or a set, then this method tests, whether at least one of its elements is among the entries of `s`.

#### Method _index: return a particular entry

- `_index(dom s, positive integer i, positive integer j)`
- - returns the `j`-th entry of the `i`-th row of the sample `s`.
  - This method overloads `_index`.
  - Indexed calls such as `s[i, j]` call this method.

#### Method set_index: assign a new value to an entry

- `set_index(dom s, positive integer i, positive integer j, any x)`
- - sets the (`i`,`j`)-th element of `s` to `x`.

    Note that no conversion to strings occurs, even if the type of `s` is not one of the ``data types'' described in the `Details' section.

  - This method is called by indexed assignments of the form `s[i, j] := x`.

#### Method map: map a function to the rows

- `map(dom s, any f)`
- - maps the function `f` onto the rows of the sample `s`. Note that rows are internally represented by lists. The function must accept a list as input parameter and must return a list of the same length.
  - This method overloads `map`.

#### Method nops: number of rows

- `nops(dom s)`
- - returns the number of rows of `s`.
  - This method overloads `nops`.

#### Method op: get the operands (rows)

- `op(dom s, positive integer i )`
- `op(dom s, [positive integer i, positive integer j])`
- - returns the i-th row of `s` or the j-th element of the i-th row, respectively.
  - This method overloads `op`.

#### Method subsop: replace a row

- `subsop(dom s, integer i = list newrow, ..)`
- - replaces the i-th row of the sample `s` by `newrow`. The length of the new row has to match the number of columns of `s`. It is possible to replace several rows simultaneously.
  - This method overloads `subsop`.

#### Method row2list: return a particular row as a list

- `row2list(dom s, positive integer or range r, ..)`
- - returns the `r`-th row of the sample `s` as a list. It is possible to specify more than one row index or range of row indices.

#### Method print: output

- `print(dom s)`
- - returns a matrix-like scheme containing the entries of the sample `s`. This method is called by the system for displaying samples.
  - This method overloads `print`.

#### Method fastprint: fast output

- `fastprint(dom s)`
- - returns a matrix-like scheme containing the entries of the sample `s`. The usual `print` command may be slow for large samples. This method provides a somewhat faster alternative.

#### Example 1

A sample is created from a list of rows:

    >> stats::sample([[5, a], [b, 7.534], [7/4, c+d]])

                                     5      a
                                     b  7.534
                                   7/4  c + d

For a sample with only one column one can use a flat list instead of a list of rows:

    >> stats::sample([5, 3, 8])

                                        5
                                        3
                                        8

#### Example 2

The following input creates a small sample with columns for ``gender'', ``age'' and ``height'', respectively:

    >> stats::sample([["m", 26, 180], ["f", 22, 160],
                      ["f", 48, 155], ["m", 30, 172]])

                                  "m"  26  180
                                  "f"  22  160
                                  "f"  48  155
                                  "m"  30  172

Note that all entries in a column are automatically converted to strings, if one entry of that column is a string:

    >> stats::sample([[m, 26, 180], [f, 22, 160],
                      ["f", 48, 155], [m, 30, 172]])

                                  "m"  26  180
                                  "f"  22  160
                                  "f"  48  155
                                  "m"  30  172

#### Example 3

The functions `float`, `has`, `map`, `nops`, `op`, and `subsop` are overloaded to work on samples as on lists of lists:

    >> s := stats::sample([[a, 1], [b, 2], [c, 3]])

                                      a  1
                                      b  2
                                      c  3

    >> float(s), has(s, a), map(s, list -> [list[1], list[2]^2]),
       nops(s), subsop(s, 1 = [d, 4]), op(s, [1, 2])

                       a  1.0  , TRUE, a  1  , 3, d  4  , 1
                       b  2.0          b  4       b  2
                       c  3.0          c  9       c  3

Indexing works like on `array`s:

    >> s[1, 2] := x : s

                                      a  x
                                      b  2
                                      c  3

    >> delete s:

#### Example 4

The dot operator may be used to concatenate samples and lists (regarded a samples with one row):

    >> s := stats::sample([[1, a], [2, b]]): s.[X, Y].s

                                      1  a
                                      2  b
                                      X  Y
                                      1  a
                                      2  b

    >> delete s:

#### Super-Domain

`Dom::BaseDomain`

#### Axioms

`Ax::canonicalRep`

#### Changes

- new function

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000