la

LinearAnalysis object, which is the base class for other pyemu analysis objects (Schur, ErrVar, MonteCarlo, and EnsembleSmoother). This class is usually not used directly.

`LinearAnalysis`

Bases: object

The base/parent class for linear analysis.

Parameters:

Name	Type	Description	Default
`jco`	`varies`	something that can be cast or loaded into a `pyemu.Jco`. Can be a str for a filename or `pyemu.Matrix`/`pyemu.Jco` object.	`None`
`pst`	`varies`	something that can be cast into a `pyemu.Pst`. Can be an `str` for a filename or an existing `pyemu.Pst`. If `None`, a pst filename is sought with the same base name as the jco argument (if passed)	`None`
`parcov`	`varies`	prior parameter covariance matrix. If `str`, a filename is assumed and the prior parameter covariance matrix is loaded from a file using the file extension (".jcb"/".jco" for binary, ".cov"/".mat" for PEST-style ASCII matrix, or ".unc" for uncertainty files). If `None`, the prior parameter covariance matrix is constructed from the parameter bounds in `LinearAnalysis.pst`. Can also be a `pyemu.Cov` instance	`None`
`obscov`	`varies`	observation noise covariance matrix. If `str`, a filename is assumed and the noise covariance matrix is loaded from a file using the file extension (".jcb"/".jco" for binary, ".cov"/".mat" for PEST-style ASCII matrix, or ".unc" for uncertainty files). If `None`, the noise covariance matrix is constructed from the observation weights in `LinearAnalysis.pst`. Can also be a `pyemu.Cov` instance	`None`
`forecasts`	`varies`	forecast sensitivity vectors. If `str`, first an observation name is assumed (a row in `LinearAnalysis.jco`). If that is not found, a filename is assumed and predictions are loaded from a file using the file extension. If [`str`], a list of observation names is assumed. Can also be a `pyemu.Matrix` instance, a `numpy.ndarray` or a collection of `pyemu.Matrix` or `numpy.ndarray`.	`None`
`ref_var`	`float`	reference variance. Default is 1.0	`1.0`
`verbose`	`bool`	controls screen output. If `str`, a filename is assumed and and log file is written.	`False`
`sigma_range`	`float`	defines range of upper bound - lower bound in terms of standard deviation (sigma). For example, if sigma_range = 4, the bounds represent 4 * sigma. Default is 4.0, representing approximately 95% confidence of implied normal distribution. This arg is only used if constructing parcov from parameter bounds.	`4.0`
`scale_offset`	`bool`	flag to apply parameter scale and offset to parameter bounds when calculating prior parameter covariance matrix from bounds. This arg is onlyused if constructing parcov from parameter bounds.Default is True.	`True`

Note:

Can be used directly, but for prior uncertainty analyses only.

The derived types (`pyemu.Schur`, `pyemu.ErrVar`) are for different
forms of FOMS-based posterior uncertainty analyses.

This class tries hard to not load items until they are needed; all arguments are optional.

The class makes heavy use of property decorator to encapsulated private attributes

Example::

#assumes "my.pst" exists
la = pyemu.LinearAnalysis(jco="my.jco",forecasts=["fore1","fore2"])
print(la.prior_forecast)

`adj_par_names` `property`

adjustable parameter names

Returns:

Type	Description
	['str`]: list of adjustable parameter names

Note

if LinearAnalysis.pst is None, returns LinearAnalysis.jco.col_names

`fehalf` `property`

Karhunen-Loeve scaling matrix attribute.

Returns:

Type	Description
	`pyemu.Matrix`: the Karhunen-Loeve scaling matrix based on the prior
	parameter covariance matrix

`forecast_names` `property`

get the forecast (aka prediction) names

Returns:

Type	Description
[`str`]	list of forecast names

`forecasts` `property`

the forecast sentivity vectors attribute

Returns:

Type	Description
	`pyemu.Matrix`: a matrix of forecast (prediction) sensitivity vectors (column wise)

`forecasts_iter` `property`

forecast (e.g. prediction) sensitivity vectors iterator

Returns:

Type	Description
	`iterator`: iterator on forecasts (e.g. predictions) sensitivity vectors (matrix)

Note

This is used for processing huge numbers of predictions

This is a synonym for LinearAnalysis.predictions_iter()

`jco` `property`

the jacobian matrix attribute

Returns:

Type	Description
	`pyemu.Jco`: the jacobian matrix attribute

`mle_covariance` `property`

maximum likelihood parameter covariance matrix.

Returns:

Type	Description
	`pyemu.Matrix`: maximum likelihood parameter covariance matrix

`mle_parameter_estimate` `property`

maximum likelihood parameter estimate.

Returns:

Type	Description
	`pandas.Series`: the maximum likelihood parameter estimates

`nnz_obs_names` `property`

non-zero-weighted observation names

Returns:

Type	Description
	['str`]: list of non-zero-weighted observation names

Note

if LinearAnalysis.pst is None, returns LinearAnalysis.jco.row_names

`obscov` `property`

get the observation noise covariance matrix attribute

Returns:

Type	Description
	`pyemu.Cov`: a reference to the `LinearAnalysis.obscov` attribute

`parcov` `property`

get the prior parameter covariance matrix attribute

Returns:

Type	Description
	`pyemu.Cov`: a reference to the `LinearAnalysis.parcov` attribute

`predictions` `property`

the prediction (aka forecast) sentivity vectors attribute

Returns:

Type	Description
	`pyemu.Matrix`: a matrix of prediction sensitivity vectors (column wise)

`predictions_iter` `property`

prediction sensitivity vectors iterator

Returns:

Type	Description
	`iterator`: iterator on prediction sensitivity vectors (matrix)

Note

this is used for processing huge numbers of predictions

`prior_forecast` `property`

prior forecast (e.g. prediction) variances

Returns:

Type	Description
	`dict`: a dictionary of forecast name, prior variance pairs

`prior_parameter` `property`

prior parameter covariance matrix

Returns:

Type	Description
	`pyemu.Cov`: prior parameter covariance matrix

`prior_prediction` `property`

prior prediction (e.g. forecast) variances

Returns:

Type	Description
	`dict`: a dictionary of prediction name, prior variance pairs

`pst` `property`

the pst attribute

Returns:

Type	Description
	`pyemu.Pst`: the pst attribute

`qhalf` `property`

square root of the cofactor matrix attribute. Create the attribute if it has not yet been created

Returns:

Type	Description
	`pyemu.Matrix`: square root of the cofactor matrix

`qhalfx` `property`

half normal matrix attribute.

Returns:

Type	Description
	`pyemu.Matrix`: half normal matrix attribute

`xtqx` `property`

normal matrix attribute.

Returns:

Type	Description
	`pyemu.Matrix`: normal matrix attribute

`__fromfile(filename, astype=None)`

a private method to deduce and load a filename into a matrix object. Uses extension: 'jco' or 'jcb': binary, 'mat','vec' or 'cov': ASCII, 'unc': pest uncertainty file.

`__load_jco()`

private method to set the jco attribute from a file or a matrix object

`__load_obscov()`

private method to set the obscov attribute from: a pest control file (observation weights) a pst object a matrix object an uncert file an ascii matrix file

`__load_parcov()`

private method to set the parcov attribute from: a pest control file (parameter bounds) a pst object a matrix object an uncert file an ascii matrix file

`__load_predictions()`

private method set the predictions attribute from

mixed list of row names, matrix files and ndarrays a single row name an ascii file

can be none if only interested in parameters.

`__load_pst()`

private method set the pst attribute

`adjust_obscov_resfile(resfile=None)`

reset the elements of obscov by scaling the implied weights based on the phi components in res_file so that the total phi is equal to the number of non-zero weights.

Parameters:

Name	Type	Description	Default
`resfile`	`str`	residual file to use. If None, residual file with case name is sought. default is None	`None`

Note

calls pyemu.Pst.adjust_weights_resfile()

`apply_karhunen_loeve_scaling()`

apply karhuene-loeve scaling to the jacobian matrix.

Note:

This scaling is not necessary for analyses using Schur's
complement, but can be very important for error variance
analyses.  This operation effectively transfers prior knowledge
specified in the parcov to the jacobian and reset parcov to the
identity matrix.

`clean()`

drop regularization and prior information observation from the jco

`drop_prior_information()`

drop the prior information from the jco and pst attributes

`get(par_names=None, obs_names=None, astype=None)`

method to get a new LinearAnalysis class using a subset of parameters and/or observations

Parameters:

Name	Type	Description	Default
`par_names`	[`'str`]	par names for new object	`None`
`obs_names`	[`'str`]	obs names for new object	`None`
`astype`	`pyemu.Schur` or `pyemu.ErrVar`	type to cast the new object. If None, return type is same as self	`None`

Returns:

Type	Description
	`LinearAnalysis`: new instance

`get_cso_dataframe()`

get a dataframe of composite observation sensitivity, as returned by PEST in the seo file.

Returns:

Type	Description
	`pandas.DataFrame`: dataframe of observation names and composite observation
	sensitivity

Note

That this formulation deviates slightly from the PEST documentation in that the values are divided by (npar-1) rather than by (npar).

The equation is cso_j = ((Q^1/2JJ^T*Q^1/2)^1/2)_jj/(NPAR-1)

`get_obs_competition_dataframe()`

get the observation competition stat a la PEST utility

Returns:

Type	Description
	`pandas.DataFrame`: a dataframe of observation names by
	observation names with values equal to the PEST
	competition statistic

`get_par_css_dataframe()`

get a dataframe of composite scaled sensitivities. Includes both PEST-style and Hill-style.

Returns:

Type	Description
	`pandas.DataFrame`: a dataframe of parameter names, PEST-style and
	Hill-style composite scaled sensitivity

`reset_obscov(arg=None)`

reset the obscov attribute to None

Parameters:

Name	Type	Description	Default
`arg`	`str` or `pyemu.Matrix`	the value to assign to the obscov attribute. If None, the private __obscov attribute is cleared but not reset	`None`

`reset_parcov(arg=None)`

reset the parcov attribute to None

Parameters:

Name	Type	Description	Default
`arg`	`str` or `pyemu.Matrix`	the value to assign to the parcov attribute. If None, the private __parcov attribute is cleared but not reset	`None`

`reset_pst(arg)`

reset the LinearAnalysis.pst attribute

Parameters:

Name	Type	Description	Default
`arg`	`str` or `pyemu.Pst`	the value to assign to the pst attribute	required

la

LinearAnalysis

adj_par_names property

fehalf property

forecast_names property

forecasts property

forecasts_iter property

jco property

mle_covariance property

mle_parameter_estimate property

nnz_obs_names property

obscov property

parcov property

predictions property

predictions_iter property

prior_forecast property

prior_parameter property

prior_prediction property

pst property

qhalf property

qhalfx property

xtqx property

__fromfile(filename, astype=None)

__load_jco()

__load_obscov()

__load_parcov()

__load_predictions()

__load_pst()

adjust_obscov_resfile(resfile=None)

apply_karhunen_loeve_scaling()

clean()

drop_prior_information()

get(par_names=None, obs_names=None, astype=None)

get_cso_dataframe()

get_obs_competition_dataframe()

get_par_css_dataframe()

reset_obscov(arg=None)

reset_parcov(arg=None)

reset_pst(arg)

`LinearAnalysis`

`adj_par_names` `property`

`fehalf` `property`

`forecast_names` `property`

`forecasts` `property`

`forecasts_iter` `property`

`jco` `property`

`mle_covariance` `property`

`mle_parameter_estimate` `property`

`nnz_obs_names` `property`

`obscov` `property`

`parcov` `property`

`predictions` `property`

`predictions_iter` `property`

`prior_forecast` `property`

`prior_parameter` `property`

`prior_prediction` `property`

`pst` `property`

`qhalf` `property`

`qhalfx` `property`

`xtqx` `property`

`__fromfile(filename, astype=None)`

`__load_jco()`

`__load_obscov()`

`__load_parcov()`

`__load_predictions()`

`__load_pst()`

`adjust_obscov_resfile(resfile=None)`

`apply_karhunen_loeve_scaling()`

`clean()`

`drop_prior_information()`

`get(par_names=None, obs_names=None, astype=None)`

`get_cso_dataframe()`

`get_obs_competition_dataframe()`

`get_par_css_dataframe()`

`reset_obscov(arg=None)`

`reset_parcov(arg=None)`

`reset_pst(arg)`