Skip to content

Fitting

FitStMoMo

Result of fitting a :class:~pystmomo.core.StMoMo model.

Attributes:

Name Type Description
model

The StMoMo model specification that was fitted.
ax

Static age function coefficients α_x, shape (n_ages,), or None.
bx

Period age-modulating functions β_x, shape (n_ages, N). For parametric models, this stores the age-function evaluations. For non-parametric models (LC, RH), this is the freely-fitted β_x.
kt

Period indexes κ_t, shape (N, n_years).
b0x

Cohort age-modulating function β_x^(0), shape (n_ages,), or None.
gc

Cohort index γ_c, shape (n_cohorts,), or None.
Dxt

Observed deaths, shape (n_ages, n_years).
Ext

Exposures, shape (n_ages, n_years).
wxt

Binary weight matrix, shape (n_ages, n_years).
oxt

Log-exposure offset, shape (n_ages, n_years).
ages, years, cohorts

Age, year, and cohort vectors.
fitted_rates

Fitted mortality rates μ_xt (Poisson) or q_xt (Binomial).
fitted_deaths

Fitted expected deaths E_xt · μ_xt.
loglik

Maximised log-likelihood.
deviance

Model deviance.
npar

Number of estimated parameters.
nobs

Number of observations (weighted cells).
converged

Whether the optimisation converged.
n_iter

Number of IRLS iterations (bilinear path only; -1 for GLM path).
Source code in src/pystmomo/fit/fit_result.py 
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
class FitStMoMo:
    """Result of fitting a :class:`~pystmomo.core.StMoMo` model.

    Attributes
    ----------
    model:
        The StMoMo model specification that was fitted.
    ax:
        Static age function coefficients α_x, shape (n_ages,), or None.
    bx:
        Period age-modulating functions β_x, shape (n_ages, N).
        For parametric models, this stores the age-function evaluations.
        For non-parametric models (LC, RH), this is the freely-fitted β_x.
    kt:
        Period indexes κ_t, shape (N, n_years).
    b0x:
        Cohort age-modulating function β_x^(0), shape (n_ages,), or None.
    gc:
        Cohort index γ_c, shape (n_cohorts,), or None.
    Dxt:
        Observed deaths, shape (n_ages, n_years).
    Ext:
        Exposures, shape (n_ages, n_years).
    wxt:
        Binary weight matrix, shape (n_ages, n_years).
    oxt:
        Log-exposure offset, shape (n_ages, n_years).
    ages, years, cohorts:
        Age, year, and cohort vectors.
    fitted_rates:
        Fitted mortality rates μ_xt (Poisson) or q_xt (Binomial).
    fitted_deaths:
        Fitted expected deaths E_xt · μ_xt.
    loglik:
        Maximised log-likelihood.
    deviance:
        Model deviance.
    npar:
        Number of estimated parameters.
    nobs:
        Number of observations (weighted cells).
    converged:
        Whether the optimisation converged.
    n_iter:
        Number of IRLS iterations (bilinear path only; -1 for GLM path).
    """

    def __init__(
        self,
        model: StMoMo,
        ax: np.ndarray | None,
        bx: np.ndarray,
        kt: np.ndarray,
        b0x: np.ndarray | None,
        gc: np.ndarray | None,
        Dxt: np.ndarray,
        Ext: np.ndarray,
        wxt: np.ndarray,
        oxt: np.ndarray,
        ages: np.ndarray,
        years: np.ndarray,
        cohorts: np.ndarray,
        fitted_rates: np.ndarray,
        fitted_deaths: np.ndarray,
        loglik: float,
        deviance: float,
        npar: int,
        nobs: int,
        converged: bool = True,
        n_iter: int = -1,
    ) -> None:
        self.model = model
        self.ax = ax
        self.bx = bx
        self.kt = kt
        self.b0x = b0x
        self.gc = gc
        self.Dxt = Dxt
        self.Ext = Ext
        self.wxt = wxt
        self.oxt = oxt
        self.ages = ages
        self.years = years
        self.cohorts = cohorts
        self.fitted_rates = fitted_rates
        self.fitted_deaths = fitted_deaths
        self.loglik = loglik
        self.deviance = deviance
        self.npar = npar
        self.nobs = nobs
        self.converged = converged
        self.n_iter = n_iter

    # ------------------------------------------------------------------
    # Convenience statistics
    # ------------------------------------------------------------------

    def aic(self) -> float:
        """Akaike Information Criterion: -2·loglik + 2·npar."""
        return -2.0 * self.loglik + 2.0 * self.npar

    def bic(self) -> float:
        """Bayesian Information Criterion: -2·loglik + npar·log(nobs)."""
        return -2.0 * self.loglik + self.npar * np.log(self.nobs)

    def residuals(
        self, kind: Literal["deviance", "pearson", "response"] = "deviance"
    ) -> np.ndarray:
        """Compute residuals.

        Parameters
        ----------
        kind:
            Type of residuals: ``"deviance"``, ``"pearson"``, or ``"response"``.

        Returns
        -------
        np.ndarray
            Residual matrix, shape (n_ages, n_years).  Masked cells are 0.
        """
        from ..diagnostics.residuals import (
            deviance_residuals,
            pearson_residuals,
            response_residuals,
        )

        if kind == "deviance":
            return deviance_residuals(self)
        elif kind == "pearson":
            return pearson_residuals(self)
        elif kind == "response":
            return response_residuals(self)
        else:
            raise ValueError(f"Unknown residual kind: {kind!r}")

    # ------------------------------------------------------------------
    # Downstream methods (delegate to submodules)
    # ------------------------------------------------------------------

    def forecast(
        self,
        h: int = 50,
        *,
        kt_method: Literal["mrwd", "arima"] = "mrwd",
        gc_method: Literal["arima", "mrwd"] = "arima",
        level: float = 0.95,
        **kwargs,
    ) -> ForStMoMo:
        """Forecast future mortality rates.  See :func:`~pystmomo.forecast.forecast`."""
        from ..forecast.forecast import forecast
        return forecast(self, h=h, kt_method=kt_method, gc_method=gc_method,
                        level=level, **kwargs)

    def simulate(
        self,
        nsim: int = 1000,
        h: int = 50,
        *,
        seed: int | None = None,
        **kwargs,
    ) -> SimStMoMo:
        """Simulate future mortality trajectories.  See :func:`~pystmomo.simulate.simulate`."""
        from ..simulate.simulate import simulate
        return simulate(self, nsim=nsim, h=h, seed=seed, **kwargs)

    def bootstrap(
        self,
        nboot: int = 500,
        *,
        method: Literal["semiparametric", "residual"] = "semiparametric",
        **kwargs,
    ) -> BootStMoMo:
        """Bootstrap parameter uncertainty.  See :func:`~pystmomo.bootstrap`."""
        from ..bootstrap.residual_boot import residual_bootstrap
        from ..bootstrap.semipar_boot import semiparametric_bootstrap
        if method == "semiparametric":
            return semiparametric_bootstrap(self, nboot=nboot, **kwargs)
        else:
            return residual_bootstrap(self, nboot=nboot, **kwargs)

    def __repr__(self) -> str:
        conv = "converged" if self.converged else "NOT converged"
        return (
            f"FitStMoMo(\n"
            f"  model = {self.model}\n"
            f"  ages  = {self.ages[0]}–{self.ages[-1]}  ({len(self.ages)} ages)\n"
            f"  years = {self.years[0]}–{self.years[-1]}  ({len(self.years)} years)\n"
            f"  nobs  = {self.nobs},  npar = {self.npar}\n"
            f"  loglik = {self.loglik:.2f},  deviance = {self.deviance:.2f}\n"
            f"  AIC = {self.aic():.2f},  BIC = {self.bic():.2f}\n"
            f"  {conv}\n"
            f")"
        )

aic()

Akaike Information Criterion: -2·loglik + 2·npar.

Source code in src/pystmomo/fit/fit_result.py 
112
113
114
def aic(self) -> float:
    """Akaike Information Criterion: -2·loglik + 2·npar."""
    return -2.0 * self.loglik + 2.0 * self.npar

bic()

Bayesian Information Criterion: -2·loglik + npar·log(nobs).

Source code in src/pystmomo/fit/fit_result.py 
116
117
118
def bic(self) -> float:
    """Bayesian Information Criterion: -2·loglik + npar·log(nobs)."""
    return -2.0 * self.loglik + self.npar * np.log(self.nobs)

bootstrap(nboot=500, *, method='semiparametric', **kwargs)

Bootstrap parameter uncertainty. See :func:~pystmomo.bootstrap.

Source code in src/pystmomo/fit/fit_result.py 
180
181
182
183
184
185
186
187
188
189
190
191
192
193
def bootstrap(
    self,
    nboot: int = 500,
    *,
    method: Literal["semiparametric", "residual"] = "semiparametric",
    **kwargs,
) -> BootStMoMo:
    """Bootstrap parameter uncertainty.  See :func:`~pystmomo.bootstrap`."""
    from ..bootstrap.residual_boot import residual_bootstrap
    from ..bootstrap.semipar_boot import semiparametric_bootstrap
    if method == "semiparametric":
        return semiparametric_bootstrap(self, nboot=nboot, **kwargs)
    else:
        return residual_bootstrap(self, nboot=nboot, **kwargs)

forecast(h=50, *, kt_method='mrwd', gc_method='arima', level=0.95, **kwargs)

Forecast future mortality rates. See :func:~pystmomo.forecast.forecast.

Source code in src/pystmomo/fit/fit_result.py 
154
155
156
157
158
159
160
161
162
163
164
165
166
def forecast(
    self,
    h: int = 50,
    *,
    kt_method: Literal["mrwd", "arima"] = "mrwd",
    gc_method: Literal["arima", "mrwd"] = "arima",
    level: float = 0.95,
    **kwargs,
) -> ForStMoMo:
    """Forecast future mortality rates.  See :func:`~pystmomo.forecast.forecast`."""
    from ..forecast.forecast import forecast
    return forecast(self, h=h, kt_method=kt_method, gc_method=gc_method,
                    level=level, **kwargs)

residuals(kind='deviance')

Compute residuals.

Parameters:

Name Type Description Default
kind Literal['deviance', 'pearson', 'response']

Type of residuals: "deviance", "pearson", or "response".

 'deviance'

Returns:

Type Description
ndarray

Residual matrix, shape (n_ages, n_years). Masked cells are 0.
Source code in src/pystmomo/fit/fit_result.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def residuals(
    self, kind: Literal["deviance", "pearson", "response"] = "deviance"
) -> np.ndarray:
    """Compute residuals.

    Parameters
    ----------
    kind:
        Type of residuals: ``"deviance"``, ``"pearson"``, or ``"response"``.

    Returns
    -------
    np.ndarray
        Residual matrix, shape (n_ages, n_years).  Masked cells are 0.
    """
    from ..diagnostics.residuals import (
        deviance_residuals,
        pearson_residuals,
        response_residuals,
    )

    if kind == "deviance":
        return deviance_residuals(self)
    elif kind == "pearson":
        return pearson_residuals(self)
    elif kind == "response":
        return response_residuals(self)
    else:
        raise ValueError(f"Unknown residual kind: {kind!r}")

simulate(nsim=1000, h=50, *, seed=None, **kwargs)

Simulate future mortality trajectories. See :func:~pystmomo.simulate.simulate.

Source code in src/pystmomo/fit/fit_result.py 
168
169
170
171
172
173
174
175
176
177
178
def simulate(
    self,
    nsim: int = 1000,
    h: int = 50,
    *,
    seed: int | None = None,
    **kwargs,
) -> SimStMoMo:
    """Simulate future mortality trajectories.  See :func:`~pystmomo.simulate.simulate`."""
    from ..simulate.simulate import simulate
    return simulate(self, nsim=nsim, h=h, seed=seed, **kwargs)