natcap.invest.fisheries package¶
Submodules¶
natcap.invest.fisheries.fisheries module¶
natcap.invest.fisheries.fisheries_hst module¶
natcap.invest.fisheries.fisheries_hst_io module¶
The Fisheries Habitat Scenarios Tool IO module contains functions for handling inputs and outputs
-
natcap.invest.fisheries.fisheries_hst_io.
fetch_args
(args)¶ Fetches input arguments from the user, verifies for correctness and completeness, and returns a list of variables dictionaries
Parameters: args (dictionary) – arguments from the user (same as Fisheries Preprocessor entry point) Returns: dictionary containing necessary variables Return type: vars_dict (dictionary) Raises: ValueError
– parameter mismatch between Population and Habitat CSV filesExample Returns:
vars_dict = { 'workspace_dir': 'path/to/workspace_dir/', 'output_dir': 'path/to/output_dir/', 'sexsp': 2, 'gamma': 0.5, # Pop Vars 'population_csv_path': 'path/to/csv_path', 'Surv_nat_xsa': np.array( [[[...], [...]], [[...], [...]], ...]), 'Classes': np.array([...]), 'Class_vectors': { 'Vulnfishing': np.array([...], [...]), 'Maturity': np.array([...], [...]), 'Duration': np.array([...], [...]), 'Weight': np.array([...], [...]), 'Fecundity': np.array([...], [...]), }, 'Regions': np.array([...]), 'Region_vectors': { 'Exploitationfraction': np.array([...]), 'Larvaldispersal': np.array([...]), }, # Habitat Vars 'habitat_chg_csv_path': 'path/to/csv', 'habitat_dep_csv_path': 'path/to/csv', 'Habitats': ['habitat1', 'habitat2', ...], 'Hab_classes': ['class1', 'class2', ...], 'Hab_regions': ['region1', 'region2', ...], 'Hab_chg_hx': np.array( [[[...], [...]], [[...], [...]], ...]), 'Hab_dep_ha': np.array( [[[...], [...]], [[...], [...]], ...]), 'Hab_class_mvmt_a': np.array([...]), 'Hab_dep_num_a': np.array([...]), }
-
natcap.invest.fisheries.fisheries_hst_io.
read_habitat_chg_csv
(args)¶ Parses and verifies a Habitat Change Parameters CSV file and returns a dictionary of information related to the interaction between a species and the given habitats.
Parses the Habitat Change Parameters CSV file for the following vectors:
- Names of Habitats and Regions
- Habitat Area Change
Parameters: args (dictionary) – arguments from the user (same as Fisheries HST entry point)
Returns: - dictionary containing necessary
variables
Return type: habitat_chg_dict (dictionary)
Raises: MissingParameter
– required parameter not includedValueError
– values are out of bounds or of wrong typeIndexError
– likely a file formatting issue
Example Returns:
habitat_chg_dict = { 'Habitats': ['habitat1', 'habitat2', ...], 'Hab_regions': ['region1', 'region2', ...], 'Hab_chg_hx': np.array( [[[...], [...]], [[...], [...]], ...]), }
-
natcap.invest.fisheries.fisheries_hst_io.
read_habitat_dep_csv
(args)¶ Parses and verifies a Habitat Dependency Parameters CSV file and returns a dictionary of information related to the interaction between a species and the given habitats.
Parses the Habitat Parameters CSV file for the following vectors:
- Names of Habitats and Classes
- Habitat-Class Dependency
The following vectors are derived from the information given in the file:
- Classes where movement between habitats occurs
- Number of habitats that a particular class depends upon
Parameters: args (dictionary) – arguments from the user (same as Fisheries HST entry point)
Returns: - dictionary containing necessary
variables
Return type: habitat_dep_dict (dictionary)
Raises: - MissingParameter - required parameter not included
- ValueError - values are out of bounds or of wrong type
- IndexError - likely a file formatting issue
Example Returns:
habitat_dep_dict = { 'Habitats': ['habitat1', 'habitat2', ...], 'Hab_classes': ['class1', 'class2', ...], 'Hab_dep_ha': np.array( [[[...], [...]], [[...], [...]], ...]), 'Hab_class_mvmt_a': np.array([...]), 'Hab_dep_num_a': np.array([...]), }
-
natcap.invest.fisheries.fisheries_hst_io.
read_population_csv
(args)¶ Parses and verifies a single Population Parameters CSV file
Parses and verifies inputs from the Population Parameters CSV file. If not all necessary vectors are included, the function will raise a MissingParameter exception. Survival matrix will be arranged by class-elements, 2nd dim: sex, and 3rd dim: region. Class vectors will be arranged by class-elements, 2nd dim: sex (depending on whether model is sex-specific) Region vectors will be arraged by region-elements, sex-agnostic.
Parameters: args (dictionary) – arguments provided by user
Returns: - dictionary containing verified population
arguments
Return type: pop_dict (dictionary)
Raises: MissingParameter
– required parameter not includedValueError
– values are out of bounds or of wrong type
Example Returns:
pop_dict = { 'population_csv_path': 'path/to/csv', 'Surv_nat_xsa': np.array( [[...], [...]], [[...], [...]], ...), # Class Vectors 'Classes': np.array([...]), 'Class_vector_names': [...], 'Class_vectors': { 'Vulnfishing': np.array([...], [...]), 'Maturity': np.array([...], [...]), 'Duration': np.array([...], [...]), 'Weight': np.array([...], [...]), 'Fecundity': np.array([...], [...]), }, # Region Vectors 'Regions': np.array([...]), 'Region_vector_names': [...], 'Region_vectors': { 'Exploitationfraction': np.array([...]), 'Larvaldispersal': np.array([...]), }, }
-
natcap.invest.fisheries.fisheries_hst_io.
save_population_csv
(vars_dict)¶ Creates a new Population Parameters CSV file based the provided inputs.
Parameters: vars_dict (dictionary) – variables generated by preprocessor arguments and run. Example Args:
args = { 'workspace_dir': 'path/to/workspace_dir/', 'output_dir': 'path/to/output_dir/', 'sexsp': 2, 'population_csv_path': 'path/to/csv', # original csv file 'Surv_nat_xsa': np.ndarray([...]), 'Surv_nat_xsa_mod': np.ndarray([...]), # Class Vectors 'Classes': np.array([...]), 'Class_vector_names': [...], 'Class_vectors': { 'Vulnfishing': np.array([...], [...]), 'Maturity': np.array([...], [...]), 'Duration': np.array([...], [...]), 'Weight': np.array([...], [...]), 'Fecundity': np.array([...], [...]), }, # Region Vectors 'Regions': np.array([...]), 'Region_vector_names': [...], 'Region_vectors': { 'Exploitationfraction': np.array([...]), 'Larvaldispersal': np.array([...]), }, # other arguments are ignored ... }
Note
- Creates a modified Population Parameters CSV file located in the ‘workspace/output/’ folder
- Currently appends ‘_modified’ to original filename for new filename
natcap.invest.fisheries.fisheries_io module¶
The Fisheries IO module contains functions for handling inputs and outputs
-
exception
natcap.invest.fisheries.fisheries_io.
MissingParameter
¶ Bases:
ValueError
An exception class that may be raised when a necessary parameter is not provided by the user.
-
natcap.invest.fisheries.fisheries_io.
create_outputs
(vars_dict)¶ Creates outputs from variables generated in the run_population_model() function in the fisheries_model module
Creates the following:
- Results CSV File
- Results HTML Page
- Results Shapefile (if provided)
- Intermediate CSV File
Parameters: vars_dict (dictionary) – contains variables generated by model run
-
natcap.invest.fisheries.fisheries_io.
fetch_args
(args, create_outputs=True)¶ Fetches input arguments from the user, verifies for correctness and completeness, and returns a list of variables dictionaries
Parameters: args (dictionary) – arguments from the user Returns: - set of variable dictionaries for each
- model
Return type: model_list (list) Example Returns:
model_list = [ { 'workspace_dir': 'path/to/workspace_dir', 'results_suffix': 'scenario_name', 'output_dir': 'path/to/output_dir', 'aoi_vector_path': 'path/to/aoi_vector_path', 'total_timesteps': 100, 'population_type': 'Stage-Based', 'sexsp': 2, 'harvest_units': 'Individuals', 'do_batch': False, 'spawn_units': 'Weight', 'total_init_recruits': 100.0, 'recruitment_type': 'Ricker', 'alpha': 32.4, 'beta': 54.2, 'total_recur_recruits': 92.1, 'migr_cont': True, 'val_cont': True, 'frac_post_process': 0.5, 'unit_price': 5.0, # Pop Params 'population_csv_path': 'path/to/csv_path', 'Survnaturalfrac': numpy.array( [[[...], [...]], [[...], [...]], ...]), 'Classes': numpy.array([...]), 'Vulnfishing': numpy.array([...], [...]), 'Maturity': numpy.array([...], [...]), 'Duration': numpy.array([...], [...]), 'Weight': numpy.array([...], [...]), 'Fecundity': numpy.array([...], [...]), 'Regions': numpy.array([...]), 'Exploitationfraction': numpy.array([...]), 'Larvaldispersal': numpy.array([...]), # Mig Params 'migration_dir': 'path/to/mig_dir', 'Migration': [numpy.matrix, numpy.matrix, ...] }, { ... # additional dictionary doesn't exist when 'do_batch' # is false } ]
Note
This function receives an unmodified ‘args’ dictionary from the user
-
natcap.invest.fisheries.fisheries_io.
read_migration_tables
(args, class_list, region_list)¶ Parses, verifies and orders list of migration matrices necessary for program.
Parameters: - args (dictionary) – same args as model entry point
- class_list (list) – list of class names
- region_list (list) – list of region names
Returns: see example below
Return type: mig_dict (dictionary)
Example Returns:
mig_dict = { 'Migration': [numpy.matrix, numpy.matrix, ...] }
Note
If migration matrices are not provided for all classes, the function will generate identity matrices for missing classes
-
natcap.invest.fisheries.fisheries_io.
read_population_csv
(args, path)¶ Parses and verifies a single Population Parameters CSV file
Parses and verifies inputs from the Population Parameters CSV file. If not all necessary vectors are included, the function will raise a MissingParameter exception. Survival matrix will be arranged by class-elements, 2nd dim: sex, and 3rd dim: region. Class vectors will be arranged by class-elements, 2nd dim: sex (depending on whether model is sex-specific) Region vectors will be arraged by region-elements, sex-agnostic.
Parameters: - args (dictionary) – arguments provided by user
- path (string) – the particular Population Parameters CSV file to parse and verifiy
Returns: - dictionary containing verified population
arguments
Return type: pop_dict (dictionary)
Example Returns:
pop_dict = { 'population_csv_path': 'path/to/csv', 'Survnaturalfrac': numpy.array( [[...], [...]], [[...], [...]], ...), # Class Vectors 'Classes': numpy.array([...]), 'Vulnfishing': numpy.array([...], [...]), 'Maturity': numpy.array([...], [...]), 'Duration': numpy.array([...], [...]), 'Weight': numpy.array([...], [...]), 'Fecundity': numpy.array([...], [...]), # Region Vectors 'Regions': numpy.array([...]), 'Exploitationfraction': numpy.array([...]), 'Larvaldispersal': numpy.array([...]), }
-
natcap.invest.fisheries.fisheries_io.
read_population_csvs
(args)¶ Parses and verifies the Population Parameters CSV files
Parameters: args (dictionary) – arguments provided by user Returns: - list of dictionaries containing verified population
- arguments
Return type: pop_list (list) Example Returns:
pop_list = [ { 'Survnaturalfrac': numpy.array( [[...], [...]], [[...], [...]], ...), # Class Vectors 'Classes': numpy.array([...]), 'Vulnfishing': numpy.array([...], [...]), 'Maturity': numpy.array([...], [...]), 'Duration': numpy.array([...], [...]), 'Weight': numpy.array([...], [...]), 'Fecundity': numpy.array([...], [...]), # Region Vectors 'Regions': numpy.array([...]), 'Exploitationfraction': numpy.array([...]), 'Larvaldispersal': numpy.array([...]), }, { ... } ]
natcap.invest.fisheries.fisheries_model module¶
The Fisheries Model module contains functions for running the model
Variable Suffix Notation: t: time x: area/region a: age/class s: sex
-
natcap.invest.fisheries.fisheries_model.
initialize_vars
(vars_dict)¶ Initializes variables for model run
Parameters: vars_dict (dictionary) – verified arguments and variables Returns: modified vars_dict with additional variables Return type: vars_dict (dictionary) Example Returns:
vars_dict = { # (original vars) 'Survtotalfrac': np.array([...]), # a,s,x 'G_survtotalfrac': np.array([...]), # (same) 'P_survtotalfrac': np.array([...]), # (same) 'N_tasx': np.array([...]), # Index Order: t,a,s,x 'H_tx': np.array([...]), # t,x 'V_tx': np.array([...]), # t,x 'Spawners_t': np.array([...]), }
-
natcap.invest.fisheries.fisheries_model.
run_population_model
(vars_dict, init_cond_func, cycle_func, harvest_func)¶ Runs the model
Parameters: - vars_dict (dictionary) –
- init_cond_func (lambda function) – sets initial conditions
- cycle_func (lambda function) – computes numbers for the next time step
- harvest_func (lambda function) – computes harvest and valuation
Returns: vars_dict (dictionary)
Example Returned Dictionary:
{ # (other items) ... 'N_tasx': np.array([...]), # Index Order: time, class, sex, region 'H_tx': np.array([...]), # Index Order: time, region 'V_tx': np.array([...]), # Index Order: time, region 'Spawners_t': np,array([...]), 'equilibrate_timestep': <int>, }
-
natcap.invest.fisheries.fisheries_model.
set_cycle_func
(vars_dict, rec_func)¶ Creates a function to run a single cycle in the model
Parameters: - vars_dict (dictionary) –
- rec_func (lambda function) – recruitment function
Example Output of Returned Cycle Function:
N_asx = np.array([...]) spawners = <int> N_next, spawners = cycle_func(N_prev)
-
natcap.invest.fisheries.fisheries_model.
set_harvest_func
(vars_dict)¶ Creates harvest function that calculates the given harvest and valuation of the fisheries population over each time step for a given region. Returns None if harvest isn’t selected by user.
Example Outputs of Returned Harvest Function:
H_x, V_x = harv_func(N_tasx) H_x = np.array([3.0, 4.5, 2.5, ...]) V_x = np.array([6.0, 9.0, 5.0, ...])
-
natcap.invest.fisheries.fisheries_model.
set_init_cond_func
(vars_dict)¶ Creates a function to set the initial conditions of the model
Parameters: vars_dict (dictionary) – variables Returns: initial conditions function Return type: init_cond_func (lambda function) Example Return Array:
N_asx = np.ndarray([...])
-
natcap.invest.fisheries.fisheries_model.
set_recru_func
(vars_dict)¶ Creates recruitment function that calculates the number of recruits for class 0 at time t for each region (currently sex agnostic). Also returns number of spawners
Parameters: vars_dict (dictionary) – Returns: recruitment function Return type: rec_func (function) Example Output of Returned Recruitment Function:
N_next[0], spawners = rec_func(N_prev)