pst_handler

`Pst`

Bases: object

All things PEST(++) control file

Parameters:

Name	Type	Description	Default
`filename`	`str`	the name of the control file	required
`load`	`bool`	flag to load the control file. Default is True	`True`
`resfile`	`str`	corresponding residual file. If `None`, a residual file with the control file base name is sought. Default is `None`	`None`

Note

This class is the primary mechanism for dealing with PEST control files. Support is provided for constructing new control files as well as manipulating existing control files.

Example::

pst = pyemu.Pst("my.pst")
pst.control_data.noptmax = -1
pst.write("my_new.pst")

`adj_par_groups` `property`

get the parameter groups with at least one adjustable parameter

Returns:

Type	Description
	[`str`]: a list of parameter groups with
	at least one adjustable parameter

`adj_par_names` `property`

get the adjustable (not fixed or tied) parameter names

Returns:

Type	Description
	[`str`]: list of adjustable (not fixed or tied)
	parameter names

`control_data = ControlData()` `instance-attribute`

pyemu.pst.pst_controldata.ControlData: '* control data' information.
Access with standard PEST variable names

Example::

pst.control_data.noptmax = 2
pst.control_data.pestmode = "estimation"

`estimation` `property`

check if the control_data.pestmode is set to estimation

Returns:

Type	Description
	`bool`: True if `control_data.pestmode` is estmation, False otherwise

`forecast_names` `property`

get the forecast names from the pestpp options (if any). Returns None if no forecasts are named

Returns:

Type	Description
	[`str`]: a list of forecast names.

`greater_than_obs_constraints` `property`

get the names of the observations that are listed as active (non-zero weight) greater than inequality constraints.

Returns:

Type	Description
	`pandas.Series`: names observations that are non-zero weighted
	greater than constraints (`obgnme` startsiwth "g_" or "greater")

Note

Zero-weighted obs are skipped

`greater_than_pi_constraints` `property`

get the names of the prior information eqs that are listed as active (non-zero weight) greater than inequality constraints.

Returns:

Type	Description
	`pandas.Series` names of prior information that are non-zero weighted
	greater than constraints (`obgnme` startsiwth "g_" or "greater")

Note

Zero-weighted pi are skipped

`input_files` `property`

list of model input file names

Returns:

Type	Description
	`[str]`: a list of model input file names, extracted from `Pst.model_input_data.model_file`. Returns `None` if this attribute is `None`

Note

Use Pst.model_input_data to access the template-input file information for writing/modification

`instruction_files` `property`

list of instruction file names Returns: [str]: a list of instruction file names, extracted from Pst.model_output_data.pest_file. Returns None if this attribute is None

Note

Use Pst.model_output_data to access the instruction-output file information for writing/modification

`less_than_obs_constraints` `property`

get the names of the observations that are listed as active (non-zero weight) less than inequality constraints.

Returns:

Type	Description
	`pandas.Series`: names of observations that are non-zero weighted less
	than constraints (`obgnme` starts with 'l_' or "less")

Note

Zero-weighted obs are skipped

`less_than_pi_constraints` `property`

get the names of the prior information eqs that are listed as active (non-zero weight) less than inequality constraints.

Returns:

Type	Description
	`pandas.Series`: names of prior information that are non-zero weighted
	less than constraints (`obgnme` starts with "l_" or "less")

Note

Zero-weighted pi are skipped

`nnz_obs` `property`

get the number of non-zero weighted observations

Returns:

Type	Description
	`int`: the number of non-zeros weighted observations

`nnz_obs_groups` `property`

get the observation groups that contain at least one non-zero weighted observation

Returns:

Type	Description
	[`str`]: a list of observation groups that contain at
	least one non-zero weighted observation

`nnz_obs_names` `property`

get the non-zero weight observation names

Returns:

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

`nobs` `property`

get the number of observations

Returns:

Type	Description
	`int`: the number of observations

`npar` `property`

get number of parameters

Returns:

Type	Description
	`int`: the number of parameters

`npar_adj` `property`

get the number of adjustable parameters (not fixed or tied)

Returns:

Type	Description
	`int`: the number of adjustable parameters

`nprior` `property`

number of prior information equations

Returns:

Type	Description
	`int`: the number of prior info equations

`obs_groups` `property`

get the observation groups

Returns:

Type	Description
	[`str`]: a list of unique observation groups

`obs_names` `property`

get the observation names

Returns:

Type	Description
	[`str`]: a list of observation names

`observation_data = None` `instance-attribute`

pandas.DataFrame: '* observation data' information. Columns are standard PEST variable names

Example::

pst.observation_data.loc[:,"weight"] = 1.0
pst.observation_data.loc[:,"obgnme"] = "obs_group"

`output_files` `property`

list of model output file names Returns: [str]: a list of model output file names, extracted from Pst.model_output_data.model_file. Returns None if this attribute is None

Note

Use Pst.model_output_data to access the instruction-output file information for writing/modification

`par_groups` `property`

get the parameter groups

Returns:

Type	Description
	[`str`]: a list of parameter groups

`par_names` `property`

get the parameter names

Returns:

Type	Description
	[`str`]: a list of parameter names

`parameter_data = None` `instance-attribute`

pandas.DataFrame: '* parameter data' information. Columns are standard PEST variable names

Example::

pst.parameter_data.loc[:,"partrans"] = "log"
pst.parameter_data.loc[:,"parubnd"] = 10.0

`phi` `property`

get the weighted total objective function.

Returns:

Type	Description
	`float`: sum of squared residuals

Note

Requires Pst.res (the residuals file) to be available

`phi_components` `property`

get the individual components of the total objective function

Returns:

Type	Description
	`dict`: dictionary of observation group, contribution to total phi

Note

Requires Pst.res (the residuals file) to be available

`phi_components_normalized` `property`

get the individual components of the total objective function normalized to the total PHI being 1.0

Returns:

Type	Description
	`dict`: dictionary of observation group,
	normalized contribution to total phi

Note

Requires Pst.res (the residuals file) to be available

`prior_groups` `property`

get the prior info groups

Returns:

Type	Description
	[`str`]: a list of prior information groups

`prior_information = None` `instance-attribute`

pandas.DataFrame: '* prior information' data. Columns are standard PEST variable names

`prior_names` `property`

get the prior information names

Returns:

Type	Description
	[`str`]: a list of prior information names

`reg_data = RegData()` `instance-attribute`

pyemu.pst.pst_controldata.RegData: '* regularization' section information. Access with standard PEST variable names.

Example::

pst.reg_data.phimlim = 1.00 #yeah right!

`res` `property`

get the residuals dataframe attribute

Returns:

Type	Description
	`pandas.DataFrame`: a dataframe containing the
	residuals information.

Note

if the Pst.__res attribute has not been loaded, this call loads the res dataframe from a file

Example::

# print the observed and simulated values for non-zero weighted obs
print(pst.res.loc[pst.nnz_obs_names,["modelled","measured"]])

`svd_data = SvdData()` `instance-attribute`

pyemu.pst.pst_controldata.SvdData: '* singular value decomposition' section information.
Access with standard PEST variable names

Example::

pst.svd_data.maxsing = 100

`template_files` `property`

list of template file names

Returns:

Type	Description
	`[str]`: a list of template file names, extracted from `Pst.model_input_data.pest_file`. Returns `None` if this attribute is `None`

Note

Use Pst.model_input_data to access the template-input file information for writing/modification

`tied` `property`

list of tied parameter names

Returns:

Type	Description
	`pandas.DataFrame`: a dataframe of tied parameter information.
	Columns of `tied` are `parnme` and `partied`. Returns `None` if
	no tied parameters are found.

`zero_weight_obs_names` `property`

get the zero-weighted observation names

Returns:

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

`__reset_weights(target_phis, res_idxs, obs_idxs)`

private method to reset weights based on target phi values for each group. This method should not be called directly

Parameters:

Name	Type	Description	Default
`target_phis`	`dict`	target phi contribution for groups to reweight	required
`res_idxs`	`dict`	the index positions of each group of interest in the res dataframe	required
`obs_idxs`	`dict`	the index positions of each group of interest in the observation data dataframe	required

`add_observations(ins_file, out_file=None, pst_path=None, inschek=True)`

add new observations to a control file

Parameters:

Name	Type	Description	Default
`ins_file`	`str`	instruction file with exclusively new observation names	required
`out_file`	`str`	model output file. If None, then ins_file.replace(".ins","") is used. Default is None	`None`
`pst_path`	`str`	the path to append to the instruction file and out file in the control file. If not None, then any existing path in front of the template or in file is split off and pst_path is prepended. If python is being run in a directory other than where the control file will reside, it is useful to pass `pst_path` as `.`. Default is None	`None`
`inschek`	`bool`	flag to try to process the existing output file using the `pyemu.InstructionFile` class. If successful, processed outputs are used as obsvals	`True`

Returns:

Type	Description
	`pandas.DataFrame`: the data for the new observations that were added

Note

populates the new observation information with default values

Example::

pst = pyemu.Pst(os.path.join("template", "my.pst"))
pst.add_observations(os.path.join("template","new_obs.dat.ins"), pst_path=".")
pst.write(os.path.join("template", "my_new.pst")

`add_parameters(template_file, in_file=None, pst_path=None)`

add new parameters to an existing control file

Parameters:

Name	Type	Description	Default
`template_file`	`str`	template file with (possibly) some new parameters	required
`in_file`	`str`	model input file. If None, template_file.replace('.tpl','') is used. Default is None.	`None`
`pst_path`	`str`	the path to append to the template_file and in_file in the control file. If not None, then any existing path in front of the template or in file is split off and pst_path is prepended. If python is being run in a directory other than where the control file will reside, it is useful to pass `pst_path` as `.`. Default is None	`None`

Returns:

Type	Description
	`pandas.DataFrame`: the data for the new parameters that were added.
	If no new parameters are in the new template file, returns None

Note

populates the new parameter information with default values

Example::

pst = pyemu.Pst(os.path.join("template","my.pst"))
pst.add_parameters(os.path.join("template","new_pars.dat.tpl",pst_path=".")
pst.write(os.path.join("template","my_new.pst")

`add_pars_as_obs(pst_path='.', par_sigma_range=4, name_prefix='')`

add all parameter values as observation values by creating a new template and instruction file and adding them to the control file

Parameters:

Name	Type	Description	Default
`pst_path`	`str`	the path to the control file from where python is running. Default is "." (python is running in the same directory as the control file)	`'.'`
`par_sigma_range`	`int`	number of standard deviations implied by the distance between the parameter bounds. Used to set the weights for the range observations	`4`
`name_prefix`	`str`	a tag to prepend to the observation names and the cooresponding I/O files	`''`

Returns: DataFrame: info for the new observations

`add_pi_equation(par_names, pilbl=None, rhs=0.0, weight=1.0, obs_group='pi_obgnme', coef_dict={})`

a helper to construct a new prior information equation.

Parameters:

Name	Type	Description	Default
`par_names`	[`str`]	parameter names in the equation	required
`pilbl`	`str`	name to assign the prior information equation. If None, a generic equation name is formed. Default is None	`None`
`rhs`	`float`	the right-hand side of the pi equation	`0.0`
`weight`	`float`	the weight of the equation	`1.0`
`obs_group`	`str`	the observation group for the equation. Default is 'pi_obgnme'	`'pi_obgnme'`
`coef_dict`	`dict`	a dictionary of parameter name, coefficient pairs to assign leading coefficients for one or more parameters in the equation. If a parameter is not listed, 1.0 is used for its coefficients. Default is {}	`{}`

Example::

pst = pyemu.Pst("pest.pst")
# add a pi equation for the first adjustable parameter
pst.add_pi_equation(pst.adj_par_names[0],pilbl="pi1",rhs=1.0)
# add a pi equation for 1.5 times the 2nd and 3 times the 3rd adj pars to sum together to 2.0
names = pst.adj_par_names[[1,2]]
pst.add_pi_equation(names,coef_dict={names[0]:1.5,names[1]:3})

`add_transform_columns(include_offset_and_scale=False)`

add transformed values to the Pst.parameter_data attribute

Parameters:

Name	Type	Description	Default
`include_offset_and_scale`	`bool`	flag to apply the scale and offset values before	`False`

Note

adds parval1_trans, parlbnd_trans and parubnd_trans to Pst.parameter_data

Example::

pst = pyemu.Pst("pest.pst")
pst.add_transform_columns()
print(pst.parameter_data.parval1_trans

`adjust_weights(obs_dict=None, obsgrp_dict=None)`

reset the weights of observations or observation groups to contribute a specified amount to the composite objective function

Parameters:

Name	Type	Description	Default
`obs_dict`	`dict`	dictionary of observation name,new contribution pairs	`None`
`obsgrp_dict`	`dict`	dictionary of obs group name,contribution pairs	`None`

Notes

If a group is assigned a contribution of 0, all observations in that group will be assigned zero weight.

If a group is assigned a nonzero contribution AND all observations in that group start with zero weight, the observations will be assigned weight of 1.0 to allow balancing.

If groups obsgrp_dict is not passed, all nonzero

Example::

pst = pyemu.Pst("my.pst")

# adjust a single observation
pst.adjust_weights(obs_dict={"obs1":10})

# adjust a single observation group
pst.adjust_weights(obsgrp_dict={"group1":100.0})

# make all non-zero weighted groups have a contribution of 100.0
balanced_groups = {grp:100 for grp in pst.nnz_obs_groups}
pst.adjust_weights(obsgrp_dict=balanced_groups)

`adjust_weights_discrepancy(resfile=None, original_ceiling=True, bygroups=False)`

adjusts the weights of each non-zero weight observation based on the residual in the pest residual file so each observations contribution to phi is 1.0 (e.g. Mozorov's discrepancy principal)

Parameters:

Name	Type	Description	Default
`resfile`	`str`	residual file name. If None, try to use a residual file with the Pst case name. Default is None	`None`
`original_ceiling`	`bool`	flag to keep weights from increasing - this is generally a good idea. Default is True	`True`
`bygroups`	`bool`	flag to adjust weights by groups. If False, the weight of each non-zero weighted observation is adjusted individually. If True, intergroup weighting is preserved (the contribution to each group is used) but this may result in some strangeness if some observations in a group have a really low phi already.	`False`

Example::

pst = pyemu.Pst("my.pst")
print(pst.phi) #assumes "my.res" is colocated with "my.pst"
pst.adjust_weights_discrepancy()
print(pst.phi) # phi should equal number of non-zero observations

`bounds_report(iterations=None)`

report how many parameters are at bounds. If ensemble, the base enbsemble member is evaluated

Parameters:

Name	Type	Description	Default
`iterations`	[`int`]	a list of iterations for which a bounds report is requested If None, all iterations for which `par` files are located are reported. Default is None	`None`

Returns:

Type	Description
	`df`: a pandas DataFrame object with rows being parameter groups and columns _num_at_ub, _num_at_lb, and _total_at_bounds row 0 is total at bounds, subsequent rows correspond with groups

Example

pst = pyemu.Pst("my.pst") df = pst.bound_report(iterations=[0,2,3])

`build_increments()`

experimental method to calculate parameter increments for use in the finite difference perturbation calculations

Note

user beware!

`calculate_perturbations()`

experimental method to calculate finite difference parameter perturbations.

Note:

The perturbation values are added to the
`Pst.parameter_data` attribute - user beware!

`dialate_par_bounds(dialate_factor, center=True)`

increase the distance between the parameter bounds while respecting the log transformation status

Parameters:

Name	Type	Description	Default
`dialate_factor`	`varies`	a factor to increase the distance between parameter bounds. Can be a float or a dict of str-float pars.	required
`center`	`bool`	flag to dialate from the center point between the bounds. If False, then the dialation is from the `parval1` values. Beware that using center False can have produce the some strange results...	`True`

`drop_observations(ins_file, pst_path=None)`

remove observations in an instruction file from the control file

Parameters:

Name	Type	Description	Default
`ins_file`	`str`	instruction file to remove	required
`pst_path`	`str`	the path to append to the instruction file in the control file. If not None, then any existing path in front of the instruction is split off and pst_path is prepended. If python is being run in a directory other than where the control file will reside, it is useful to pass `pst_path` as `.`. Default is None	`None`

Returns:

Type	Description
	`pandas.DataFrame`: the observation data for the observations that were removed.

Example::

pst = pyemu.Pst(os.path.join("template", "my.pst"))
pst.remove_observations(os.path.join("template","some_obs.dat.ins"), pst_path=".")
pst.write(os.path.join("template", "my_new_with_less_obs.pst")

`drop_parameters(tpl_file, pst_path=None)`

remove parameters in a template file from the control file

Parameters:

Name	Type	Description	Default
`tpl_file`	`str`	template file to remove	required
`pst_path`	`str`	the path to append to the template file in the control file. If not None, then any existing path in front of the template or in file is split off and pst_path is prepended. If python is being run in a directory other than where the control file will reside, it is useful to pass `pst_path` as `.`. Default is None	`None`

Returns:

Type	Description
	`pandas.DataFrame`: the parameter data for the parameters that were removed.

Note

This method does not check for multiple occurrences of the same parameter name(s) in across template files so if you have the same parameter in multiple template files, this is not the method you are looking for

Example::

pst = pyemu.Pst(os.path.join("template", "my.pst"))
pst.remove_parameters(os.path.join("template","boring_zone_pars.dat.tpl"), pst_path=".")
pst.write(os.path.join("template", "my_new_with_less_pars.pst")

`enforce_bounds()`

enforce bounds violation

Note

cheap enforcement of simply bringing violators back in bounds

Example::

pst = pyemu.Pst("pest.pst")
pst.parrep("random.par")
pst.enforce_bounds()
pst.write("pest_rando.pst")

`from_io_files(tpl_files, in_files, ins_files, out_files, pst_filename=None, pst_path=None)` `classmethod`

create a Pst instance from model interface files.

Parameters:

Name	Type	Description	Default
`tpl_files`	[`str`]	list of template file names	required
`in_files`	[`str`]	list of model input file names (pairs with template files)	required
`ins_files`	[`str`]	list of instruction file names	required
`out_files`	[`str`]	list of model output file names (pairs with instruction files)	required
`pst_filename`	`str`	name of control file to write. If None, no file is written. Default is None	`None`
`pst_path`	`str`	the path from the control file to the IO files. For example, if the control will be in the same directory as the IO files, then `pst_path` should be '.'. Default is None, which doesn't do any path manipulation on the I/O file names	`None`

Returns:

Type	Description
	`Pst`: new control file instance with parameter and observation names
	found in `tpl_files` and `ins_files`, respectively.

Note

calls pyemu.helpers.pst_from_io_files()

Assigns generic values for parameter info. Tries to use INSCHEK to set somewhat meaningful observation values

all file paths are relatively to where python is running.

Example::

tpl_files = ["my.tpl"]
in_files = ["my.in"]
ins_files = ["my.ins"]
out_files = ["my.out"]
pst = pyemu.Pst.from_io_files(tpl_files,in_files,ins_files,out_files)
pst.control_data.noptmax = 0
pst.write("my.pst)

`from_par_obs_names(par_names=['par1'], obs_names=['obs1'])` `classmethod`

construct a shell Pst instance from parameter and observation names

Parameters:

Name	Type	Description	Default
`par_names`	[`str`]	list of parameter names. Default is [`par1`]	`['par1']`
`obs_names`	[`str`]	list of observation names. Default is [`obs1`]	`['obs1']`

Note

While this method works, it does not make template or instruction files. Users are encouraged to use Pst.from_io_files() for more usefulness

Example::

par_names = ["par1","par2"]
obs_names = ["obs1","obs2"]
pst = pyemu.Pst.from_par_obs_names(par_names,obs_names)

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

get a new pst object with subset of parameters and/or observations

Parameters:

Name	Type	Description	Default
`par_names`	[`str`]	a list of parameter names to have in the new Pst instance. If None, all parameters are in the new Pst instance. Default is None	`None`
`obs_names`	[`str`]	a list of observation names to have in the new Pst instance. If None, all observations are in the new Pst instance. Default is None	`None`

Returns:

Type	Description
	`Pst`: a new Pst instance

Note

passing par_names as None and obs_names as None effectively generates a copy of the current Pst

Does not modify model i/o files - this is just a method for performing pyemu operations

Example::

pst = pyemu.Pst("pest.pst")
new_pst = pst.get(pst.adj_par_names[0],pst.obs_names[:10])

`get_adj_pars_at_bounds(frac_tol=0.01)`

get list of adjustable parameter at/near bounds

Parameters:

Name	Type	Description	Default
`frac_tol`	'float`	fractional tolerance of distance to bound. For upper bound, the value `parubnd * (1-frac_tol)` is used, lower bound uses `parlbnd * (1.0 + frac_tol)`	`0.01`

Returns:

Type	Description
	tuple containing:
	[`str`]: list of parameters at/near lower bound
	[`str`]: list of parameters at/near upper bound

Example::

pst = pyemu.Pst("pest.pst")
at_lb,at_ub = pst.get_adj_pars_at_bounds()
print("pars at lower bound",at_lb)

`get_par_change_limits()`

calculate the various parameter change limits used in pest.

Returns:

Type	Description
	`pandas.DataFrame`: a copy of `Pst.parameter_data`
	with columns for relative and factor change limits

Note:

does not yet support absolute parameter change limits!

Works in control file values space (not log transformed space).  Also
adds columns for effective upper and lower which account for par bounds and the
value of parchglim

example::

pst = pyemu.Pst("pest.pst")
df = pst.get_par_change_limits()
print(df.chg_lower)

`get_res_stats(nonzero=True)`

get some common residual stats by observation group.

Parameters:

Name	Type	Description	Default
`nonzero`	`bool`	calculate stats using only nonzero-weighted observations. This may seem obsvious to most users, but you never know....	`True`

Returns:

Type	Description
	`pd.DataFrame`: a dataframe with columns for groups names and indices of statistic name.

Note

Stats are derived from the current obsvals, weights and grouping in Pst.observation_data and the modelled values in Pst.res. The key here is 'current' because if obsval, weights and/or groupings have changed in Pst.observation_data since the residuals file was generated then the current values for obsval, weight and group are used

the normalized RMSE is normalized against the obsval range (max - min)

Example::

pst = pyemu.Pst("pest.pst")
stats_df = pst.get_res_stats()
print(stats_df.loc["mae",:])

`load(filename, parse_metadata=True)`

entry point load the pest control file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	pst filename	required

Note

This method is called from the Pst constructor unless the load arg is False.

`parrep(parfile=None, enforce_bounds=True, real_name=None, noptmax=0, binary_ens_file=False)`

replicates the pest parrep util. replaces the parval1 field in the parameter data section dataframe with values in a PEST parameter file or a single realization from an ensemble parameter csv file

Parameters:

Name	Type	Description	Default
`parfile`	`str`	parameter file to use. If None, try to find and use a parameter file that corresponds to the case name. If parfile has extension '.par' a single realization parameter file is used If parfile has extension '.csv' an ensemble parameter file is used which invokes real_name If parfile has extension '.jcb' a binary ensemble parameter file is used which invokes real_name Default is None	`None`
`enforce_bounds`	`bool`	flag to enforce parameter bounds after parameter values are updated. This is useful because PEST and PEST++ round the parameter values in the par file, which may cause slight bound violations. Default is `True`	`True`
`real_name`	`str` or `int`	name of the ensemble realization to use for updating the parval1 value in the parameter data section dataframe. If None, try using "base". If "base" not present, use the real_name with smallest index number. Ignored if parfile is of the PEST parameter file format (e.g. not en ensemble)	`None`
`noptmax`	`int`	Value with which to update the pst.control_data.noptmax value Default is 0.	`0`
`binary_ens_file`	`bool`	If True, use binary format to load ensemble file, else assume it's a CSV file	`False`

Example::

pst = pyemu.Pst("pest.pst")
pst.parrep("pest.1.base.par")
pst.control_data.noptmax = 0
pst.write("pest_1.pst")

`plot(kind=None, **kwargs)`

method to plot various parts of the control. This is sweet as!

Parameters:

Name	Type	Description	Default
`kind`	`str`	options are 'prior' (prior parameter histograms, '1to1' (line of equality and sim vs res), 'obs_v_sim' (time series using datetime suffix), 'phi_pie' (pie chart of phi components)	`None`
`kwargs`	`dict`	optional args for plots that are passed to pyemu plot helpers and ultimately to matplotlib	`{}`

Note

Depending on 'kind' argument, a multipage pdf is written

Example::

pst = pyemu.Pst("my.pst")
pst.plot(kind="1to1") # requires Pst.res
pst.plot(kind="prior")
pst.plot(kind="phi_pie")

`process_output_files(pst_path='.')`

processing the model output files using the instruction files and existing model output files.

Parameters:

Name	Type	Description	Default
`pst_path`	`str`	relative path from where python is running to where the control file, instruction files and model output files are located. Default is "." (current python directory)	`'.'`

Returns:

Type	Description
	`pandas.Series`: model output values

Note

requires a complete set of model input files at relative path from where python is running to pst_path

Example::

pst = pyemu.Pst("pest.pst")
obsvals = pst.process_output_files()
print(obsvals)

`proportional_weights(fraction_stdev=1.0, wmax=100.0, leave_zero=True)`

setup weights inversely proportional to the observation value

Parameters:

Name	Type	Description	Default
`fraction_stdev`	`float`	the fraction portion of the observation val to treat as the standard deviation. set to 1.0 for inversely proportional. Default is 1.0	`1.0`
`wmax`	`float`	maximum weight to allow. Default is 100.0	`100.0`
`leave_zero`	`bool`	flag to leave existing zero weights. Default is True	`True`

Example::

pst = pyemu.Pst("pest.pst")
# set the weights of the observations to 20% of the observed value
pst.proportional_weights(fraction_stdev=0.2,wmax=10)
pst.write("pest_propo.pst")

`rectify_pgroups()`

synchronize parameter groups section with the parameter data section

Note

This method is called during Pst.write() to make sure all parameter groups named in * parameter data are included. This is so users don't have to manually keep this section up. This method can also be called during control file modifications to see what parameter groups are present and prepare for modifying the default values in the * parameter group section

Example::

pst = pyemu.Pst("my.pst")
pst.parameter_data.loc["par1","pargp"] = "new_group"
pst.rectify_groups()
pst.parameter_groups.loc["new_group","derinc"] = 1.0

`rectify_pi()`

rectify the prior information equation with the current state of the parameter_data dataframe.

Note

Equations that list fixed, tied or missing parameters are removed completely even if adjustable parameters are also listed in the equation. This method is called during Pst.write()

`rename_observations(name_dict, pst_path='.', insmap=None)`

rename observations in the control and instruction files

Parameters:

Name	Type	Description	Default
`name_dict`	`dict`	mapping of current to new names.	required
`pst_path`	`str`	the path to the control file from where python is running. Default is "." (python is running in the same directory as the control file)	`'.'`

Note

This does a lot of string compare, so its gonna be slow as...

Example::

pst = pyemu.Pst(os.path.join("template","pest.pst"))
name_dict = {"obs1":"obs1_better_name"}
pst.rename_observations(name_dict,pst_path="template")

`rename_parameters(name_dict, pst_path='.', tplmap=None)`

rename parameters in the control and template files

Parameters:

Name	Type	Description	Default
`name_dict`	`dict`	mapping of current to new names.	required
`pst_path`	`str`	the path to the control file from where python is running. Default is "." (python is running in the same directory as the control file)	`'.'`

Note

no attempt is made to maintain the length of the marker strings in the template files, so if your model is sensitive to changes in spacing in the template file(s), this is not a method for you

This does a lot of string compare, so its gonna be slow as...

Example::

pst = pyemu.Pst(os.path.join("template","pest.pst"))
name_dict = {"par1":"par1_better_name"}
pst.rename_parameters(name_dict,pst_path="template")

`sanity_checks(forgive=False)`

some basic check for strangeness

Parameters:

Name	Type	Description	Default
`forgive`	`bool`	flag to forgive (warn) for issues. Default is False	`False`

Note

checks for duplicate names, at least 1 adjustable parameter and at least 1 non-zero-weighted observation

Not nearly as comprehensive as pestchek

Example::

pst = pyemu.Pst("pest.pst")
pst.sanity_checks()

`set_res(res)`

reset the private Pst.res attribute.

Parameters:

Name	Type	Description	Default
`res`		(`pandas.DataFrame` or `str`): something to use as Pst.res attribute. If `res` is `str`, a dataframe is read from file `res`	required

`try_parse_name_metadata()`

try to add meta data columns to parameter and observation data based on item names. Used with the PstFrom process.

Note

metadata is identified in key-value pairs that are separated by a colon. each key-value pair is separated from others by underscore

This works with PstFrom style long names

This method is called programmtically during Pst.load()

`write(new_filename, version=None, check_interface=False)`

main entry point to write a pest control file.

Parameters:

Name	Type	Description	Default
`new_filename`	`str`	name of the new pest control file	required
`version`	`int`	flag for which version of control file to write (must be 1 or 2). if None, uses the number of pars to decide: if number of pars iis greater than 10,000, version 2 is used.	`None`
`check_interface`	`bool`	flag to check the control file par and obs names against the names found in the template and instruction files. Default is False	`False`

Example::

pst = pyemu.Pst("my.pst")
pst.parrep("my.par")
pst.write(my_new.pst")
#write a version 2 control file
pst.write("my_new_v2.pst",version=2)

`write_input_files(pst_path='.')`

writes model input files using template files and current parval1 values.

Parameters:

Name	Type	Description	Default
`pst_path`	`str`	the path to where control file and template files reside. Default is '.'	`'.'`

Note

adds "parval1_trans" column to Pst.parameter_data that includes the effect of scale and offset

Example::

pst = pyemu.Pst("my.pst")

# load final parameter values
pst.parrep("my.par")

# write new model input files with final parameter values
pst.write_input_files()

`write_obs_summary_table(filename=None, group_names=None)`

write a stand alone observation summary latex table or Excel shet filename (str): filename. If None, use .par.tex to write as LaTeX. If filename extension is '.xls' or '.xlsx', tries to write as an Excel file. If filename is "none", no table is written Default is None

Parameters:

Name	Type	Description	Default
`filename`	`str`	filename. If `filename` is "none", no table is written. If None, use .obs.tex. If filename extension is '.xls' or '.xlsx', tries to write as an Excel file. Default is None	`None`
`group_names`	`dict`	obs group names : table names. For example {"hds":"simulated groundwater level"}. Default is None	`None`

Returns:

Type	Description
	`pandas.DataFrame`: the summary observation group dataframe

Example::

pst = pyemu.Pst("my.pst")
pst.write_obs_summary_table(filename="obs.tex")

`write_par_summary_table(filename=None, group_names=None, sigma_range=4.0, report_in_linear_space=False)`

write a stand alone parameter summary latex table or Excel sheet

Parameters:

Name	Type	Description	Default
`filename`	`str`	filename. If None, use .par.tex to write as LaTeX. If filename extension is '.xls' or '.xlsx', tries to write as an Excel file. If `filename` is "none", no table is written Default is None	`None`
`group_names`	`dict`	par group names : table names. For example {"w0":"well stress period 1"}. Default is None	`None`
`sigma_range`	`float`	number of standard deviations represented by parameter bounds. Default is 4.0, implying 95% confidence bounds	`4.0`
`report_in_linear_space`	`bool`	flag, if True, that reports all logtransformed values in linear space. This renders standard deviation meaningless, so that column is skipped	`False`

Returns:

Type	Description
	`pandas.DataFrame`: the summary parameter group dataframe

Example::

pst = pyemu.Pst("my.pst")
pst.write_par_summary_table(filename="par.tex")

pst_handler

Pst

adj_par_groups property

adj_par_names property

control_data = ControlData() instance-attribute

estimation property

forecast_names property

greater_than_obs_constraints property

greater_than_pi_constraints property

input_files property

instruction_files property

less_than_obs_constraints property

less_than_pi_constraints property

nnz_obs property

nnz_obs_groups property

nnz_obs_names property

nobs property

npar property

npar_adj property

nprior property

obs_groups property

obs_names property

observation_data = None instance-attribute

output_files property

par_groups property

par_names property

parameter_data = None instance-attribute

phi property

phi_components property

phi_components_normalized property

prior_groups property

prior_information = None instance-attribute

prior_names property

reg_data = RegData() instance-attribute

res property

svd_data = SvdData() instance-attribute

template_files property

tied property

zero_weight_obs_names property

__reset_weights(target_phis, res_idxs, obs_idxs)

add_observations(ins_file, out_file=None, pst_path=None, inschek=True)

add_parameters(template_file, in_file=None, pst_path=None)

add_pars_as_obs(pst_path='.', par_sigma_range=4, name_prefix='')

add_pi_equation(par_names, pilbl=None, rhs=0.0, weight=1.0, obs_group='pi_obgnme', coef_dict={})

add_transform_columns(include_offset_and_scale=False)

adjust_weights(obs_dict=None, obsgrp_dict=None)

adjust_weights_discrepancy(resfile=None, original_ceiling=True, bygroups=False)

bounds_report(iterations=None)

build_increments()

calculate_perturbations()

dialate_par_bounds(dialate_factor, center=True)

drop_observations(ins_file, pst_path=None)

drop_parameters(tpl_file, pst_path=None)

enforce_bounds()

from_io_files(tpl_files, in_files, ins_files, out_files, pst_filename=None, pst_path=None) classmethod

from_par_obs_names(par_names=['par1'], obs_names=['obs1']) classmethod

get(par_names=None, obs_names=None)

get_adj_pars_at_bounds(frac_tol=0.01)

get_par_change_limits()

get_res_stats(nonzero=True)

load(filename, parse_metadata=True)

parrep(parfile=None, enforce_bounds=True, real_name=None, noptmax=0, binary_ens_file=False)

plot(kind=None, **kwargs)

process_output_files(pst_path='.')

proportional_weights(fraction_stdev=1.0, wmax=100.0, leave_zero=True)

rectify_pgroups()

rectify_pi()

rename_observations(name_dict, pst_path='.', insmap=None)

rename_parameters(name_dict, pst_path='.', tplmap=None)

sanity_checks(forgive=False)

set_res(res)

try_parse_name_metadata()

write(new_filename, version=None, check_interface=False)

write_input_files(pst_path='.')

write_obs_summary_table(filename=None, group_names=None)

write_par_summary_table(filename=None, group_names=None, sigma_range=4.0, report_in_linear_space=False)

`Pst`

`adj_par_groups` `property`

`adj_par_names` `property`

`control_data = ControlData()` `instance-attribute`

`estimation` `property`

`forecast_names` `property`

`greater_than_obs_constraints` `property`

`greater_than_pi_constraints` `property`

`input_files` `property`

`instruction_files` `property`

`less_than_obs_constraints` `property`

`less_than_pi_constraints` `property`

`nnz_obs` `property`

`nnz_obs_groups` `property`

`nnz_obs_names` `property`

`nobs` `property`

`npar` `property`

`npar_adj` `property`

`nprior` `property`

`obs_groups` `property`

`obs_names` `property`

`observation_data = None` `instance-attribute`

`output_files` `property`

`par_groups` `property`

`par_names` `property`

`parameter_data = None` `instance-attribute`

`phi` `property`

`phi_components` `property`

`phi_components_normalized` `property`

`prior_groups` `property`

`prior_information = None` `instance-attribute`

`prior_names` `property`

`reg_data = RegData()` `instance-attribute`

`res` `property`

`svd_data = SvdData()` `instance-attribute`

`template_files` `property`

`tied` `property`

`zero_weight_obs_names` `property`

`__reset_weights(target_phis, res_idxs, obs_idxs)`

`add_observations(ins_file, out_file=None, pst_path=None, inschek=True)`

`add_parameters(template_file, in_file=None, pst_path=None)`

`add_pars_as_obs(pst_path='.', par_sigma_range=4, name_prefix='')`

`add_pi_equation(par_names, pilbl=None, rhs=0.0, weight=1.0, obs_group='pi_obgnme', coef_dict={})`

`add_transform_columns(include_offset_and_scale=False)`

`adjust_weights(obs_dict=None, obsgrp_dict=None)`

`adjust_weights_discrepancy(resfile=None, original_ceiling=True, bygroups=False)`

`bounds_report(iterations=None)`

`build_increments()`

`calculate_perturbations()`

`dialate_par_bounds(dialate_factor, center=True)`

`drop_observations(ins_file, pst_path=None)`

`drop_parameters(tpl_file, pst_path=None)`

`enforce_bounds()`

`from_io_files(tpl_files, in_files, ins_files, out_files, pst_filename=None, pst_path=None)` `classmethod`

`from_par_obs_names(par_names=['par1'], obs_names=['obs1'])` `classmethod`

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

`get_adj_pars_at_bounds(frac_tol=0.01)`

`get_par_change_limits()`

`get_res_stats(nonzero=True)`

`load(filename, parse_metadata=True)`

`parrep(parfile=None, enforce_bounds=True, real_name=None, noptmax=0, binary_ens_file=False)`

`plot(kind=None, **kwargs)`

`process_output_files(pst_path='.')`

`proportional_weights(fraction_stdev=1.0, wmax=100.0, leave_zero=True)`

`rectify_pgroups()`

`rectify_pi()`

`rename_observations(name_dict, pst_path='.', insmap=None)`

`rename_parameters(name_dict, pst_path='.', tplmap=None)`

`sanity_checks(forgive=False)`

`set_res(res)`

`try_parse_name_metadata()`

`write(new_filename, version=None, check_interface=False)`

`write_input_files(pst_path='.')`

`write_obs_summary_table(filename=None, group_names=None)`

`write_par_summary_table(filename=None, group_names=None, sigma_range=4.0, report_in_linear_space=False)`