Declares one or more matrix data structures.

### Options

`ROWS` = scalar, vector, pointer or text |
Number of rows, or labels for rows; default `*` |
---|---|

`COLUMNS` = scalar, vector, pointer or text |
Number of columns, or labels for columns; default `*` |

`VALUES` = numbers |
Values for all the matrices; default `*` |

`MODIFY` = string token |
Whether to modify (instead of redefining) existing structures (`yes, no);` default `no` |

`IPRINT` = string tokens |
Information to be used by default to identify the matrices in output (`identifier` , `extra` ); if this is not set, they will be identified in the standard way for each type of output |

### Parameters

`IDENTIFIER` = identifiers |
Identifiers of the matrices |
---|---|

`VALUES` = identifiers |
Values for each matrix |

`DECIMALS` = scalars |
Number of decimal places for printing |

`EXTRA` = texts |
Extra text associated with each identifier |

`MINIMUM` = scalars |
Minimum value for the contents of each structure |

`MAXIMUM` = scalars |
Maximum value for the contents of each structure |

`DREPRESENTATION` = scalars or texts |
Default format to use when the contents represent dates and times |

### Description

A matrix stores a set of numbers as a two-dimensional array indexed by rows and columns. For example, the array

`1 2 3 4`

`5 6 7 8`

`9 10 11 12`

is called a three-by-four matrix.

You use the `ROWS`

and `COLUMNS`

options to specify the size of the matrices that are being defined. The simplest way of doing this is to use scalars to define the numbers of rows and columns explicitly. Alternatively, you can set `ROWS`

(or `COLUMNS`

) to a variate, text or pointer, whose length then defines the number of rows (or columns) and whose values will then be used as labels, for example when the matrix is printed. Finally, if you specify a factor, the number of levels defines the number of rows or columns and the labels if available, or otherwise the levels, are used for labelling.

Values can be supplied for the matrices using either the `VALUES`

option or the `VALUES`

parameter. The option defines a common value (or set of values) for all the matrices in the declaration, while the parameter allows them each to be given different values. With the option you must supply a list of values. With the parameter, however, you must give a list of identifiers of data structures of the appropriate mode; unnamed data structures are particularly useful for this. Thus, to declare the matrix above, we can put:

`MATRIX [ROWS=3; COLUMNS=4] X;\`

` VALUES=!(1,2,3,4,5,6,7,8,9,10,11,12)`

If both the option and the parameter are specified, the parameter takes precedence.

The `DECIMALS`

parameter can be used to define the number of decimal places that Genstat will use by default whenever the values of the matrix are printed. This applies to output either by `PRINT`

or from an analysis (but it does not affect the accuracy with which the numbers are stored).

You can associate a text with each data structure by means of the parameter `EXTRA`

. This text is then used by many Genstat directives to give a fuller annotation of output.

The `MINIMUM`

and `MAXIMUM`

parameters allow you to define lower and upper limits on the values expected for any structure that stores numbers. Genstat then prints warnings if any values outside that range are assigned to the structure.

The `DREPRESENTATION`

parameter allows a scalar or a single-valued text to be specified for each matrix to indicate that the matrix stores dates and times, and to define a format to be used for these, by default, when they are printed; details are given in the description of the `PRINT`

directive.

If you are declaring any of the matrices for a second time, by default you will lose all its existing attributes and values. You can retain those that remain valid by setting option `MODIFY=yes`

.

The `IPRINT`

option can be set to specify how the matrices will be identified in output. If `IPRINT`

is not set, they will be identified in whatever way is usual for the section of output concerned. For example, the `PRINT`

directive generally uses their identifiers (although this can be changed using the `IPRINT`

option of `PRINT`

itself).

Options: `ROWS`

, `COLUMNS`

, `VALUES`

, `MODIFY`

, `IPRINT`

.

Parameters: `IDENTIFIER`

, `VALUES`

, `DECIMALS`

, `EXTRA`

, `MINIMUM`

, `MAXIMUM`

, `DREPRESENTATION`

.

### See also

Directives: `DIAGONALMATRIX`

, `LRV`

, `SYMMETRICMATRIX`

, `SSPM`

.

Commands for: Data structures.

### Example

" Example MATR-1: Declaring a rectangular matrix" TEXT [VALUES=Beer,Lager,Orange] Drink VARIATE [VALUES=0.5,1.0] Quantity MATRIX [ROWS=Drink; COLUMNS=Quantity;\ VALUES=1.1,0.6,1.2,0.65,0.8,0.45] Cost PRINT Cost; DECIMALS=2