Fisheries Package

Fisheries Model Entry Point

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

Fisheries IO Module

The Fisheries IO module contains functions for handling inputs and outputs

exception natcap.invest.fisheries.fisheries_io.MissingParameter

Bases: exceptions.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([...]),
    },
    {
        ...
    }
]

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)

Fisheries Habitat Scenario Tool Module

The Fisheries Habitat Scenario Tool module contains the high-level code for generating a new Population Parameters CSV File based on habitat area change and the dependencies that particular classes of the given species have on particular habitats.

natcap.invest.fisheries.fisheries_hst.convert_survival_matrix(vars_dict)

Creates a new survival matrix based on the information provided by the user related to habitat area changes and class-level dependencies on those habitats.

Parameters:vars_dict (dictionary) – see fisheries_preprocessor_io.fetch_args for example
Returns:
modified vars_dict with new Survival matrix
accessible using the key ‘Surv_nat_xsa_mod’ with element values that exist between [0,1]
Return type:vars_dict (dictionary)

Example Returns:

ret = {
    # Other Variables...

    'Surv_nat_xsa_mod': np.ndarray([...])
}
natcap.invest.fisheries.fisheries_hst.execute(args)

Fisheries: Habitat Scenario Tool.

The Fisheries Habitat Scenario Tool generates a new Population Parameters CSV File with modified survival attributes across classes and regions based on habitat area changes and class-level dependencies on those habitats.

args[‘workspace_dir’] (str): location into which the resultant
modified Population Parameters CSV file should be placed.
args[‘sexsp’] (str): specifies whether or not the age and stage
classes are distinguished by sex. Options: ‘Yes’ or ‘No’
args[‘population_csv_path’] (str): location of the population
parameters csv file. This file contains all age and stage specific parameters.
args[‘habitat_chg_csv_path’] (str): location of the habitat change
parameters csv file. This file contains habitat area change information.
args[‘habitat_dep_csv_path’] (str): location of the habitat dependency
parameters csv file. This file contains habitat-class dependency information.
args[‘gamma’] (float): describes the relationship between a change
in habitat area and a change in survival of life stages dependent on that habitat
Returns:None

Example Args:

args = {
    'workspace_dir': 'path/to/workspace_dir/',
    'sexsp': 'Yes',
    'population_csv_path': 'path/to/csv',
    'habitat_chg_csv_path': 'path/to/csv',
    'habitat_dep_csv_path': 'path/to/csv',
    'gamma': 0.5,
}

Note

  • Modified Population Parameters CSV File saved to ‘workspace_dir/output/’

Fisheries Habitat Scenario Tool 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 files

Example 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 included
  • ValueError – values are out of bounds or of wrong type
  • IndexError – 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 included
  • ValueError – 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

Module contents