Fisheries Package

Fisheries Model Entry Point

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

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

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