ModelInterface#

Module: leaspy.models.base

At the very top of the Leaspy model hierarchy sits ModelInterface. This is not a model you can use directly; it is a contract. It strictly defines what a Leaspy model is and what it must do.

What is an Interface?#

In software design, an interface acts like a blueprint. It declares the methods and properties that a class must implement, without providing the method code itself. This ensures consistency: any object that claims to be a “Leaspy Model” is guaranteed to have the standard methods (fit, estimate, personalize) that the algorithms expect.

Use an Abstract Base Class (ABC) when you want to provide a common interface for a set of subclasses. — Python abc module documentation

The Contract: Mandatory Capabilities#

Any valid Leaspy model must provide implementations for these capabilities:

Core Properties#

  • name & dimension: Identity and structure of the model.

  • features: The specific variable names (e.g., “memory”, “attention”) corresponding to the dimensions.

  • is_initialized: A flag indicating if the model has been set up with data.

  • parameters & hyperparameters: Access to the underlying mathematical values (fixed effects).

Core Methods#

  • fit(data, algorithm): Estimate the model parameters from population data.

  • personalize(data): Estimate individual parameters for specific subjects.

  • estimate(timepoints, individual_parameters): Predict values for subjects at specific times.

  • simulate(individual_parameters, ...): Generate synthetic data based on model parameters.

I/O#

  • save(path) & load(path): Serialize the model to/from JSON files for storage.

The Hierarchy: Interface, Base, and Concrete Models#

In Leaspy, we organize models into a hierarchy to separate the “rules” from the bit-by-bit “implementation”.

  1. The Contract (ModelInterface): This is the strict rulebook. It defines what a model must do (like fit or personalize) but contains no logic. It ensures that every Leaspy model looks the same to the outside world.

  2. The Foundation (Intermediate classes): These classes (BaseModel, TimeReparametrizedModel, RiemanianManifoldModel) sit between the interface and the final model. They are a mix of implementation and definition:

    • They implement key logic: They handle file storage, input validation, and the core algorithms like time reparametrization (\( \alpha(t - \tau) \)).

    • They leave specific “holes”: They define abstract methods for the parts that vary, such as the shape of the manifold or the specific reaction to time. This forces the final model to provide just these missing pieces.

  3. The Concrete Model (LogisticModel): This is the final, usable model. It inherits all the structural logic from the foundation and fills in the specific mathematical “holes” — for example, defining the logistic sigmoid function \( \frac{1}{1 + e^{-x}} \) as the shape of the manifold.

Why Do We Need This?#

The algorithms in Leaspy (like MCMC-SAEM) are designed to be generic. They don’t want to know if they are optimizing a LogisticModel or a custom MyNewModel. They only want to know that the object passed to them has a .fit() method and a .parameters property. As long as your new class inherits from ModelInterface and implements these methods, it will work with all existing Leaspy algorithms.

Moving to Implementation: BaseModel#

ModelInterface tells us what to do, but it doesn’t do anything itself. Implementing all these methods from scratch for every new model would be tedious and error-prone.

To solve this, we have BaseModel. It takes this contract and provides the standard “plumbing” — the shared code that orchestrates how these methods work together.