Declares one or more diagonal matrix data structures.

### Options

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

`VALUES` = numbers |
Values for all the diagonal 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 diagonal 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 diagonal matrices |
---|---|

`VALUES` = identifiers |
Values for each diagonal 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

Diagonal matrices are square matrices that have zero entries except on their leading diagonals: for example,

`2 0 0`

`0 1 0`

`0 0 3`

Another example is the identity matrix, which has a diagonal of values equal to 1. To save space, Genstat has a special structure for diagonal matrices, and these can be declared using the `DIAGONALMATRIX`

directive.

Because a diagonal matrix is square, Genstat requires you to specify only the number of rows. This is done using the `ROWS`

option. The simplest method is to use a scalar to define the number of rows explicitly. Alternatively, you can set `ROWS`

to a variate, text or pointer, whose length then defines the number of rows 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 and the labels if available, or otherwise the levels, are used for labelling.

When you give the values of a diagonal matrix, either in a declaration or when its values are read, you should specify only the diagonal elements. (Genstat does not store the off-diagonal elements, but assumes them to be zero.) Similarly, when a diagonal matrix is printed it appears as a column of numbers; Genstat omits the off-diagonal zeros. For example:

`DIAGONALMATRIX [ROWS=3; VALUES=2,1,3] D`

declares the diagonal matrix `D`

and gives it the values shown above.

Values can be assigned to the diagonal matrices by either the `VALUES`

option or the `VALUES`

parameter. The option defines a common value for all the matrices in the declaration, while the parameter allows them each to be given a different value. If both the option and the parameter are specified, the parameter takes precedence.

If the `MODIFY`

option is set to `yes`

any existing attributes and values of the diagonal matrices are retained (if still appropriate); otherwise these are lost.

The `DECIMALS`

parameter lets you define a number of decimal places to be used by default when each diagonal matrix is printed. You can associate a text of extra annotation with each diagonal matrix using the `EXTRA`

parameter. The `MINIMUM`

and `MAXIMUM`

parameters allow you to define lower and upper limits on the values in each diagonal matrix. Genstat then prints warnings if any values outside that range are allocated to the matrix. The `DREPRESENTATION`

parameter allows a scalar or a single-valued text to be specified for each diagonal 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.

The `IPRINT`

option can be set to specify how the diagonal 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`

, `VALUES`

, `MODIFY`

, `IPRINT`

.

Parameters: `IDENTIFIER`

, `VALUES`

, `DECIMALS`

, `EXTRA`

, `MINIMUM`

, `MAXIMUM`

, `DREPRESENTATION`

.

### See also

Directives: `LRV`

, `MATRIX`

, `SYMMETRICMATRIX`

, `SSPM`

.

Commands for: Data structures.

### Example

" Example DIAG-1: declaring a diagonal matrix" DIAGONALMATRIX [ROWS=3; VALUES=2,1,3] D PRINT D