natcap.invest.fisheries.fisheries¶
Fisheries.
-
natcap.invest.fisheries.fisheries.
execute
(args, create_outputs=True)¶ Fisheries.
- args[‘workspace_dir’] (str): location into which all intermediate
and output files should be placed.
args[‘results_suffix’] (str): a string to append to output filenames
- args[‘aoi_vector_path’] (str): location of shapefile which will be
used as subregions for calculation. Each region must contain a ‘Name’ attribute (case-sensitive) matching the given name in the population parameters csv file.
- args[‘timesteps’] (int): represents the number of time steps that
the user desires the model to run.
- args[‘population_type’] (str): specifies whether the model
is age-specific or stage-specific. Options will be either “Age Specific” or “Stage Specific” and will change which equation is used in modeling growth.
- args[‘sexsp’] (str): specifies whether or not the age and stage
classes are distinguished by sex.
- args[‘harvest_units’] (str): specifies how the user wants to get
the harvest data. Options are either “Individuals” or “Weight”, and will change the harvest equation used in core. (Required if args[‘val_cont’] is True)
- args[‘do_batch’] (bool): specifies whether program will perform a
single model run or a batch (set) of model runs.
- args[‘population_csv_path’] (str): location of the population
parameters csv. This will contain all age and stage specific parameters. (Required if args[‘do_batch’] is False)
- args[‘population_csv_dir’] (str): location of the directory that
contains the Population Parameters CSV files for batch processing (Required if args[‘do_batch’] is True)
- args[‘spawn_units’] (str): specifies whether the spawner abundance used in
the recruitment function should be calculated in terms of number of individuals (‘Individuals’) or in terms of biomass (‘Weight’). If ‘Weight’ is selected, the user must provide a ‘Weight’ vector alongside the survival matrix in the Population Parameters CSV File. The ‘alpha’ and ‘beta’ parameters provided by the user should correspond to the selected choice.
- args[‘total_init_recruits’] (float): represents the initial number of
recruits that will be used in calculation of population on a per area basis.
- args[‘recruitment_type’] (str): name corresponding to one of the built-in
recruitment functions {‘Beverton-Holt’, ‘Ricker’, ‘Fecundity’, Fixed}, or ‘Other’, meaning that the user is passing in their own recruitment function as an anonymous python function via the optional dictionary argument ‘recruitment_func’.
- args[‘recruitment_func’] (function): Required if args[‘recruitment_type’]
is set to ‘Other’. See below for instructions on how to create a user- defined recruitment function.
- args[‘alpha’] (float): must exist within args for BH or Ricker Recruitment.
Parameter that will be used in calculation of recruitment.
- args[‘beta’] (float): must exist within args for BH or Ricker Recruitment.
Parameter that will be used in calculation of recruitment.
- args[‘total_recur_recruits’] (float): must exist within args for Fixed
Recruitment. Parameter that will be used in calculation of recruitment.
args[‘migr_cont’] (bool): if True, model uses migration.
- args[‘migration_dir’] (str): if this parameter exists, it means migration
is desired. This is the location of the parameters folder containing files for migration. There should be one file for every age class which migrates. (Required if args[‘migr_cont’] is True)
args[‘val_cont’] (bool): if True, model computes valuation.
- args[‘frac_post_process’] (float): represents the fraction of the species
remaining after processing of the whole carcass is complete. This will exist only if valuation is desired for the particular species. (Required if args[‘val_cont’] is True)
- args[‘unit_price’] (float): represents the price for a single unit of
harvest. Exists only if valuation is desired. (Required if args[‘val_cont’] is True)
Example Args:
args = { 'workspace_dir': 'path/to/workspace_dir/', 'results_suffix': 'scenario_name', 'aoi_vector_path': 'path/to/aoi_vector_path', 'total_timesteps': 100, 'population_type': 'Stage-Based', 'sexsp': 'Yes', 'harvest_units': 'Individuals', 'do_batch': False, 'population_csv_path': 'path/to/csv_path', 'population_csv_dir': '', 'spawn_units': 'Weight', 'total_init_recruits': 100000.0, 'recruitment_type': 'Ricker', 'alpha': 32.4, 'beta': 54.2, 'total_recur_recruits': 92.1, 'migr_cont': True, 'migration_dir': 'path/to/mig_dir/', 'val_cont': True, 'frac_post_process': 0.5, 'unit_price': 5.0, }
Creating a User-Defined Recruitment Function
An optional argument has been created in the Fisheries Model to allow users proficient in Python to pass their own recruitment function into the program via the args dictionary.
Using the Beverton-Holt recruitment function as an example, here’s how a user might create and pass in their own recruitment function:
import natcap.invest import numpy as np # define input data Matu = np.array([...]) # the Maturity vector in the Population Parameters File Weight = np.array([...]) # the Weight vector in the Population Parameters File LarvDisp = np.array([...]) # the LarvalDispersal vector in the Population Parameters File alpha = 2.0 # scalar value beta = 10.0 # scalar value sexsp = 2 # 1 = not sex-specific, 2 = sex-specific # create recruitment function def spawners(N_prev): return (N_prev * Matu * Weight).sum() def rec_func_BH(N_prev): N_0 = (LarvDisp * ((alpha * spawners( N_prev) / (beta + spawners(N_prev)))) / sexsp) return (N_0, spawners(N_prev)) # fill out args dictionary args = {} # ... define other arguments ... args['recruitment_type'] = 'Other' # lets program know to use user- defined function args['recruitment_func'] = rec_func_BH # pass recruitment function as 'anonymous' Python function # run model natcap.invest.fisheries.fisheries.execute(args)
Conditions that a new recruitment function must meet to run properly:
- The function must accept as an argument: a single numpy three-
dimensional array (N_prev) representing the state of the population at the previous time step. N_prev has three dimensions: the indices of the first dimension correspond to the region (must be in same order as provided in the Population Parameters File), the indices of the second dimension represent the sex if it is specific (i.e. two indices representing female, then male if the model is ‘sex-specific’, else just a single zero index representing the female and male populations aggregated together), and the indicies of the third dimension represent age/stage in ascending order.
- The function must return: a tuple of two values. The first value
(N_0) being a single numpy one-dimensional array representing the youngest age of the population for the next time step. The indices of the array correspond to the regions of the population (outputted in same order as provided). If the model is sex-specific, it is currently assumed that males and females are produced in equal number and that the returned array has been already been divided by 2 in the recruitment function. The second value (spawners) is the number or weight of the spawners created by the population from the previous time step, provided as a scalar float value (non-negative).
Example of How Recruitment Function Operates within Fisheries Model:
# input data N_prev_xsa = [[[region0-female-age0, region0-female-age1], [region0-male-age0, region1-male-age1]], [[region1-female-age0, region1-female-age1], [region1-male-age0], [region1-male-age1]]] # execute function N_0_x, spawners = rec_func(N_prev_xsa) # output data - where N_0 contains information about the youngest # age/stage of the population for the next time step: N_0_x = [region0-age0, region1-age0] # if sex-specific, rec_func should divide by two before returning type(spawners) is float