Software architecture

Architecture diagram

Architecture description

Below we explain in words the high-level software architecture of the PCNtoolkit as seen in the diagram above. To better separate the classes we split them 5 thematic categories:

1. Normative modelling

NormativeModel (normative_model.py)

It is the orchestrator you interact with. To use it: construct it around a regression model, then fit → predict (or fit_predict). It also exposes transfer, extend, merge (federated learning) and computes Z-scores / centiles. It owns a RegressionModel as its template, plus one fitted model per response variable. It has an Evaluator and a set of Scalers, and it gets the test and train data from NormData.

RegressionModel (regression_model/regression_model.py)

It is the abstract base which creates a template every model implements (fit, forward, backward, transfer). The model type lives in its two subclasses:

• BLR (blr.py)
• HBR (hbr.py)

2. Math behind normative modelling

Algorithms used by the regression models. Each is an abstract base + subclasses.

• BLR (regression_model/blr.py): + uses BasisFunction (separate mean/var basis) and can use WarpBase (w-BLR: fit non-Gaussian distributions).
• HBR (regression_model/hbr.py): uses a Likelihood → composes BasePrior → composes BasisFunction (only if LinearPrior is selected).

3. Data

NormData (dataio/norm_data.py)

Extends xarray's Dataset and carries X (covariates), Y (responses), batch effects, and results (Z, centiles). Can hold arrays with different dimensions. Built via from_dataframe / from_ndarrays / from_paths.

4. Longitudinal normative modelling

Once you have a fit-predicted NormativeModel, you can move to longitudinal scoring.

LongitudinalScore (longitudinal_score/)

It is the abstract base class. It requires a fitted model and rejects cross-sectional data. Two scores supported now:

• ZDiffScore: BLR-only, exactly two timepoints.
• ZGainScore: works with any RegressionModel, estimates a correlation matrix R, supports thrive lines. The math behind ZGainScore are in velocity.py (computes correlation matrix, thrive lines, z-gain).

5. Infrastructure layer

Runner (util/runner.py)

Wraps fit/predict to run parallel / on a cluster (SLURM/Torque) and handle cross-validation. Uses NormativeModel

Evaluator (util/evaluator.py)

Computes statistical metrics (R², RMSE, MSLL, ...) on results.

plotter (util/plotter.py)

Plot centile curves

CLI (normative.py)

Lets you run models from the terminal instead of writing Python. It's a thin layer: it reads a config, then calls the same fit/predict/load_data