API Documentation

Metran

The Metran model class.

class metran.metran.Metran(oseries, name='Cluster', freq=None, tmin=None, tmax=None)[source]

Class for the Pastas Metran model.

Parameters:

  • oseries (pandas.DataFrame, list of pandas.Series or pastas.TimeSeries) – Time series to be analyzed. Index must be DatetimeIndex. The series can be non-equidistant.

  • name (str, optional) – String with the name of the model. The default is ‘Cluster’

  • freq (str, optional) – String with the frequency the stressmodels are simulated. Must be one of the following (D, h, m, s, ms, us, ns) or a multiple of that e.g. “7D”.

  • tmin (str, optional) – String with a start date for the simulation period (E.g. ‘1980’). If none is provided, the tmin from the oseries is used.

  • tmax (str, optional) – String with an end date for the simulation period (E.g. ‘2010’). If none is provided, the tmax from the oseries is used.

Returns:

mt – Metran instance.

Return type:

metran.Metran

_get_file_info()[source]

Internal method to get the file information.

Returns:

file_info – dictionary with file information.

Return type:

dict

_get_matrices(p, initial=False)[source]

Internal method to get all matrices.

Returns all matrices required to define the Metran dynamic factor model.

Parameters:

  • p (pandas.Series) – Model parameters.

  • initial (bool, optional) – Determines whether to use initial (True) or optimal (False) parameters. The default is False.

Returns:

  • numpy.ndarray – Transition matrix.

  • numpy.ndarray – Transition covariance matrix.

  • numpy.ndarray – Observation matrix.

  • numpy.ndarray – Observation variance vector.

_init_kalmanfilter(oseries, engine='numba')[source]

Internal method, initialize Kalmanfilter for sequential processing.

Parameters:

  • oseries (pandas.DataFrame) – Series being processed by the Kalmanfilter.

  • engine (str, optional) – Engine used for the Kalman filter, by default ‘numba’ which is the fastest choice but ‘numpy’ is also available, but is slower.

Return type:

None.

_phi(alpha)[source]

Internal method to calculate autoregressive model parameter.

Autoregressive model parameter is calculated based on parameter alpha.

Parameters:

alpha (float) – model parameter

Returns:

autoregressive model parameter

Return type:

float

_run_kalman(method, p=None)[source]

Internal method to (re)run Kalman filter or smoother.

Parameters:

  • method (str, optional) – Use “filter” to run Kalman filter, and “smoother” to run Kalman smoother. The default is “smoother”.

  • p (pandas.Series) – Model parameters. The default is None.

Return type:

None.

decompose_simulation(name, p=None, standardized=False, method='smoother')[source]

Decompose simulation into specific and common dynamic components.

Method to get for observed series filtered/smoothed estimate decomposed into specific dynamic component (sdf) and the sum of common dynamic components (cdf).

Parameters:

  • name (str) – name of series to be obtained.

  • p (pandas.Series) – Model parameters. The default is None.

  • standardized (bool, optional) – If True, obtain estimates for standardized series. If False, obtain estimates for unstandardized series. The default is False.

  • method (str, optional) – Use “filter” to obtain filtered estimates, and “smoother” to obtain smoothed estimates. The default is “smoother”.

Returns:

df – DataFrame with specific and common dynamic component for series with name ‘name’.

Return type:

pandas.DataFrame

fit_report(output='full')[source]

Method that reports on the fit after a model is optimized.

Parameters:

output (str, optional) – If any other value than “full” is provided, the parameter correlations will be removed from the output.

Returns:

report – String with the report.

Return type:

str

Examples

This method is called by the solve method if report=True, but can also be called on its own:

>>> print(mt.fit_report())
get_communality()[source]

Get fraction that is explained by the common dynamic factor(s).

Calculate communality for each series.

Returns:

For each series the communality, a value between 0 and 1. A value of 0 means that the series has no variation in common with other series. A value of 1 means that the series has all variation in common.

Return type:

numpy.ndarray

get_factors(oseries=None)[source]

Method to get factor loadings based on factor analysis.

This method also gets some relevant results from the factor analysis including the eigenvalues and percentage explained by factors (fep).

Parameters:

oseries (pandas.DataFrame, optional) – Series to be analyzed. The default is None.

Returns:

factors – Factor loadings as estimated using factor analysis

Return type:

numpy.ndarray

get_mle(p)[source]

Method to obtain maximum likelihood estimate based on Kalman filter.

Parameters:

p (pandas.Series) – Model parameters.

Returns:

mle – Maximum likelihood estimate.

Return type:

float

get_observation_matrix(p=None, initial=False)[source]

Method to get observation matrix of the Metran dynamic factor model.

Parameters:

  • p (pandas.Series, optional) – Model parameters. The default is None.

  • initial (bool, optional) – Determines whether to use initial (True) or optimal (False) parameters. The default is False.

Returns:

observation_matrix – Observation matrix

Return type:

numpy.ndarray

get_observation_variance()[source]

Method to get observation matrix.

Currently the observation variance is zero by default.

Returns:

observation_variance – Observation variance vector

Return type:

numpy.ndarray

get_observations(standardized=False, masked=False)[source]

Returns series as available in Metran class.

Parameters:

  • standardized (bool, optional) – If True, obtain standardized observations. If False, obtain unstandardized observations. The default is False.

  • masked (boolean) – If True, return masked observations. The default is False.

Returns:

Time series.

Return type:

pandas.DataFrame

get_parameters(initial=False)[source]

Method to get all parameters from the individual objects.

Parameters:

initial (bool, optional) – True to get initial parameters, False to get optimized parameters. If optimized parameters do not exist, return initial parameters.

Returns:

parameters – initial or optimal parameters.

Return type:

pandas.Series

get_scaled_observation_matrix(p=None)[source]

Method scale observation matrix by standard deviations of oseries.

Returns:

  • observation_matrix (numpy.ndarray) – scaled observation matrix

  • p (pandas.Series) – Model parameters. The default is None.

get_simulated_means(p=None, standardized=False, method='smoother')[source]

Method to calculate simulated means.

Simulated means are the filtered/smoothed mean estimates for the observed series.

Parameters:

  • p (pandas.Series) – Model parameters. The default is None.

  • standardized (bool, optional) – If True, obtain estimates for standardized series. If False, obtain estimates for unstandardized series. The default is False.

  • method (str, optional) – Use “filter” to obtain filtered estimates, and “smoother” to obtain smoothed estimates. The default is “smoother”.

Returns:

simulated_means – Filtered or smoothed estimates for observed series.

Return type:

pandas.DataFrame

get_simulated_variances(p=None, standardized=False, method='smoother')[source]

Method to calculate simulated variances,

The simulated variances are the filtered/smoothed variances for the observed series.

Parameters:

  • p (pandas.Series) – Model parameters. The default is None.

  • standardized (bool, optional) – If True, obtain estimates for standardized series. If False, obtain estimates for unstandardized series. The default is False.

  • method (str, optional) – Use “filter” to obtain filtered estimates, and “smoother” to obtain smoothed estimates. The default is “smoother”.

Returns:

simulated_variances – Filtered or smoothed variances for observed series.

Return type:

pandas.DataFrame

get_simulation(name, p=None, alpha=0.05, standardized=False, method='smoother')[source]

Method to calculate simulated means for specific series.

Optionally including 1-alpha confidence interval.

Parameters:

  • name (str) – name of series to be obtained

  • p (pandas.Series) – Model parameters. The default is None.

  • alpha (float, optional) – Include (1-alpha) confidence interval in DataFrame. The value of alpha must be between 0 and 1. If None, no confidence interval is returned. The default is 0.05.

  • standardized (bool, optional) – If True, obtain estimates for standardized series. If False, obtain estimates for unstandardized series. The default is False.

  • method (str, optional) – Use “filter” to obtain filtered estimates, and “smoother” to obtain smoothed estimates. The default is “smoother”.

Returns:

proj – filtered or smoothed estimate (mean) for series ‘name’, optionally with ‘lower’ and ‘upper’ as lower and upper bounds of 95% confidence interval.

Return type:

pandas.DataFrame

get_specificity()[source]

Get fraction that is explained by the specific dynamic factor.

Calculate specificity for each series. The specificity is equal to (1 - communality).

Returns:

For each series the specificity, a value between 0 and 1. A value of 0 means that the series has all variation in common with other series. A value of 1 means that the series has no variation in common.

Return type:

numpy.ndarray

get_state(i, p=None, alpha=0.05, method='smoother')[source]

Get filtered or smoothed mean for specific state.

Optionally including the 1-alpha confidence interval.

Parameters:

  • i (int) – index of state vector to be obtained

  • p (pandas.Series) – Model parameters. The default is None.

  • alpha (float, optional) – Include (1-alpha) confidence interval in DataFrame. The value of alpha must be between 0 and 1. If None, no confidence interval is returned. The default is 0.05.

  • method (str, optional) – Use “filter” to obtain filtered variances, and “smoother” to obtain smoothed variances. The default is “smoother”.

Returns:

state – ith filtered or smoothed state (mean), optionally with ‘lower’ and ‘upper’ as lower and upper bounds of 95% confidence interval.

Return type:

pandas.DataFrame

get_state_means(p=None, method='smoother')[source]

Method to get filtered or smoothed state means.

Parameters:

  • p (pandas.Series) – Model parameters. The default is None.

  • method (str, optional) – Use “filter” to obtain filtered states, and “smoother” to obtain smoothed states. The default is “smoother”.

Returns:

state_means – Filtered or smoothed states. Column names refer to specific dynamic factors (sdf) and common dynamic factors (cdf)

Return type:

pandas.DataFrame

get_state_variances(p=None, method='smoother')[source]

Method to get filtered or smoothed state variances.

Parameters:

  • p (pandas.Series) – Model parameters. The default is None.

  • method (str, optional) – Use “filter” to obtain filtered variances, and “smoother” to obtain smoothed variances. The default is “smoother”.

Returns:

state_variances – Filtered or smoothed variances. Column names refer to specific dynamic factors (sdf) and common dynamic factors (cdf)

Return type:

pandas.DataFrame

get_transition_covariance(p=None, initial=False)[source]

Get transition covariance matrix of the Metran dynamic factor model.

Parameters:

  • p (pandas.Series, optional) – Model parameters. The default is None.

  • initial (bool, optional) – Determines whether to use initial (True) or optimal (False) parameters. The default is False.

Returns:

transition_covariance – Transition covariance matrix

Return type:

numpy.ndarray

get_transition_matrix(p=None, initial=False)[source]

Method to get transition matrix of the Metran dynamic factor model.

Parameters:

  • p (pandas.Series, optional) – Model parameters. The default is None.

  • initial (bool, optional) – Determines whether to use initial (True) or optimal (False) parameters. The default is False.

Returns:

transition_matrix – Transition matrix

Return type:

numpy.ndarray

get_transition_variance(p=None, initial=False)[source]

Get the transition variance vector.

The transition variance vector is obtained by extracting the diagonal of the transition covariance matrix.

Parameters:

  • p (pandas.Series, optional) – Model parameters. The default is None.

  • initial (bool, optional) – Determines whether to use initial (True) or optimal (False) parameters. The default is False.

Returns:

transition_variance – Transition variance vector

Return type:

numpy.ndarray

mask_observations(mask)[source]

Mask observations for processing with Kalman filter or smoother.

This method does NOT change the oseries itself. It only masks (hides) observations while running the Kalman filter or smoother, so that these observations are not used for updating the Kalman filter/smoother.

Parameters:

mask (pandas.DataFrame) – DataFrame with shape of oseries containing 0 or False for observation to be kept and 1 or True for observation to be masked (hidden).

Return type:

None.

metran_report(output='full')[source]

Method that reports on the metran model results.

Parameters:

output (str, optional) – If any other value than “full” is provided, the state correlations will be removed from the output.

Returns:

report – String with the report.

Return type:

str

Examples

This method is called by the solve method if report=True, but can also be called on its own:

>>> print(mt.metran_report())
property nparam
property nstate
set_init_parameters()[source]

Method to initialize parameters to be optimized.

Return type:

None

set_observations(oseries)[source]

Rework oseries to pandas.DataFrame for further use in Metran class.

Parameters:

  • oseries (pandas.DataFrame) –

  • pandas.Series/pandas.DataFrame/pastas.TimeSeries (or list/tuple of) – Time series to be analyzed.

Raises:

Exception –

  • if a DataFrame within a list/tuple has more than one column - if input type is not correct - if number of series is less than 2 - if index of Series/DataFrame is not a DatetimeIndex

Return type:

None.

solve(solver=None, report=True, engine='numba', **kwargs)[source]

Method to solve the time series model.

Parameters:

  • solver (metran.solver.BaseSolver class, optional) – Class used to solve the model. Options are: mt.ScipySolve (default) or mt.LmfitSolve. A class is needed, not an instance of the class!

  • report (bool, optional) – Print reports to the screen after optimization finished. This can also be manually triggered after optimization by calling print(mt.fit_report()) or print(mt.metran_report()) on the Metran instance.

  • engine (str, optional) – Engine used for the Kalman filter, by default ‘numba’ which is the fastest choice but ‘numpy’ is also available, but is slower.

  • **kwargs (dict, optional) – All keyword arguments will be passed onto minimization method from the solver.

Notes

  • The solver object including some results are stored as mt.fit. From here one can access the covariance (mt.fit.pcov) and correlation matrix (mt.fit.pcor).

  • The solver returns a number of results after optimization. These are stored in mt.fit.result and can be accessed from there.

standardize(oseries)[source]

Method to standardize series.

Standardized by subtracting mean and dividing by standard deviation.

Parameters:

oseries (pandas.DataFrame) – series to be standardized

Returns:

standardized series

Return type:

pandas.DataFrame

test_cross_section(oseries=None, min_pairs=None)[source]

Method to test whether series have enough cross-sectional data.

Default threshold value is defined by self.settings[“min_pairs”].

Parameters:

  • oseries (pandas.DataFrame, optional) – Time series to be evaluated. The default is None.

  • min_pairs (int, optional) – Minimum number of cross-sectional data for each series. Should be greater than 1. The default is None.

Raises:

Exception – If one of the series has less than min_pairs of cross-sectional data and exception is raised.

Return type:

None.

truncate(oseries)[source]

Method to set start and end of series.

If tmin and/or tmax have been defined in self.settings, use these dates to trucate series. Dates with only NaN are being removed.

Parameters:

oseries (pandas.DataFrame) – series to be tructated

Returns:

truncated series

Return type:

pandas.DataFrame

unmask_observations()[source]

Method to unmask observation and reset observations.

Return type:

None

Factor Analysis

FactorAnalysis class for Metran in Pastas.

class metran.factoranalysis.FactorAnalysis(maxfactors=None)[source]

Class to perform a factor analysis for the Pastas Metran model.

Parameters:

maxfactors (int, optional.) – maximum number of factors to select. The default is None.

Examples

A minimal working example of the FactorAnalysis class is shown below:

>>> fa = FactorAnalysis()
>>> factors = fa.solve(oseries)
get_eigval_weight()[source]

Method to get the relative weight of each eigenvalue.

Returns:

All eigenvalues as a fraction of the sum of eigenvalues.

Return type:

numpy.ndarray

solve(oseries)[source]

Method to perform factor analysis.

Factor analysis is based on the minres algorithm. The number of eigenvalues is determined by MAP test. If more than one eigenvalue is used, the factors are rotated using orthogonal rotation.

Parameters:

oseries (pandas.DataFrame) – Object containing the time series. The series can be non-equidistant.

Raises:

Exception – If no proper factors can be derived from the series.

Returns:

factors – Factor loadings.

Return type:

numpy.ndarray

Kalman Filter

This module contains the Kalman filter class for Metran and associated filtering and smoothing methods.

class metran.kalmanfilter.SPKalmanFilter(engine='numba')[source]

Kalman filter class for Metran.

Parameters:

engine (str, optional) – Engine to be used to run sequential Kalman filter. Either “numba” or “numpy”. The default is “numba”.

Returns:

kf – Metran SPKalmanfilter instance.

Return type:

kalmanfilter.SPKalmanFilter

decompose(observation_matrix, method='smoother')[source]

Method to decompose simulated means.

Decomposition into specific dynamic factors (sdf) and common dynamic factors (cdf).

Parameters:

  • observation_matrix (numpy.ndarray) – Observation matrix for projecting states.

  • method (str, optional) – If “filter”, use Kalman filter to obtain estimates. If “smoother”, use Kalman smoother. The default is “smoother”.

Returns:

  • sdf_means (list) – List of specific dynamic factors for each time step.

  • cdf_means (list) – List of common dynamic factor(s) for each time step.

get_mle(warmup=1)[source]

Method to calculate maximum likelihood estimate.

Parameters:

warmup (int, optional) – Number of time steps to skip. The default is 1.

Returns:

mle – Maximum likelihood estimate.

Return type:

float

init_states()[source]

Method to initialize state means and covariances.

Return type:

None.

run_filter(initial_state_mean=None, initial_state_covariance=None, engine=None)[source]

Method to run the Kalman Filter.

This is a sequential processing implementation of the Kalman filter requiring a diagonal observation error covariance matrix. The algorithm allows for missing data using the arrays observation_count giving the number of observations for each timestep, and observation_indices containing the corresponding indices of those observations used to select the appropriate rows from observation_matrix and observation_variance. These arrays have been constructed with self.set_observations()

Parameters:

  • initial_state_mean (array_like) – state vector for initializing Kalman filter.

  • initial_state_covariance (array_like) – state covariance matrix for initializing Kalman filter.

  • engine (str, optional) – Engine to be used to run sequential Kalman filter. Either “numba” or “numpy”. The default is None, which means that the default Class setting is used.

Return type:

None

run_smoother()[source]

Run Kalman smoother.

Calculate smoothed state means and covariances using the Kalman smoother.

set_matrices(transition_matrix, transition_covariance, observation_matrix, observation_variance)[source]

Method to set matrices of state space model.

Parameters:

  • transition_matrix (numpy.ndarray) – State transition matrix

  • transition_covariance (numpy.ndarray) – State transition covariance matrix.

  • observation_matrix (numpy.ndarray) – Observation matrix.

  • observation_variance (numpy.ndarray) – Observation variance.

Return type:

None.

set_observations(oseries)[source]

Construct observation matrices allowing missing values.

Initialize sequential processing of the Kalman filter.

Parameters:

oseries (pandas.DataFrame) – multiple time series

simulate(observation_matrix, method='smoother')[source]

Method to get simulated means and covariances.

Parameters:

  • observation_matrix (numpy.ndarray) – Observation matrix for projecting states.

  • method (str, optional) – If “filter”, use Kalman filter to obtain estimates. If “smoother”, use Kalman smoother. The default is “smoother”.

Returns:

  • simulated_means (list) – List of simulated means for each time step.

  • simulated_variances (list) – List of simulated variances for each time step. Variances are diagonal elements of simulated covariance matrix.

metran.kalmanfilter.filter_predict(filtered_state_mean, filtered_state_covariance, transition_matrix, transition_covariance)[source]

Predict state with a Kalman Filter using sequential processing.

Parameters:

  • filtered_state_mean (numpy.ndarray) – Mean of state at time t-1 given observations from times [0…t-1]

  • filtered_state_covariance (numpy.ndarray) – Covariance of state at time t-1 given observations from times [0…t-1]

Returns:

  • predicted_state_mean (numpy.ndarray) – Mean of state at time t given observations from times [0…t-1]

  • predicted_state_covariance (numpy.ndarray) – Covariance of state at time t given observations from times [0…t-1]

metran.kalmanfilter.filter_update(observations, observation_matrix, observation_variance, observation_indices, observation_count, state_mean, state_covariance)[source]

Update predicted state with Kalman Filter using sequential processing.

Parameters:

  • observations (numpy.ndarray) – Observations for sequential processing of Kalman filter.

  • observation_matrix (numpy.ndarray) – observation matrix to project state.

  • observation_variance (numpy.ndarray) – observation variances

  • observation_indices (numpy.ndarray) – used to compress observations, observation_matrix, and observation_variance skipping missing values.

  • observation_count (numpy.ndarray) – number of observed time series for each timestep determining the number of elements to be read in observation_indices.

  • state_mean (numpy.ndarray) – mean of state at time t given observations from times [0…t-1]

  • state_covariance (numpy.ndarray) – covariance of state at time t given observations from times [0…t-1]

Returns:

  • state_mean ([n_dim_state] array) – Mean of state at time t given observations from times [0…t], i.e. updated state mean

  • state_covariance ([n_dim_state, n_dim_state] array) – Covariance of state at time t given observations from times [0…t], i.e. updated state covariance

  • sigma (float) – Weighted squared innovations.

  • detf (float) – Log of determinant of innovation variances matrix.

metran.kalmanfilter.kalmansmoother(filtered_state_means, filtered_state_covariances, predicted_state_means, predicted_state_covariances, transition_matrix)[source]

Method to run the Kalman smoother.

Estimate the hidden state at time for each time step given all observations.

Parameters:

  • filtered_state_means (array_like) – filtered_state_means[t] = mean state estimate for time t given observations from times [0…t].

  • filtered_state_covariances (array_like) – filtered_state_covariances[t] = covariance of state estimate for time t given observations from times [0…t].

  • predicted_state_means (array_like) – predicted_state_means[t] = mean state estimate for time t given observations from times [0…t-1].

  • predicted_state_covariances (array_like) – predicted_state_covariances[t] = covariance of state estimate for time t given observations from times [0…t-1].

  • transition_matrix (numpy.ndarray) – State transition matrix from time t-1 to t.

Returns:

  • smoothed_state_means (numpy.ndarray) – Mean of hidden state distributions for times [0…n_timesteps-1] given all observations

  • smoothed_state_covariances (numpy.ndarray) – Covariance matrix of hidden state distributions for times [0…n_timesteps-1] given all observations

metran.kalmanfilter.seqkalmanfilter(observations, transition_matrix, transition_covariance, observation_matrix, observation_variance, observation_indices, observation_count, filtered_state_mean, filtered_state_covariance)[source]

Method to run sequential Kalman filter optimized for use with numba.

This method requires numba to be installed. With numba, this method is much faster than seqkalmanfilter_np. However, without numba, it is extremely slow and seqkalmanfilter_np should be used.

Parameters:

  • observations (numpy.ndarray) – Observations for sequential processing of Kalman filter.

  • transition_matrix (numpy.ndarray) – State transition matrix from time t-1 to t.

  • transition_covariance (numpy.ndarray) – State transition covariance matrix from time t-1 to t.

  • observation_matrix (numpy.ndarray) – Observation matrix to project state.

  • observation_variance (numpy.ndarray) – Observation variances

  • observation_indices (numpy.ndarray) – Used to compress observations, observation_matrix, and observation_variance skipping missing values.

  • observation_count (numpy.ndarray) – Number of observed time series for each timestep determining the number of elements to be read in observation_indices.

  • filtered_state_mean (numpy.ndarray) – Initial state mean

  • filtered_state_covariance (numpy.ndarray) – Initial state covariance

Returns:

  • sigmas (numpy.ndarray) – Weighted squared innovations.

  • detfs (numpy.ndarray) – Log of determinant of innovation variances matrix.

  • sigmacount (int) – Number of elements in sigmas en detfs with calculated values.

  • filtered_state_means (numpy.ndarray) – filtered_state_means[t] = mean state estimate for time t given observations from times [0…t].

  • filtered_state_covariances (numpy.ndarray) – filtered_state_covariances[t] = covariance of state estimate for time t given observations from times [0…t].

  • predicted_state_means (numpy.ndarray) – predicted_state_means[t] = mean state estimate for time t given observations from times [0…t-1].

  • predicted_state_covariances (numpy.ndarray) – predicted_state_covariances[t] = covariance of state estimate for time t given observations from times [0…t-1].

metran.kalmanfilter.seqkalmanfilter_np(observations, transition_matrix, transition_covariance, observation_matrix, observation_variance, observation_indices, observation_count, filtered_state_mean, filtered_state_covariance)[source]

Method to run sequential Kalman filter optimized for use with numpy.

This method is suggested if numba is not installed. It is, however, much slower than seqkalmanfilter combined with numba.

Parameters:

  • observations (numpy.ndarray) – Observations for sequential processing of Kalman filter.

  • transition_matrix (numpy.ndarray) – State transition matrix from time t-1 to t.

  • transition_covariance (numpy.ndarray) – State transition covariance matrix from time t-1 to t.

  • observation_matrix (numpy.ndarray) – Observation matrix to project state.

  • observation_variance (numpy.ndarray) – Observation variances

  • observation_indices (numpy.ndarray) – Used to compress observations, observation_matrix, and observation_variance skipping missing values.

  • observation_count (numpy.ndarray) – Number of observed time series for each timestep determining the number of elements to be read in observation_indices.

  • filtered_state_mean (numpy.ndarray) – Initial state mean

  • filtered_state_covariance (numpy.ndarray) – Initial state covariance

Returns:

  • sigmas (list) – Weighted squared innovations.

  • detfs (list) – Log values of determinant of innovation variances matrix.

  • filtered_state_means (list) – filtered_state_means[t] = mean state estimate for time t given observations from times [0…t].

  • filtered_state_covariances (list) – filtered_state_covariances[t] = covariance of state estimate for time t given observations from times [0…t].

  • predicted_state_means (list) – predicted_state_means[t] = mean state estimate for time t given observations from times [0…t-1].

  • predicted_state_covariances (list) – predicted_state_covariances[t] = covariance of state estimate for time t given observations from times [0…t-1].

Solvers

This module contains the solver that is available for Pastas Metran.

All solvers inherit from the BaseSolver class, which contains methods to obtain the object function value and numerical approximation of the parameter covariance matrix.

To solve a model the following syntax can be used:

>>> mt.solve(solver=ps.LmfitSolve)
class metran.solver.BaseSolver(mt, **kwargs)[source]

All solver instances inherit from the BaseSolver class.

mt
Type:

Metran instance

objfunction(p, callback)[source]

Method to get objective function used by solver.

Parameters:

  • p (type required for callback function) – Parameters to be coverted by callback function into proper type and format.

  • callback (ufunc) – Function that is called after each iteration. The parameters are provided to the func, e.g. “callback(parameters)”.

Returns:

obj – Objective function value.

Return type:

float

class metran.solver.LmfitSolve(mt, **kwargs)[source]

Class for solving the model using the LmFit solver [LM].

Lmfit is basically a wrapper around the scipy solvers, adding some functionality for boundary conditions.

Parameters:

  • mt (Metran instance) –

  • **kwargs (dict, optional) – All keyword arguments will be passed onto minimization method from the solver.

Examples

>>> mt.solve(solver=ps.LmfitSolve)

References

solve(method='lbfgsb', **kwargs)[source]

Method to run solver and optimize parameters.

Parameters:

  • method (str, optional) – Name of the fitting method to use. The default is “lbfgsb”.

  • **kwargs (dict, optional) – All keyword arguments will be passed onto minimization method from the solver.

Returns:

  • success (boolean) – True if optimization routine terminated successfully.

  • params (lmfit.Parameters instance) – Ordered dictionary of Parameter objects.

class metran.solver.ScipySolve(mt, **kwargs)[source]

Solver based on Scipy’s least_squares method [scipy_ref].

This class is the default solver class in the Metran solve method.

Parameters:

  • mt (Metran instance) –

  • **kwargs (dict, optional) – All keyword arguments will be passed onto minimization method from the solver.

Examples

>>> mt.solve(solver=ps.ScipySolve)

References

solve(method='l-bfgs-b', **kwargs)[source]

Method to run solver and optimize parameters.

Parameters:

  • method (str, optional) – Name of the fitting method to use. The default is “l-bfgs-b”.

  • **kwargs (dict, optional) – All keyword arguments will be passed onto minimization method from the solver.

Returns:

  • success (boolean) – True if optimization routine terminated successfully.

  • params (lmfit.Parameters instance) – Ordered dictionary of Parameter objects.

Plots

This module contains the Plot helper class for Metran.

class metran.plots.MetranPlot(mt)[source]

Plots available directly from the Metran Class.

decomposition(name, tmin=None, tmax=None, ax=None, split=False, adjust_height=True, **kwargs)[source]

Plot decomposition into specific and common dynamic components.

Parameters:

  • name (str) – name of oseries

  • tmin (str or pd.Timestamp, optional) – start time, by default None

  • tmax (str or pd.Timestamp, optional) – end time, by default None

  • ax (matplotlib.pyplot.Axis) – axes to plot decomposition on

  • split (bool, optional) – plot specific and common dynamic factors on different axes, only if ax is None

  • adjust_height (bool, optional) – scale y-limits of axes relative to one another, by default True, only used when ax is None and split=True

Returns:

axes – list of axes handles

Return type:

list of matplotlib.pyplot.Axes

decompositions(tmin=None, tmax=None, **kwargs)[source]

Plot all decompositions into specific and common dynamic components.

Parameters:

  • name (str) – name of oseries

  • tmin (str or pd.Timestamp, optional) – start time, by default None

  • tmax (str or pd.Timestamp, optional) – end time, by default None

Returns:

axes – list of axes handles

Return type:

list of matplotlib.pyplot.Axes

scree_plot()[source]

Draw a scree plot of the eigenvalues.

Returns:

ax – plot axis handle

Return type:

matplotlib.pyplot.Axes

simulation(name, alpha=0.05, tmin=None, tmax=None, ax=None)[source]

Plot simulation for single oseries.

Parameters:

  • name (str) – name of the oseries

  • alpha (float, optional) – confidence interval statistic, by default 0.05 (95% confidence interval), if None no confidence interval is shown.

  • tmin (str or pd.Timestamp, optional) – start time, by default None

  • tmax (str or pd.Timestamp, optional) – end time, by default None

  • ax (matplotlib.pyplot.Axis) – axes to plot simulation on, if None (default) create a new figure

Returns:

ax – plot axis handle

Return type:

matplotlib.pyplot.Axes

simulations(alpha=0.05, tmin=None, tmax=None)[source]

Plot simulations for all oseries.

Parameters:

  • name (str) – name of the oseries

  • alpha (float, optional) – confidence interval statistic, by default 0.05 (95% confidence interval), if None no confidence interval is shown.

  • tmin (str or pd.Timestamp, optional) – start time, by default None

  • tmax (str or pd.Timestamp, optional) – end time, by default None

  • ax (matplotlib.pyplot.Axis) – axes to plot simulation on, if None (default) create a new figure

Returns:

axes – list of axes handles

Return type:

list of matplotlib.pyplot.Axes

state_means(tmin=None, tmax=None, adjust_height=True)[source]

Plot all specific and common smoothed state means.

Parameters:

  • tmin (str or pd.Timestamp, optional) – start time, by default None

  • tmax (str or pd.Timestamp, optional) – end time, by default None

  • adjust_height (bool, optional) – scale y-axis of plots relative to one another, by default True

Returns:

axes – list of axes handles

Return type:

list of matplotlib.pyplot.Axes