API Reference

This section provides a detailed reference for the main classes and functions in the pyewe library.

EwEScenarioInterface(model_path, temp_model_path=None, ecosim_scenario=None)

Interface for running Ecopath with Ecosim scenarios.

Attributes:

Name	Type	Description
_model_path	str	Path to EwE model database file.
_temp_model_path	str	Path to temporary model database file.
_param_manager	ParameterManager	Parameter manager object to manage variable and constant params.

Initialise a EwEScenarioInterface

Given a path to the EwE model database, construct a EwEScenarioInterface object by copying the database to a temporar location so that the given database is not edited. When the interface is cleaned up or the python program exits, the object will close the temporary database and delete the temporary folder it was placed in.

If the user supplies a temporary model path, then the model will copied to that location. Ther user is responsible for deleting the copied database when complete however. This is mainly for debugging purposes to check the underlying state.

'EwEScenarioInterface.cleanup()' is registered at exit but it also good practice to manually call this function after completion.

Parameters:

Name	Type	Description	Default
model_path	str	Path to model database.	required
temp_model_path	Optonal[str]	Path to where the model database should be copied, the user is responsible for cleaning up the copy.	None

add_forcing_function(name, values)

Add/Register forcing function for use in scenario runs.

cleanup()

Clean up files and directoryies created by the interface.

Close the model database and delete the temporary directory containing the model.

get_ecotracer_fg_param_names(param_names='all')

Get functional group parameter names for given parameter prefixes

get_empty_scenarios_df(env_param_names, fg_param_names, n_scenarios=1)

Create empty scenarios dataframe for specified parameters.

Parameters:

Name	Type	Description	Default
env_param_names	list[str]	List of environmental parameter names.	required
fg_param_names	list[str]	List of functional group parameter names, (not combined parameter names and functional group names.)	required
n_scenarios	int	Number of scenarios to create a dataframe for.	1

get_long_scen_dataframe()

Get the full scenario dataframe in a long format.

Construct a scenario dataframe in a long format. Given four columns, 'Scenario', 'Group', 'Parameter', and 'Value'.

reset_parameters()

Remove all saved constant and variable parameters names and values.

run_scenarios(scenarios, save_vars=['Concentration', 'Concentration Biomass', 'Biomass', 'Catch', 'Consumption Biomass', 'Mortality', 'Trophic Level', 'Trophic Level Catch', 'FIB', 'KemptonsQ', 'Shannon Diversity'], show_progress=True, verbose=True)

Run scenarios in given dataframe.

Run all scenarios in the given dataframe and save results in the given formats to the given directory.

Parameters:

Name	Type	Description	Default
scenarios	DataFrame	Scenario dataframe listing parameter values for each scenario.	required

Returns:

Name	Type	Description
results	ResultSet	Containing results

run_scenarios_parallel(scenarios, n_workers=None, save_vars=['Concentration', 'Concentration Biomass', 'Biomass', 'Catch', 'Consumption Biomass', 'Mortality', 'Trophic Level', 'Trophic Level Catch', 'FIB', 'KemptonsQ', 'Shannon Diversity'], show_progress=True)

Run scenarios in parallel.

Parameters:

Name	Type	Description	Default
scenarios	DataFrame	Dataframe containing parameters for each scenario.	required
n_workers	Optional[int]	Number of processes to run in parallel	None

Returns:

Name	Type	Description
ResultSet		results from scenario runs.

set_constant_params(param_names, param_values)

Set parameters that are constant across scenarios

set_ecosim_group_info(group_info)

Set Ecosim group information parameters.

Set the parameterisation for ecosim group information (feeding parameters). The data frame should be in the same format with the same column names as the table in the EwE GUI.

set_ecosim_vulnerabilities(vulnerabilities)

Set Ecosim vulnerabilities to use for all scenario runs.

Set the vulnerabilitiy coefficient used in the Ecosim model. The format for the input dataframe should be the same format as seen in the EwE GUI.

set_simulation_duration(n_years)

Set the number of years to run ecosim for.

ResultSet(py_core, scenarios, results)

Contains results after scenario runs.

This class is the user facing store of results. It should not contain references to the core object, and should contains all output results and scenario being run.

Attributes:

Name	Type	Description
scenarios	dict	Dataframe containing scenario specification for results.
results	dict	Dictionary mapping result variable names to xarrays.
country	str	Name of country that the EwE model is based in.
first_year	int	First Year ecosim is run.
n_scenarios	int	Number of scenarios run.
n_varied	params (int	Number of parameters changed between scenarios.

save_results(save_dir, formats)

Write results to all formats given.

Only NetCDF4, "netcdf", and CSV, "csv", are currently supported.

Parameters:

Name	Type	Description	Default
formats list[str]		list of formats to save results in.	required

CoreInterface()

Interface to update the state of the underlying EwECore.

CoreInterface provides a thin wrapper over the original cCore object defined in the EwE binaries. It should provide convenience functions to carry out operations already defined in the cCore object. Larger scale manipulations should not occur in this class.

Attributes:

Name	Type	Description
_core	cCore	Visual Basic cCore object describing the state of the program.
_ecopath_result_writer	cEcopathResultWriter	Object the handles writing ecopath results
_ecosim_result_writer	cEcosimResultWriter	Object the handles writing ecosim results
_ecotracer_result_writer	cEcotracerResultWriter	Object the handles writing ecotracer results
_state	cStateMonitor	Object handling high level state information bout _core
Ecosim	EcosimStateManager	object that manages scenario loading, model runs and results for Ecosim
Ecotracer	EcotracerStateManager	object that manages scenario loading, model runs and results for Ecotracer

add_forcing_function(name, values)

Add a forcing function to the core instance.

Add a forcing function to the forcing function manager given a list of values and a name. Furthermore, this function prepends a value of 1.0 to the list as EwE begins indexing the first value at 1.0 even though the underlying array is a 0 indexed array. See the deveolpment notes in the documentation for more information.

Parameters:

Name	Type	Description	Default
name	str	Name of the forcing function.	required
values	list[str]	List of values for the forcing function.	required

Returns:

Name	Type	Description
int	int	Index of the forcing function in the forcing manager.

get_country()

Get the country that the model is based on.

get_first_year()

Get the first year for which ecosim is run.

get_functional_group_index(group)

Get the index of a given functional gruop in the ecopath model.

get_functional_group_indices(groups)

Get the indices of the functional groups in the ecopath model.

Get the indices of the functional groups in the ecopath model. This is a one-based index.

get_functional_group_names()

Get the name of all functional groups in the EwE model.

load_model(path)

Load model from a EwE access database file into the EwE core.

n_consumers()

Get the number of consumers in the loaded model.

n_detritus_groups()

Get the number of detritus groups in the loaded model.

n_groups()

Get the number of functional groups in the loaded model.

n_living_groups()

Get the number of living groups in the loaded models.

n_producers()

Get the number of producers in the loaded model

print_summary()

Print summary on the state of the EwE core.

save_all_ecosim_results(dir)

Save all ecosim result variables to the given directory.

save_ecosim_results(dir, result_types, monthly=True, quiet=True)

Save ecosim results for a given setup of result variables.

Parameters:

Name	Type	Description	Default
dir	str	Directory to save csv files to.	required
result_types	str	Names of variables to save.	required
monthly	bool	flag to save monthly or yearly values.	True
quiet	bool	flag to print information.	True

Returns:

Name	Type	Description
bool	bool	True if successful

save_ecotracer_results(filepath)

Save ecotracer results to a given file

Parameters:

Name	Type	Description	Default
filepath	str	Path to save file	required

Returns:

Type	Description
None	successful save

set_default_save_dir(save_dir)

Set the default save directory in underlying core object.

EcosimStateManager(core, state)

Bases: EwEScenarioModel, EwEParameterManager

Ecosim Model State Wrapper

This should be the interface at which Ecosim information is set and retrieved. Parameter setting, results extraction and scenario loading should be controlled via this class.

new_scenario(name, description, author, contact)

Create a new Ecosim scenario.

run()

Run the ecosim model without ecotracer and return whether it was successful.

save_scenario()

Save the current state of the ecosim scenario to the underlying database.

save_scenario_as(name, description)

Save the current state of the ecosim scenario to a new scenario.

set_vulnerabilities(vulnerabilities)

Set ecosim vulnerabilites from a vulnerability matrix.

EcotracerStateManager(core, state)

Bases: EwEScenarioModel, EwEParameterManager

Ecotracer Model State Wrapper

This should be the interface at which Ecotracer information is set and retrieved. Parameter setting, results extraction, scenario loading and ecotracer execution should be controlled via this class.

get_contaminant_forcing_number()

Get the index of the Contaminant forcing function.

Get the index of the contaminant forcing function in the core contaminant forcing function manager. A return a one based index.

new_scenario(name, description, author, contact)

Create a new EcoTracer scenario.

run()

Run the ecosim model with ecotracer and return whether it was successful

save_scenario()

Save the state of the ecotracer scenario to the underlying database.

save_scenario_as(name, description)

Save the state of the ecotracer scenario to the underlying database.

set_contaminant_forcing_number(forcing_index)

Set the index of the contaminant forcing function.

Raises:

Type	Description
EwEError	No forcing function with index: {forcing_index} contained in core.