natcap.invest.fisheries package

Submodules

natcap.invest.fisheries.fisheries module

natcap.invest.fisheries.fisheries_hst 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:vars_dict – 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: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.

Parameters:
  • 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_uri'] (str) – location of the population parameters csv file. This file contains all age and stage specific parameters.
  • args['habitat_chg_csv_uri'] (str) – location of the habitat change parameters csv file. This file contains habitat area change information.
  • args['habitat_dep_csv_uri'] (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_uri': 'path/to/csv',
    'habitat_chg_csv_uri': 'path/to/csv',
    'habitat_dep_csv_uri': 'path/to/csv',
    'gamma': 0.5,
}

Note

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

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:vars_dict – dictionary containing necessary variables
Return type: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_uri': 'path/to/csv_uri',
    '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_uri': 'path/to/csv',
    'habitat_dep_csv_uri': '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:

habitat_chg_dict – dictionary containing necessary

variables

Return type:

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:

habitat_dep_dict – dictionary containing necessary

variables

Return type:

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:

pop_dict – dictionary containing verified population

arguments

Return type:

dictionary

Raises:
  • MissingParameter – required parameter not included
  • ValueError – values are out of bounds or of wrong type

Example Returns:

pop_dict = {
    'population_csv_uri': '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_uri': '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

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:vars_dict – modified vars_dict with additional variables
Return type: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:init_cond_func – initial conditions function
Return type: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:rec_func – recruitment function
Return type:function

Example Output of Returned Recruitment Function:

N_next[0], spawners = rec_func(N_prev)

Module contents