Finfish Aquaculture Package

Model Entry Point

invest_natcap.finfish_aquaculture.finfish_aquaculture.execute(args)

This function will take care of preparing files passed into the finfish aquaculture model. It will handle all files/inputs associated with biophysical and valuation calculations and manipulations. It will create objects to be passed to the aquaculture_core.py module. It may write log, warning, or error messages to stdout.

Parameters:
  • workspace_dir (string) – The directory in which to place all result files.
  • ff_farm_loc (string) – URI that points to a shape file of fishery locations
  • farm_ID (string) – column heading used to describe individual farms. Used to link GIS location data to later inputs.
  • g_param_a (float) – Growth parameter alpha, used in modeling fish growth, should be an int or float.
  • g_param_b (float) – Growth parameter beta, used in modeling fish growth, should be an int or float.
  • g_param_tau (float) – Growth parameter tau, used in modeling fish growth, should be an int or float
  • g_param_a_sd (float) – (description)
  • g_param_b_sd (float) – (description)
  • water_temp_tbl (string) – URI to a CSV table where daily water temperature values are stored from one year
  • farm_op_tbl (string) – URI to CSV table of static variables for calculations
  • outplant_buffer (int) – This value will allow the outplanting start day to be flexible plus or minus the number of days specified here.
  • do_valuation (boolean) – Boolean that indicates whether or not valuation should be performed on the aquaculture model
  • p_per_kg (float) – Market price per kilogram of processed fish
  • frac_p (float) – Fraction of market price that accounts for costs rather than profit
  • discount (float) – Daily market discount rate

Example Args Dictionary:

{
    'workspace_dir': 'path/to/workspace_dir',
    'ff_farm_loc': 'path/to/shapefile',
    'farm_ID': 'FarmID'
    'g_param_a': 0.038,
    'g_param_b': 0.6667,
    'g_param_tau': 0.08,
    'use_uncertainty': True,
    'g_param_a_sd': 0.005,
    'g_param_b_sd': 0.05,
    'num_monte_carlo_runs': 1000,
    'water_temp_tbl': 'path/to/water_temp_tbl',
    'farm_op_tbl': 'path/to/farm_op_tbl',
    'outplant_buffer': 3,
    'do_valuation': True,
    'p_per_kg': 2.25,
    'frac_p': 0.3,
    'discount': 0.000192,
}

Finfish Aquaculture

inVEST finfish aquaculture filehandler for biophysical and valuation data

invest_natcap.finfish_aquaculture.finfish_aquaculture.execute(args)

This function will take care of preparing files passed into the finfish aquaculture model. It will handle all files/inputs associated with biophysical and valuation calculations and manipulations. It will create objects to be passed to the aquaculture_core.py module. It may write log, warning, or error messages to stdout.

Parameters:
  • workspace_dir (string) – The directory in which to place all result files.
  • ff_farm_loc (string) – URI that points to a shape file of fishery locations
  • farm_ID (string) – column heading used to describe individual farms. Used to link GIS location data to later inputs.
  • g_param_a (float) – Growth parameter alpha, used in modeling fish growth, should be an int or float.
  • g_param_b (float) – Growth parameter beta, used in modeling fish growth, should be an int or float.
  • g_param_tau (float) – Growth parameter tau, used in modeling fish growth, should be an int or float
  • g_param_a_sd (float) – (description)
  • g_param_b_sd (float) – (description)
  • water_temp_tbl (string) – URI to a CSV table where daily water temperature values are stored from one year
  • farm_op_tbl (string) – URI to CSV table of static variables for calculations
  • outplant_buffer (int) – This value will allow the outplanting start day to be flexible plus or minus the number of days specified here.
  • do_valuation (boolean) – Boolean that indicates whether or not valuation should be performed on the aquaculture model
  • p_per_kg (float) – Market price per kilogram of processed fish
  • frac_p (float) – Fraction of market price that accounts for costs rather than profit
  • discount (float) – Daily market discount rate

Example Args Dictionary:

{
    'workspace_dir': 'path/to/workspace_dir',
    'ff_farm_loc': 'path/to/shapefile',
    'farm_ID': 'FarmID'
    'g_param_a': 0.038,
    'g_param_b': 0.6667,
    'g_param_tau': 0.08,
    'use_uncertainty': True,
    'g_param_a_sd': 0.005,
    'g_param_b_sd': 0.05,
    'num_monte_carlo_runs': 1000,
    'water_temp_tbl': 'path/to/water_temp_tbl',
    'farm_op_tbl': 'path/to/farm_op_tbl',
    'outplant_buffer': 3,
    'do_valuation': True,
    'p_per_kg': 2.25,
    'frac_p': 0.3,
    'discount': 0.000192,
}
invest_natcap.finfish_aquaculture.finfish_aquaculture.format_ops_table(op_path, farm_ID, ff_aqua_args)

Takes in the path to the operating parameters table as well as the keyword to look for to identify the farm number to go with the parameters, and outputs a 2D dictionary that contains all parameters by farm and description. The outer key is farm number, and the inner key is a string description of the parameter.

Input:

op_path: URI to CSV table of static variables for calculations farm_ID: The string to look for in order to identify the column in

which the farm numbers are stored. That column data will become the keys for the dictionary output.
ff_aqua_args: Dictionary of arguments being created in order to be
passed to the aquaculture core function.
Output:
ff_aqua_args[‘farm_op_dict’]: A dictionary that is built up to store
the static parameters for the aquaculture model run. This is a 2D dictionary, where the outer key is the farm ID number, and the inner keys are strings of parameter names.

Returns nothing.

invest_natcap.finfish_aquaculture.finfish_aquaculture.format_temp_table(temp_path, ff_aqua_args)

This function is doing much the same thing as format_ops_table- it takes in information from a temperature table, and is formatting it into a 2D dictionary as an output.

Input:
temp_path: URI to a CSV file containing temperature data for 365 days
for the farms on which we will look at growth cycles.
ff_aqua_args: Dictionary of arguments that we are building up in order
to pass it to the aquaculture core module.
Output:
ff_aqua_args[‘water_temp_dict’]: A 2D dictionary containing temperature
data for 365 days. The outer keys are days of the year from 0 to 364 (we need to be able to check the day modulo 365) which we manually shift down by 1, and the inner keys are farm ID numbers.

Returns nothing.

Finfish Aquaculture Core

Implementation of the aquaculture calculations, and subsequent outputs. This will pull from data passed in by finfish_aquaculture.

invest_natcap.finfish_aquaculture.finfish_aquaculture_core.calc_farm_cycles(outplant_buffer, a, b, tau, water_temp_dict, farm_op_dict, dur)
Input:
outplant_buffer: The number of days surrounding the outplant day during
which the fish growth cycle can still be started.
a: Growth parameter alpha. Float used as a scaler in the fish growth
equation.
b: Growth paramater beta. Float used as an exponential multiplier in
the fish growth equation.
water_temp_dict: 2D dictionary which contains temperature values for
farms. The outer keys are calendar days as strings, and the inner are farm numbers as strings.
farm_op_dict: 2D dictionary which contains individual operating
parameters for each farm. The outer key is farm number as a string, and the inner is string descriptors of each parameter.
dur: Float which describes the length for the growth simulation to run
in years.

Returns cycle_history where:

cycle_history: Dictionary which contains mappings from farms to a

history of growth for each cycle completed on that farm. These entries are formatted as follows...

Farm->List of Type (day of outplanting,day of harvest, fish weight
(grams))
invest_natcap.finfish_aquaculture.finfish_aquaculture_core.calc_hrv_weight(farm_op_dict, frac, mort, cycle_history)
Input:
farm_op_dict: 2D dictionary which contains individual operating
parameters for each farm. The outer key is farm number as a string, and the inner is string descriptors of each parameter.
frac: A float representing the fraction of the fish that remains after
processing.
mort: A float referring to the daily mortality rate of fishes on an
aquaculture farm.
cycle_history: Farm->List of Type (day of outplanting,
day of harvest, fish weight (grams))
Returns a tuple (curr_cycle_totals,indiv_tpw_totals) where:
curr_cycle_totals_: dictionary which will hold a mapping from every
farm (as identified by farm_ID) to the total processed weight of each farm
indiv_tpw_totals: dictionary which will hold a farm->list mapping,
where the list holds the individual tpw for all cycles that the farm completed
invest_natcap.finfish_aquaculture.finfish_aquaculture_core.compute_uncertainty_data(args, output_dir)

Does uncertainty analysis via a Monte Carlo simulation.

Returns a tuple with two 2D dicts. -a dict containing relative file paths to produced histograms -a dict containining statistical results (mean and std deviation) Each dict has farm IDs as outer keys, and result types (e.g. ‘value’, ‘weight’, and ‘cycles’) as inner keys.

invest_natcap.finfish_aquaculture.finfish_aquaculture_core.create_HTML_table(output_dir, args, cycle_history, sum_hrv_weight, hrv_weight, farms_npv, value_history, histogram_paths, uncertainty_stats)
Inputs:
output_dir: The directory in which we will be creating our .html file
output.
cycle_history: dictionary mapping farm ID->list of tuples, each of
which contains 3 things- (day of outplanting, day of harvest,
harvest weight of a single fish in grams)
sum_hrv_weight: dictionary which holds a mapping from farm ID->total
processed weight of each farm
hrv_weight: dictionary which holds a farm->list mapping, where the list
holds the individual tpw for all cycles that the farm completed
do_valuation: boolean variable that says whether or not valuation is
desired
farms_npv: dictionary with a farm-> float mapping, where each float is
the net processed value of the fish processed on that farm, in $1000s of dollars.
value_history: dictionary which holds a farm->list mapping, where the
list holds tuples containing (Net Revenue, Net Present Value) for each cycle completed by that farm
Output:
HTML file: contains 3 tables that summarize inputs and outputs for the

duration of the model. - Input Table: Farm Operations provided data, including Farm ID #,

Cycle Number, weight of fish at start, weight of fish at harvest, number of fish in farm, start day for growing, and length of fallowing period
  • Output Table 1: Farm Harvesting data, including a summary table

    for each harvest cycle of each farm. Will show Farm ID, cycle number, days since outplanting date, harvested weight, net revenue, outplant day, and year.

  • Output Table 2: Model outputs for each farm, including Farm ID,

    net present value, number of completed harvest cycles, and total volume harvested.

Returns nothing.

invest_natcap.finfish_aquaculture.finfish_aquaculture_core.do_monte_carlo_simulation(args)

Performs a Monte Carlo simulation and returns the results.

invest_natcap.finfish_aquaculture.finfish_aquaculture_core.execute(args)

‘ Runs the biophysical and valuation parts of the finfish aquaculture model. This will output: 1. a shape file showing farm locations w/ addition of # of harvest cycles,

total processed weight at that farm, and if valuation is true, total discounted net revenue at each farm location.
  1. Three HTML tables summarizing all model I/O- summary of user-provided

    data, summary of each harvest cycle, and summary of the outputs/farm

  2. A .txt file that is named according to the date and time the model is

    run, which lists the values used during that run

Data in args should include the following: –Biophysical Arguments– args: a python dictionary containing the following data: args[‘workspace_dir’]- The directory in which to place all result files. args[‘ff_farm_file’]- An open shape file containing the locations of

individual fisheries
args[‘farm_ID’]- column heading used to describe individual farms. Used to
link GIS location data to later inputs.
args[‘g_param_a’]- Growth parameter alpha, used in modeling fish growth,
should be int or a float.
args[‘g_param_b’]- Growth parameter beta, used in modeling fish growth,
should be int or a float.
args[‘water_temp_dict’]- A dictionary which links a specific date to the

farm numbers, and their temperature values on that day. (Note: in this case, the outer keys 1 and 2 are calendar days out of 365, starting with January 1 (day 0), and the inner 1, 2, and 3 are farm numbers.)

Format: {‘0’: ‘{‘1’: ‘8.447, ‘2’: ‘8.447’, ‘3’:‘8.947’, ...}’ ,
‘1’: ‘{‘1’: ‘8.406, ‘2’: ‘8.406’, ‘3’:‘8.906’, ...}’ ,

. . . . . . . . . }

args[‘farm_op_dict’]- Dictionary which links a specific farm ID # to

another dictionary containing operating parameters mapped to their value for that particular farm (Note: in this case, the 1 and 2 are farm ID’s, not dates out of 365.)

Format: {‘1’: ‘{‘Wt of Fish’: ‘0.06’, ‘Tar Weight’: ‘5.4’, ...}’,
‘2’: ‘{‘Wt of Fish’: ‘0.06’, ‘Tar Weight’: ‘5.4’, ...}’, . . . . . . . . . }
args[‘frac_post_process’]- the fraction of edible fish left after
processing is done to remove undesirable parts
args[‘mort_rate_daily’]- mortality rate among fish in a year, divided by
365

args[‘duration’]- duration of the simulation, in years args[‘outplant_buffer’] - This value will allow the outplant start day to

be flexible plus or minus the number of days specified here.

–Valuation arguments– args[‘do_valuation’]- boolean indicating whether or not to run the

valuation process

args[‘p_per_kg’]: Market price per kilogram of processed fish args[‘frac_p’]: Fraction of market price that accounts for costs rather

than profit

args[‘discount’]: Daily market discount rate

returns nothing

invest_natcap.finfish_aquaculture.finfish_aquaculture_core.make_histograms(farm, results, output_dir, total_num_runs)

Makes a histogram for the given farm and data.

Returns a dict mapping type (e.g. ‘value’, ‘weight’) to the relative file path for the respective histogram.

invest_natcap.finfish_aquaculture.finfish_aquaculture_core.valuation(price_per_kg, frac_mrkt_price, discount, hrv_weight, cycle_history)

This performs the valuation calculations, and returns tuple containing a dictionary with a farm-> float mapping, where each float is the net processed value of the fish processed on that farm, in $1000s of dollars, and a dictionary containing a farm-> list mapping, where each entry in the list is a tuple of (Net Revenue, Net Present Value) for every cycle on that farm.

Inputs:
price_per_kg: Float representing the price per kilogram of finfish for
valuation purposes.
frac_mrkt_price: Float that represents the fraction of market price
that is attributable to costs.

discount: Float that is the daily market discount rate. cycle_hisory: Farm->List of Type (day of outplanting,

day of harvest, fish weight (grams))

hrv_weight: Farm->List of TPW for each cycle (kilograms)

Returns a tuple (val_history, valuations):
val_history: dictionary which will hold a farm->list mapping, where the
list holds tuples containing (Net Revenue, Net Present Value) for each cycle completed by that farm
valuations: dictionary with a farm-> float mapping, where each float is
the net processed value of the fish processed on that farm

Module contents