Hierarchisation

info

We adopt the nomenclature of Brenner, Weber et al. (2025): shared parameters are group-level and model-specific parameters are subject-level.

In a similar fashion as measurements were defined by the assumed measurement function, hierarchisation defines the assumed dynamical differences between observed systems. As described in detail in the mathematical background, the hierarchical approach should be used in cases when the observed systems' dynamics are assumed to be similar, but not identical. In real-world systems similarity is not defined mathematically, rather it is a scientific assumption. For example one may assume that two subjects solving the same task implement similar dynamics, with subject-to-subject differences.

note

As a high-level architectural method, the hierarchical approach is model-agnostic. Any implemented reconstruction model can be used, and new models can be adapted to support it. See the corresponding description for implementation details.

Configuring hierarchical structures

To train a single model on the entire dataset without hierarchisation, set dsr_hierarchisation_scheme to:

{
    "sheme": "none"
}

Hierarchisation schemes

Otherwise, dsr_hierarchisation_scheme defines how group and subject parameters combine. It requires a dictionary with scheme, feature_dim, and potentially scheme-specific parameters.

The feature_dim parameter sets the dimension of the subject space, in other words it is the dimension of the initialized subject vectors. Choosing the feature_dim incorporates a trade off: larger values make the model more expressive on the expense of the interpretability of the feature space.

scheme is a string defining the combination method. Implemented schemes are:

linear-projection

Assigns a group-level projection matrix $P_A$ to each parameter $A$. This is projected onto the subject vector $p^{(i)}$ with an optional bias $b^{(i)}$:

$A^{(i)} = P_A^{\text{(group)}} \cdot p^{(i)} + b^{(i)},$

where $\cdot$ is the inner product. $b^{(i)}$ is learned only if the additional parameter with_bias is set to True.

outer-product

Assigns group-level projection vectors $P_A$ and $Q_A$ to each parameter $A$. These are combined with the subject vector via an outer product:

$A^{(i)} = P_A^{\text{(group)}} \cdot (R^{\text{(group)}}\cdot p^{(i)}) \cdot Q_A^{\text{(group)}}$,

where $R^{\text{(group)}}$ is an optional matrix projecting the subject vector into a higher dimension.The dimension can be set by additional parameter projection_dimension. If not set, no projection is applied.

tip

Based on internal testing, we advise the use of linear-projection with with_bias set to True.

Linking the dataset to subjects

To train a hierarchical model on the dataset, the timeseries defined in the dataset need to be linked to (hierarchical) subjects. This is done by grouping timeseries together, for each of which a subject vector is created. Linking the timeseries makes sure that the correct subject weights are trained using the correct timeseries.

In the configuration this is done via the dsr_subject_groups parameter. This is a dictionary expecting two keys:

{
    "mode": Literal["per-timeseries", "per-measurement", "custom"],
    "custom_groups": Optional[list[list[{
        "measurement_id": int,
        "timeseries_index": Optional[int],
    }]]]
}

per-timeseries

This mode creates one subject vector per timeseries defined. Note that if selecting this option and assigning test_timeseries_indices will trigger the use of train_test_split as leaving out the whole timeseries for testing would result in an empty train set for the given subject vector.

The custom_groups key is ignored.

per-measurement

This mode creates one subject vector per measurement defined. This will never trigger train_test_split so make sure that each measurement which has timeseries assigned to in test_timeseries_indices contains more than one timeseries.

The custom_groups key is ignored

custom

This mode allows for full customization of the groups. The required custom_groups key has the following signature: Each inner list defines one group of timeseries linked to a subject vector. The dictionaries it contains are identifiers of a timeseries, each contains the measurement's identifier and the timeseries' index within the measurement.

In total as many subject vectors will be created as as entries in the custom_groups list, each of which will be linked to the timeseries in the respective group.

tip

The timeseries_index is optional. If it is omitted, all timeseries in the given measurement will be linked to the given subject. No timeseries may be assigned (neither implicitly by omission of the timeseries_index nor explicitly) to more than one subject.

Hierarchisation of the encoder model

The idea of representing commonalities and differences in the data using the hierarchical approach is not limited to dynamical systems. Hence the encoder model was also equipped with the ability to be used in this hierarchical fashion.

Although the code provides the option, and parameters such as the encoder_hierarchisation exist, no hierarchical approach has been implemented yet.

note

The hierarchical approach has not been implemented for decoders as these are implemented as GLMs and thus contain only a handful of parameters.