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