PySIP API#

Regressor#

class pysip.regressors.Regressor(ss, inputs=None, outputs=None, time_scale='s')[source]#

Bases: object

A regressor use a statespace model and a bayesian filter to predict the states of the system given the exogeneous (or boundary) inputs and the initial conditions.

This base class does not have the ability to estimate the parameters of the statespace model : see the derived classes for that.

Parameters:

  • ss (StateSpace()) – State-space model

  • inputs (str or list of str, optional) – Input column names, by default None. If None, they are inferred from the state-space model.

  • outputs (str or list of str, optional) – Output column names, by default None. If None, they are inferred from the state-space model.

  • time_scale (str) – Time series frequency, e.g. ‘s’: seconds, ‘D’: days, etc.

estimate_output(df, x0=None, P0=None, use_outputs=True)[source]#

Estimate the output filtered distribution

Parameters:

  • df (pandas.DataFrame) – Training data

  • x0 (numpy.ndarray, optional) – Initial state. If not provided, the initial state is taken from the state-space model defaults.

  • P0 (numpy.ndarray, optional) – Initial state covariance. If not provided, the initial state covariance is taken from the state-space model defaults.

  • use_outputs (bool, optional) – Whether to use the data outputs to do the estimation, by default True

Returns:

Dataset containing the estimated outputs and their covariance

Return type:

xr.Dataset

estimate_states(df, x0=None, P0=None, smooth=False, use_outputs=True)[source]#

Estimate the state filtered/smoothed distribution

Parameters:

  • dt (float) – Sampling time

  • u (array_like, shape (n_u, n_steps)) – Input data

  • u1 (array_like, shape (n_u, n_steps)) – Forward finite difference of the input data

  • y (array_like, shape (n_y, n_steps)) – Output data

  • x0 (array_like, shape (n_x, )) – Initial state mean different from ss.x0

  • P0 (array_like, shape (n_x, n_x)) – Initial state deviation different from ss.P0

  • smooth (bool, optional) – Use RTS smoother

Returns:

Dataset containing the estimated states and their covariance

Return type:

xr.Dataset

eval_residuals(df, x0=None, P0=None)[source]#

Compute the standardized residuals

Parameters:

  • df (pandas.DataFrame) – Training data

  • outputs (str or list of str, optional) – Output name(s)

  • inputs (str or list of str, optional) – Input name(s)

  • x0 (numpy.ndarray, optional) – Initial state. If not provided, the initial state is taken from the state-space model defaults.

  • P0 (numpy.ndarray, optional) – Initial state covariance. If not provided, the initial state covariance is taken from the state-space model defaults.

Returns:

Dataset containing the residuals and their standard deviation

Return type:

xr.Dataset

fit(df, options=None, *, init='fixed', hpd=0.95, jac='3-point', method='BFGS', **minimize_options)[source]#

Estimate the parameters of the state-space model.

Parameters:

  • df (pandas.DataFrame) – Training data

  • outputs (str or list of str, optional) – Output name(s)

  • inputs (str or list of str, optional) – Input name(s)

  • options (dict, optional, deprecated) – Options for the minimization method. You should use named arguments instead. Usage of this argument will raise a warning and will be removed in the future.

  • init (str, optional) – Method to initialize the parameters. Options are: - ‘unconstrained’: initialize the parameters in the unconstrained space - ‘prior’: initialize the parameters using the prior distribution - ‘zero’: initialize the parameters to zero - ‘fixed’: initialize the parameters to the fixed values - ‘value’: initialize the parameters to the given values

  • hpd (float, optional) – Highest posterior density interval. Used only when init=’prior’.

  • minimize_options (dict, optional) – Options for the minimization method. See scipy.optimize.minimize for details. Compared to the original scipy.optimize.minimize function, the following options are set by default: - method=’BFGS’ - jac=’3-point’ - disp=True - gtol=1e-4

Return type:

Union[DataFrame, dict]

Returns:

  • pandas.DataFrame – Dataframe with the estimated parameters, their standard deviation, the p-value of the t-test and penalty values.

  • pandas.DataFrame – Dataframe with the correlation matrix of the estimated parameters.

  • dict – Results object from the minimization method. See scipy.optimize.minimize for details.

log_likelihood(df)[source]#

Evaluate the log-likelihood of the model.

Parameters:

  • df (pandas.DataFrame) – Data.

  • outputs (str or list of str, optional) – Outputs name(s). If None, all outputs are used.

  • inputs (str or list of str, optional) – Inputs name(s). If None, all inputs are used.

  • pointwise (bool, optional) – Evaluate the log-likelihood pointwise.

Returns:

Negative log-likelihood or predictive density evaluated point-wise.

Return type:

float or numpy.ndarray

log_posterior(df)[source]#

Evaluate the negative log-posterior, defined as

\[-\log p(\theta | y) = -\log p(y | \theta) - \log p(\theta) + \log\]

with \(y\) the data, \(\theta\) the parameters, \(p(y | \theta)\) the likelihood, \(p(\theta)\) the prior and \(\log p(\theta | y)\) the log-posterior.

Parameters:

df (pandas.DataFrame) – Training data

Returns:

log_posterior – The negative log-posterior

Return type:

float

posterior_predictive(df, **kwargs)[source]#

Sample from the posterior predictive distribution

Parameters:

df (pandas.DataFrame) – Dataframe containing the inputs and outputs

Return type:

xarray.Dataset

Raises:

RuntimeError – If the model has not been sampled yet

predict(df, tnew=None, x0=None, P0=None, smooth=False, use_outputs=True)[source]#

State-space model output prediction

Parameters:

  • df (pandas.DataFrame) – Training data

  • tnew (numpy.ndarray or pandas.Series, optional) – New time instants

  • x0 (numpy.ndarray, optional) – Initial state. If not provided, the initial state is taken from the state-space model.

  • P0 (numpy.ndarray, optional) – Initial state covariance. If not provided, the initial state covariance is taken from the state-space model.

  • smooth (bool, optional) – If True, the Kalman smoother is used instead of the Kalman filter

  • use_outputs (bool, optional) – If True, the outputs are used to do the estimation. Default is False.

Returns:

Dataset containing the predicted outputs and their covariance

Return type:

xr.Dataset

prepare_data(df, with_outputs=True)[source]#

Prepare data for training

Parameters:

  • df (pd.DataFrame) – Dataframe containing the data

  • with_outputs (bool, optional) – Whether to return the outputs, by default True

Return type:

Tuple[DataFrame, ...]

Returns:

  • DataFrame – time steps

  • DataFrame – input data

  • DataFrame – derivative of input data

  • DataFrame – output data (filled with NaNs if with_outputs=False)

prior_predictive(df, samples=1000, **kwargs)[source]#

Sample from the prior predictive distribution

Parameters:

  • df (pandas.DataFrame) – Dataframe containing the inputs and outputs

  • samples (int, optional) – Number of samples, by default 1000

Returns:

Dataset containing the simulated outputs

Return type:

xarray.Dataset

sample(df, draws=1000, tune=500, chains=4, **kwargs)[source]#

Sample from the posterior distribution

Parameters:

  • df (pandas.DataFrame) – Dataframe containing the inputs and outputs

  • draws (int, optional) – Number of samples, by default 1000

  • tune (int, optional) – Number of tuning samples, by default 500

  • chains (int, optional) – Number of chains, by default 4

  • cores (int, optional) – Number of cores, by default cpu_count()

Returns:

Inference data containing the posterior samples

Return type:

arviz.InferenceData

Notes

The number of cores is set to the minimum between the number of cores and the number of chains.

The sample method directly use the pymc3.sample method. See the PyMC3 documentation for more details.

simulate(df)[source]#

Stochastic simulation of the state-space model

Parameters:

  • df (pandas.DataFrame) – Dataframe containing the inputs and outputs

  • inputs (str or list of str, optional) – Input column names, by default None. If None, the regressor’s inputs attribute is used.

  • time_scale (str, optional) – Time series frequency, e.g. ‘s’: seconds, ‘D’: days, etc., by default None. If None, the regressor’s time_scale attribute is used.

Returns:

Dataset containing the simulated outputs and states

Return type:

xarray.Dataset

Statespace Estimators#

class pysip.statespace_estimator.KalmanQR(ss)[source]#

Bases: object

Bayesian Filter (Kalman Square Root filter)

Parameters:

ss (StateSpace) – State space model.

Notes

All the method except _proxy_params are jitted by numba, if available. Otherwise, the pure (but slower) python / numpy implementation will be used.

estimate_output(dt, u, dtu, y, x0=None, P0=None)[source]#

Estimate the output using the state space model and the Kalman filter.

Parameters:

  • dt (pd.Series) – Time steps.

  • u (pd.DataFrame) – Output (or exogeneous) vector.

  • dtu (pd.DataFrame) – Time derivative of the output vector.

  • y (pd.DataFrame) – Measurement (or observation) vector.

  • x0 (np.ndarray, optional) – Initial state vector, by default None. If None, the initial state vector provided by the statespace model is used.

  • P0 (np.ndarray, optional) – Initial covariance matrix, by default None. If None, the initial covariance matrix provided by the statespace model is used.

Returns:

Estimated output in the form of a namedtuple with the following fields:

  • x: np.ndarray[n_timesteps, nx, 1]

    State vector.

  • P: np.ndarray[n_timesteps, nx, nx]

    Covariance matrix.

  • y: np.ndarray[n_timesteps, ny, 1]

    Output vector.

  • y_std: np.ndarray[n_timesteps, ny, 1]

    Standard deviation of the output vector.

Return type:

OutputEstimate

filtering(dt, u, dtu, y, x0=None, P0=None)[source]#

Filter the data using the state space model and the Kalman filter.

Parameters:

  • dt (pd.Series) – Time steps.

  • u (pd.DataFrame) – Output (or exogeneous) vector.

  • dtu (pd.DataFrame) – Time derivative of the output vector.

  • y (pd.DataFrame) – Measurement (or observation) vector.

  • x0 (np.ndarray, optional) – Initial state vector, by default None. If None, the initial state vector provided by the statespace model is used.

  • P0 (np.ndarray, optional) – Initial covariance matrix, by default None. If None, the initial covariance matrix provided by the statespace model is used.

Returns:

Result of the filtering in the form of a namedtuple with the following fields:

  • x_update: np.ndarray[n_timesteps, nx, 1]

    Updated state vector.

  • P_update: np.ndarray[n_timesteps, nx, nx]

    Updated covariance matrix.

  • x_predict: np.ndarray[n_timesteps, nx, 1]

    Predicted state vector.

  • P_predict: np.ndarray[n_timesteps, nx, nx]

    Predicted covariance matrix.

  • k: np.ndarray[n_timesteps, ny, 1]

    Kalman gain.

  • S: np.ndarray[n_timesteps, ny, ny]

    Innovation covariance matrix.

Return type:

FilteringResults

log_likelihood(dt, u, dtu, y)[source]#

Compute the log-likelihood of the model.

Parameters:

  • dt (pd.Series) – Time steps.

  • u (pd.DataFrame) – Output (or exogeneous) vector.

  • dtu (pd.DataFrame) – Time derivative of the output vector.

  • y (pd.DataFrame) – Measurement (or observation) vector.

Returns:

Log-likelihood of the model.

Return type:

float

predict(x, P, u, dtu, dt)[source]#

Predict the state and covariance of the next time step.

Parameters:

  • x (np.ndarray) – State (or endogeneous) vector.

  • P (np.ndarray) – Covariance matrix.

  • u (np.ndarray) – Output (or exogeneous) vector.

  • dtu (np.ndarray) – Time derivative of the output vector.

  • dt (float) – Time step.

Return type:

tuple[ndarray, ndarray]

Returns:

  • np.ndarray – Predicted state vector.

  • np.ndarray – Predicted covariance matrix.

simulate(dt, u, dtu, x0=None, P0=None)[source]#

Simulate the data using the state space model. The Kalman filter is not involved in this process.

The formula reads:

\[y = C x + D u + R \epsilon \ x = A x + B_0 u + B_1 \dot{u} + Q \eta\]

where \(\epsilon\) and \(\eta\) are independent white noise with covariance matrices \(R\) and \(Q\) respectively.

Parameters:

  • dt (pd.Series) – Time steps.

  • u (pd.DataFrame) – Output (or exogeneous) vector.

  • dtu (pd.DataFrame) – Time derivative of the output vector.

  • x0 (np.ndarray, optional) – Initial state vector, by default None. If None, the initial state vector provided by the statespace model is used.

  • P0 (np.ndarray, optional) – Initial covariance matrix, by default None. If None, the initial covariance matrix provided by the statespace model is used.

Returns:

Simulated data in the form of a namedtuple with the following fields:

  • x: np.ndarray[n_timesteps, nx, 1]

    State vector.

  • y: np.ndarray[n_timesteps, ny, 1]

    Output vector.

Return type:

SimulationResults

smoothing(dt, u, dtu, y, x0=None, P0=None)[source]#

Smooth the data using the state space model and the Kalman filter.

Parameters:

  • dt (pd.Series) – Time steps.

  • u (pd.DataFrame) – Output (or exogeneous) vector.

  • dtu (pd.DataFrame) – Time derivative of the output vector.

  • y (pd.DataFrame) – Measurement (or observation) vector.

  • x0 (np.ndarray, optional) – Initial state vector, by default None. If None, the initial state vector provided by the statespace model is used.

  • P0 (np.ndarray, optional) – Initial covariance matrix, by default None. If None, the initial covariance matrix provided by the statespace model is used.

Returns:

Result of the smoothing in the form of a namedtuple with the following fields:

  • x_update: np.ndarray[n_timesteps, nx, 1]

    Updated state vector.

  • P_update: np.ndarray[n_timesteps, nx, nx]

    Updated covariance matrix.

  • x_predict: np.ndarray[n_timesteps, nx, 1]

    Predicted state vector.

  • P_predict: np.ndarray[n_timesteps, nx, nx]

    Predicted covariance matrix.

  • x_smooth: np.ndarray[n_timesteps, nx, 1]

    Smoothed state vector.

  • P_smooth: np.ndarray[n_timesteps, nx, nx]

    Smoothed covariance matrix.

  • k: np.ndarray[n_timesteps, ny, 1]

    Kalman gain.

  • S: np.ndarray[n_timesteps, ny, ny]

    Innovation covariance matrix.

Return type:

SmoothingResults

update(x, P, u, y)[source]#

Update the state and covariance of the current time step.

Note that this function will not update the statespace model to ensure the consistency with the model parameters : to do so, use the filter.ss.update method.

Parameters:

  • x (np.ndarray) – State (or endogeneous) vector.

  • P (np.ndarray) – Covariance matrix.

  • u (np.ndarray) – Output (or exogeneous) vector.

  • y (np.ndarray) – Measurement (or observation) vector.

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

Returns:

  • x (np.ndarray) – State (or endogeneous) vector.

  • P (np.ndarray) – Covariance matrix.

Parameters and Priors#

Parameters#

class pysip.params.Parameter(name, value=None, loc=0.0, scale=1.0, bounds=(None, None), transform='auto', prior=None)[source]#

Bases: object

A Parameter has a value in the constrained space θ and in the unconstrained space η. See the documentation of the class for more details on the different transformations.

Parameters:

  • name (str) – Parameter name

  • value (float) – Parameter value

  • loc (float) – Location value

  • scale (float) – Scaling value

  • transform (str | ParameterTransform) – Bijections transform θ -> η and untransform η -> θ

  • bounds (tuple) – Parameters bounds

  • prior (rv_continuous) – Prior distribution, using a scipy.stats distribution object.

theta#

Parameter value in the constrained space θ

Type:

float

theta_sd#

Parameter value in the standardized constrained space θ_sd

Type:

float

eta#

Parameter value in the unconstrained space η

Type:

float

eta_sd#

Parameter value in the standardized unconstrained space η_sd

Type:

float

free#

False if the parameter is fixed

Type:

bool

get_grad_penalty()[source]#

Penalty function

Return type:

float

get_inv_transform_jacobian()[source]#

Get the jacobian of θsd = f⁻¹(η)

Return type:

float

get_inv_transformed()[source]#

Do inverse transformation θsd = f^{-1}(η)

get_penalty()[source]#

Penalty function

Return type:

float

get_transform_jacobian()[source]#

Get the jacobian of η = f(θsd)

get_transformed()[source]#

Do inverse transformation θsd = f^{-1}(η)

property theta: float#

Returns constrained parameter value θ

class pysip.params.Parameters(parameters, name='')[source]#

Bases: object

Factory of Parameter instances

Parameters:

  • parameters (list) –

    There is three options for instantiating Parameters

    • parameters is a list of strings corresponding to the parameters names. In this case all the parameters have the default settings

    • parameters is a list of dictionaries, where the arguments of Parameter can be modified as key-value pairs

    • parameters is a list of Parameter instances

  • name (str, optional) – Name of this specific instance, by default “”

free#

False if the parameter is fixed

Type:

List[bool]

names#

List of the parameters names

Type:

List[str]

names_free#

List of the parameters names, only for free parameters

Type:

List[str]

scales#

List of the parameters scales

Type:

List[float]

n_par#

Number of free parameters

Type:

int

parameters_free#

List of the free parameters

Type:

List[Parameter]

theta#

Parameter value in the constrained space θ

Type:

List[float]

theta_free#

Parameter value in the constrained space θ, only for free parameters

Type:

List[float]

theta_sd#

Parameter value in the standardized constrained space θ_sd, only for free parameters

Type:

List[float]

theta_jacobian#

Gradient of the transformation from θ to η, only for free parameters

Type:

List[float]

theta_log_jacobian#

Sum of the log of the absolute values of the gradent of the transformation from θ to η for each parameter

Type:

float

eta#

Parameter value in the unconstrained space η

Type:

List[float]

eta_free#

Parameter values in the unconstrained space η, only for free parameters

Type:

List[float]

eta_jacobian#

Jacobian of the transformation from θ to η, only for free parameters

Type:

List[float]

penalty#

Sum of the penalty term for the parameters

Type:

float

prior#

Sum of the logarithm of the prior distribution, only for free parameters with a defined prior.

Type:

float

property d_penalty: List#

Partial derivative of the penalty function

Parameters:

scaling – Scaling coefficient of the penalty function

init_parameters(n_init=1, method='unconstrained', hpd=0.95)[source]#

Random initialization of the parameters

Parameters:

  • n_init (int, default 1) – Number of random initialization

  • method (str, default 'unconstrained') –

    • unconstrained: Uniform draw between [-1, 1] in the uncsontrained

    space - prior: Uniform draw from the prior distribution - zero: Set the unconstrained parameters to 0 - fixed: The current parameter values are used - value: Uniform draw between the parameter value +/- 25%

  • hpd (bool, default False) – Highest Prior Density to draw sample from (True for unimodal distribution)

Returns:

eta0 – Array of unconstrained parameters, where n_par is the number of free parameters and n_init the number of random initialization

Return type:

ndarray of shape (n_par, n_init)

property parameters#

Returns the list of Parameter instance

prior_init(hpd=None)[source]#

Draw a random sample from the prior distribution for each parameter that have a defined prior.

Parameters:

hpd (float) – Highest posterior density interval.

set_parameter(*args, **kwargs)[source]#

Change settings of Parameters after instantiation

p_alpha = Parameters([‘a’, ‘b’, ‘c’], name=’alpha’) p_alpha.set_parameter(‘a’, value=1, transform=’log’)

property theta: ndarray#

Get the constrained parameter values θ

Transforms#

Parameter transforms

This module contains the different transforms that can be applied to a parameter. The transforms are used to transform a parameter value θ to the unconstrained space η and vice versa. The transforms are used to ensure that the parameters are constrained to a certain range and that the optimization algorithm can find the optimal parameters.

The transforms are defined in the class ParameterTransform. The class has the following abstract attributes / methods:

  • name: Name of the transform

  • transform: Transform a parameter value θ to the unconstrained space η

  • untransform: Transform a parameter value η to the constrained space θ

  • grad_transform: Gradient of the transform function

  • grad_untransform: Gradient of the untransform function

The transforms are registered in the Transforms namespace. The namespace is used to get the transform class from the name of the transform.

The following transforms are available:

  • None: No transform

  • Fixed: Fixed parameter

  • Log: Log transform

  • Lower: Lower bound

  • Upper: Upper bound

  • Logit: Logit transform

An auto transform is also available. The auto transform will select the best transform based on the bounds of the parameter.

class pysip.params.transforms.FixedTransform(bounds)[source]#

Bases: NoneTransform

Fixed transform, i.e. θ = η, but the parameter is not considered as a random variable.

class pysip.params.transforms.LogTransform(bounds)[source]#

Bases: ParameterTransform

Log transform, i.e. θ = exp(η)

grad_penalty(θ)[source]#

Gradient of the penalty function for the parameter value θ

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

grad_penalty – Gradient of the penalty function for the parameter value θ

Return type:

float

grad_transform(θ)[source]#

Gradient of the transform function

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

grad – Gradient of the transform function

Return type:

float

grad_untransform(η)[source]#

Gradient of the untransform function

Parameters:

η (float) – Parameter value in the unconstrained space η

Returns:

grad – Gradient of the untransform function

Return type:

float

penalty(θ)[source]#

Penalty for the parameter value θ

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

penalty – Penalty for the parameter value θ

Return type:

float

transform(θ)[source]#

Transform a parameter value θ to the unconstrained space η

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

η – Parameter value in the unconstrained space η

Return type:

float

untransform(η)[source]#

Transform a parameter value η to the constrained space θ

Parameters:

η (float) – Parameter value in the unconstrained space η

Returns:

θ – Parameter value in the constrained space θ

Return type:

float

class pysip.params.transforms.LogitTransform(bounds)[source]#

Bases: ParameterTransform

Logit transform, i.e. θ = a + (b - a) / (1 + exp(-η)), where a and b are the lower and upper bounds, respectively .

grad_penalty(θ)[source]#

Gradient of the penalty function for the parameter value θ

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

grad_penalty – Gradient of the penalty function for the parameter value θ

Return type:

float

grad_transform(θ)[source]#

Gradient of the transform function

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

grad – Gradient of the transform function

Return type:

float

grad_untransform(η)[source]#

Gradient of the untransform function

Parameters:

η (float) – Parameter value in the unconstrained space η

Returns:

grad – Gradient of the untransform function

Return type:

float

in_bounds(x)[source]#

Check if the parameter value is in the bounds of the transform

Parameters:

x (float) – Parameter value in the constrained space θ

Returns:

in_bounds – True if the parameter value is in the bounds of the transform

Return type:

bool

penalty(θ)[source]#

Penalty for the parameter value θ

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

penalty – Penalty for the parameter value θ

Return type:

float

transform(θ)[source]#

Transform a parameter value θ to the unconstrained space η

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

η – Parameter value in the unconstrained space η

Return type:

float

untransform(η)[source]#

Transform a parameter value η to the constrained space θ

Parameters:

η (float) – Parameter value in the unconstrained space η

Returns:

θ – Parameter value in the constrained space θ

Return type:

float

class pysip.params.transforms.LowerTransform(bounds)[source]#

Bases: ParameterTransform

Lower bound transform, i.e. θ = exp(η) + a, where a is the lower bound

grad_penalty(θ)[source]#

Gradient of the penalty function for the parameter value θ

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

grad_penalty – Gradient of the penalty function for the parameter value θ

Return type:

float

grad_transform(θ)[source]#

Gradient of the transform function

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

grad – Gradient of the transform function

Return type:

float

grad_untransform(η)[source]#

Gradient of the untransform function

Parameters:

η (float) – Parameter value in the unconstrained space η

Returns:

grad – Gradient of the untransform function

Return type:

float

in_bounds(x)[source]#

Check if the parameter value is in the bounds of the transform

Parameters:

x (float) – Parameter value in the constrained space θ

Returns:

in_bounds – True if the parameter value is in the bounds of the transform

Return type:

bool

penalty(θ)[source]#

Penalty for the parameter value θ

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

penalty – Penalty for the parameter value θ

Return type:

float

transform(θ)[source]#

Transform a parameter value θ to the unconstrained space η

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

η – Parameter value in the unconstrained space η

Return type:

float

untransform(η)[source]#

Transform a parameter value η to the constrained space θ

Parameters:

η (float) – Parameter value in the unconstrained space η

Returns:

θ – Parameter value in the constrained space θ

Return type:

float

class pysip.params.transforms.NoneTransform(bounds)[source]#

Bases: ParameterTransform

No transform, i.e. θ = η

grad_penalty(θ)[source]#

Gradient of the penalty function for the parameter value θ

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

grad_penalty – Gradient of the penalty function for the parameter value θ

Return type:

float

grad_transform(θ)[source]#

Gradient of the transform function

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

grad – Gradient of the transform function

Return type:

float

grad_untransform(η)[source]#

Gradient of the untransform function

Parameters:

η (float) – Parameter value in the unconstrained space η

Returns:

grad – Gradient of the untransform function

Return type:

float

penalty(θ)[source]#

Penalty for the parameter value θ

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

penalty – Penalty for the parameter value θ

Return type:

float

transform(θ)[source]#

Transform a parameter value θ to the unconstrained space η

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

η – Parameter value in the unconstrained space η

Return type:

float

untransform(η)[source]#

Transform a parameter value η to the constrained space θ

Parameters:

η (float) – Parameter value in the unconstrained space η

Returns:

θ – Parameter value in the constrained space θ

Return type:

float

class pysip.params.transforms.UpperTransform(bounds)[source]#

Bases: ParameterTransform

Upper bound transform, i.e. θ = a - exp(η), where a is the upper bound

grad_penalty(θ)[source]#

Gradient of the penalty function for the parameter value θ

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

grad_penalty – Gradient of the penalty function for the parameter value θ

Return type:

float

grad_transform(θ)[source]#

Gradient of the transform function

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

grad – Gradient of the transform function

Return type:

float

grad_untransform(η)[source]#

Gradient of the untransform function

Parameters:

η (float) – Parameter value in the unconstrained space η

Returns:

grad – Gradient of the untransform function

Return type:

float

in_bounds(x)[source]#

Check if the parameter value is in the bounds of the transform

Parameters:

x (float) – Parameter value in the constrained space θ

Returns:

in_bounds – True if the parameter value is in the bounds of the transform

Return type:

bool

penalty(θ)[source]#

Penalty for the parameter value θ

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

penalty – Penalty for the parameter value θ

Return type:

float

transform(θ)[source]#

Transform a parameter value θ to the unconstrained space η

Parameters:

θ (float) – Parameter value in the constrained space θ

Returns:

η – Parameter value in the unconstrained space η

Return type:

float

untransform(η)[source]#

Transform a parameter value η to the constrained space θ

Parameters:

η (float) – Parameter value in the unconstrained space η

Returns:

θ – Parameter value in the constrained space θ

Return type:

float

pysip.params.transforms.auto_transform(bounds)[source]#

Automatically select a transform based on the bounds

Parameters:

bounds (tuple) – Lower and upper bounds of the parameter. Both bounds can be None.

Returns:

transform – Transform that is automatically selected based on the bounds

Return type:

ParameterTransform

Priors#

class pysip.params.prior.BasePrior[source]#

Bases: object

Prior class template

This contains both the scipy distribution (to compute standard numerical operations) as well as the pymc distribution factory (to be used with the bayesian inference engine).

logpdf(x)[source]#

Evaluate the logarithm of the probability density function

Parameters:

x (float) – Quantiles

Return type:

float

pdf(x)[source]#

Evaluate the probability density function

Parameters:

x (float) – Quantiles

Return type:

float

random(n=1, hpd=None)[source]#

Draw random samples from the prior distribution

Parameters:

  • n – Number of draws

  • hpd – Highest Prior Density for drawing sample from (true for unimodal distribution)

Return type:

ndarray

class pysip.params.prior.Beta(alpha=3.0, beta=3.0)[source]#

Bases: BasePrior

Beta prior distribution

Parameters:

  • alpha (float) – Shape parameter of the beta distribution

  • beta (float) – Shape parameter of the beta distribution

class pysip.params.prior.Gamma(alpha=3.0, beta=1.0)[source]#

Bases: BasePrior

Gamma prior distribution

Parameters:

  • alpha (float) – Shape parameter of the gamma distribution

  • beta (float) – Rate parameter of the gamma distribution

class pysip.params.prior.InverseGamma(alpha=3.0, beta=1.0)[source]#

Bases: BasePrior

Inverse Gamma prior distribution

Parameters:

  • alpha (float) – Shape parameter of the inverse gamma distribution

  • beta (float) – Scale parameter of the inverse gamma distribution

class pysip.params.prior.LogNormal(mu=0.0, sigma=1.0)[source]#

Bases: BasePrior

Log Normal prior distribution

Parameters:

  • mu (float) – Mean of the log normal distribution

  • sigma (float) – Standard deviation of the log normal distribution

class pysip.params.prior.Normal(mu=0.0, sigma=1.0)[source]#

Bases: BasePrior

Normal prior distribution

Parameters:

  • mu (float) – Mean of the normal distribution

  • sigma (float) – Standard deviation of the normal distribution

class pysip.params.prior.Uniform(lower=0.0, upper=1.0)[source]#

Bases: BasePrior

Uniform prior distribution

Parameters:

  • lower (float) – Lower bound of the uniform distribution

  • upper (float) – Upper bound of the uniform distribution

Statespaces#

class pysip.statespace.StateSpace(parameters=None, hold_order=0, method='mfd', name='')[source]#

Bases: object

Linear Gaussian Continuous-Time State-Space Model

Model Variables#

  • Inputs

  • Outputs

  • States

discretization(dt)[source]#

Discretization of LTI state-space model. Should be overloaded by subclasses.

Parameters:

dt (float) – Sampling time

Returns:

a 4-elements tuple containing - A: Discrete state matrix - B0: Discrete input matrix (zero order hold) - B1: Discrete input matrix (first order hold) - Q: Upper Cholesky factor of the process noise covariance matrix

Return type:

Tuple[np.ndarray, …]

get_discrete_ssm(dt)[source]#

Return the updated discrete state-space model

Parameters:

dt (float) – Sampling time

Returns:

Discrete state-space model, a 4-elements namedtuple containing - A: Discrete state matrix - B0: Discrete input matrix (zero order hold) - B1: Discrete input matrix (first order hold) - Q: Upper Cholesky factor of the process noise covariance matrix

Return type:

DiscreteStates

prepare_data(df, inputs=None, outputs=None, time_scale='s')[source]#

Prepare data for training

Parameters:

  • df (pd.DataFrame) – Dataframe containing the data

  • inputs (Optional[Sequence[str]], optional) – List of input variables, by default None. If None, the inputs defined in the model are used.

  • outputs (Optional[Sequence[str] or False], optional) – List of output variables, by default None. If None, the outputs defined in the model are used. If False, no output is returned.

Returns:

  • DataFrame – time steps

  • DataFrame – input data

  • DataFrame – derivative of input data

  • DataFrame – output data (only if outputs is not False)

set_constant_continuous_ssm()[source]#

Set constant values in state-space model

update()[source]#

Update the state-space model with the constrained parameters

update_continuous_ssm()[source]#

Update the state-space model with the constrained parameters

class pysip.statespace.RCModel(parameters=None, hold_order=0, method='mfd', name='', latent_forces='')[source]#

Bases: StateSpace

Dynamic thermal model

Model Variables#

  • Inputs

  • Outputs

  • States

discretization(dt)[source]#

Discretization of RC model

Parameters:

dt (float) – Sampling time

Returns:

a 4-elements tuple containing - A: Discrete state matrix - B0: Discrete input matrix (zero order hold) - B1: Discrete input matrix (first order hold) - Q: Upper Cholesky factor of the process noise covariance matrix

Return type:

Tuple[np.ndarray, …]

class pysip.statespace.GPModel(parameters=None, hold_order=0, method='mfd', name='')[source]#

Bases: StateSpace

Gaussian Process

Model Variables#

  • Inputs

  • Outputs

  • States

discretization(dt)[source]#

Discretization of the temporal Gaussian Process

Parameters:

dt (float) – Sampling time

Returns:

a 4-elements tuple containing - A: Discrete state matrix - B0: Discrete input matrix (zero order hold) - B1: Discrete input matrix (first order hold) - Q: Upper Cholesky factor of the process noise covariance matrix

Return type:

Tuple[np.ndarray, …]