Finfish Aquaculture Package¶
Model Entry Point¶
-
natcap.invest.finfish_aquaculture.finfish_aquaculture.
execute
(args)¶ Finfish Aquaculture.
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
- use_uncertainty (boolean) –
- g_param_a_sd (float) – (description)
- g_param_b_sd (float) – (description)
- num_monte_carlo_runs (int) –
- 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
-
natcap.invest.finfish_aquaculture.finfish_aquaculture.
execute
(args) Finfish Aquaculture.
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
- use_uncertainty (boolean) –
- g_param_a_sd (float) – (description)
- g_param_b_sd (float) – (description)
- num_monte_carlo_runs (int) –
- 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, }
-
natcap.invest.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.
-
natcap.invest.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.
-
natcap.invest.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))
-
natcap.invest.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
-
natcap.invest.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.
-
natcap.invest.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.
-
natcap.invest.finfish_aquaculture.finfish_aquaculture_core.
do_monte_carlo_simulation
(args)¶ Performs a Monte Carlo simulation and returns the results.
-
natcap.invest.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.- Three HTML tables summarizing all model I/O- summary of user-provided
- data, summary of each harvest cycle, and summary of the outputs/farm
- 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 processargs[‘p_per_kg’]: Market price per kilogram of processed fish args[‘frac_p’]: Fraction of market price that accounts for costs rather
than profitargs[‘discount’]: Daily market discount rate
returns nothing
-
natcap.invest.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.
-
natcap.invest.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