Skip to contents

Model Quantity Index Table

Source: R/mp_index.R
mp_index.Rd

Make an index table to enumerate model quantity labels by category. These objects generalize and wrap data.frames, where each column is a label category and each row is an index. Indices must contain only letters, numbers, and underscores. Blank empty string entries are allowed, but missing values (NAs) are not.

Usage

mp_index(..., labelling_column_names)

# S3 method for class 'Index'
print(x, ...)

# S3 method for class 'Index'
names(x)

# S3 method for class 'Index'
labelling_column_names(x)

# S3 method for class 'Index'
labels(object, ...)

Arguments

...

Character vectors to combine to produce an index. Alternatively, any number of data frames of character-valued columns. If data frames are supplied, their rows will be bound and the result converted to an index if possible.

labelling_column_names

A character vector of the names of the index that will be used to label the model components (i.e. rows) being described. The labelling_column_names cannot have duplicates and must contain at least one name. The index given by the labelling_column_names must uniquely identify each row. The default NULL gives the set of columns, in order starting with the first column, that are required to uniquely identify each row.

x

An index.

object

An index.

Details

For example, the following index table describes the state variables of the model:

sir = mp_index(Epi = c("S", "I", "R"))
print(sir)
#>  Epi
#>    S
#>    I
#>    R

Here, the column Epi denotes that the category of these labels is epidemiological. There is nothing special about this specific choice of category name; we could have also used another name like Compartment.

However, in more complicated models, it is good to think carefully about choosing descriptive category names. For example, in an age-structured SIR model, we could add an Age column to generate an index table as follows:

sir_age = mp_index(
 Epi = rep(c("S", "I", "R"), 2),
 Age = rep(c("young", "old"), each = 3)
)
print(sir_age)
#>  Epi   Age
#>    S young
#>    I young
#>    R young
#>    S   old
#>    I   old
#>    R   old

Here, having the first column in the index table labeled Compartment would be somewhat misleading, as the compartments aren't actually just "S", "I", and "R", they are each of the epidemiological states stratified by the age groups "young" and "old".

This index table could also be generated by first specifying individual index tables for the Epi and Age columns, and then using a macpan2 product function that combines the tables into a single index table:

sir = mp_index(Epi = c("S", "I", "R"))
age = mp_index(Age = c("young", "old"))
prod = mp_cartesian(sir, age)
prod
#>  Epi   Age
#>    S young
#>    I young
#>    R young
#>    S   old
#>    I   old
#>    R   old

The mp_cartesian() function will produce a table with entries that are all possible combinations of the individual index tables. The "See Also" section of the mp_cartesian() help page catalogues all available product functions.

We can produce the full labels of model quantities, which are simply dot-concatenated indices, one for each entry in the index table, using the labels() function:

#> [1] "S.young" "I.young" "R.young" "S.old"   "I.old"   "R.old"

Dots are not allowed in indices so that the labels can be inverted to reproduce the original index table (provided that the column names can be retrieved).

It is recommended to use UpperCamelCase for the columns of index tables and single uppercase characters ("S", "I"), all lowercase character strings ("gamma"), and/or snake_case strings ("aging_rate") for indices. This convention helps when reading code that contains references to both column names and indices.

Functions

  • print(Index): Print an index.

  • names(Index): Get the names of the columns of an index.

  • labelling_column_names(Index): Retrieve the labelling_column_names of an index. These are the names of the columns that are used to label the model components.

  • labels(Index): Convert an index into a character vector giving labels associated with each model component (i.e. row) being described.

See also

mp_structured_vector()

mp_set_numbers()

Other functions that return index tables mp_cartesian(), mp_rename(), mp_subset(), mp_union()

Examples

state = mp_index(
  Epi = c("S", "I", "S", "I"),
  Age = c("young", "young", "old", "old")
)
print(state)
#>  Epi   Age
#>    S young
#>    I young
#>    S   old
#>    I   old
labels(state)
#> [1] "S.young" "I.young" "S.old"   "I.old"  
mp_cartesian(state, mp_index(City = c("hamilton", "toronto")))
#>  Epi   Age     City
#>    S young hamilton
#>    I young hamilton
#>    S   old hamilton
#>    I   old hamilton
#>    S young  toronto
#>    I young  toronto
#>    S   old  toronto
#>    I   old  toronto