Make an index table to enumerate model quantity labels by category. These
objects generalize and wrap data.frame
s, 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 (NA
s) are not.
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. Thelabelling_column_names
cannot have duplicates and must contain at least one name. The index given by thelabelling_column_names
must uniquely identify each row. The defaultNULL
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
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 thelabelling_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
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
# 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(prod)
#> [1] "S.young" "I.young" "R.young" "S.old" "I.old" "R.old"