natcap.invest.habitat_risk_assessment package

Submodules

natcap.invest.habitat_risk_assessment.hra module

This will be the preperatory module for HRA. It will take all unprocessed and pre-processed data from the UI and pass it to the hra_core module.

exception natcap.invest.habitat_risk_assessment.hra.DQWeightNotFound

Bases: exceptions.Exception

An exception to be passed if there is a shapefile within the spatial criteria directory, but no corresponing data quality and weight to support it. This would likely indicate that the user is try to run HRA without having added the criteria name into hra_preprocessor properly.

exception natcap.invest.habitat_risk_assessment.hra.ImproperAOIAttributeName

Bases: exceptions.Exception

An exception to pass in hra non core if the AOIzone files do not contain the proper attribute name for individual indentification. The attribute should be named ‘name’, and must exist for every shape in the AOI layer.

exception natcap.invest.habitat_risk_assessment.hra.ImproperCriteriaAttributeName

Bases: exceptions.Exception

An excepion to pass in hra non core if the criteria provided by the user for use in spatially explicit rating do not contain the proper attribute name. The attribute should be named ‘RATING’, and must exist for every shape in every layer provided.

natcap.invest.habitat_risk_assessment.hra.add_crit_rasters(dir, crit_dict, habitats, h_s_e, h_s_c, grid_size)

This will take in the dictionary of criteria shapefiles, rasterize them, and add the URI of that raster to the proper subdictionary within h/s/h-s.

Input:
dir- Directory into which the raserized criteria shapefiles should be
placed.
crit_dict- A multi-level dictionary of criteria shapefiles. The

outermost keys refer to the dictionary they belong with. The structure will be as follows:

{‘h’:
{‘HabA’:
{‘CriteriaName: “Shapefile Datasource URI”...}, ...

},

‘h_s_c’:
{(‘HabA’, ‘Stress1’):
{‘CriteriaName: “Shapefile Datasource URI”, ...}, ...

},

‘h_s_e’
{(‘HabA’, ‘Stress1’):
{‘CriteriaName: “Shapefile Datasource URI”, ...}, ...

}

}

h_s_c- A multi-level structure which holds numerical criteria

ratings, as well as weights and data qualities for criteria rasters. h-s will hold only criteria that apply to habitat and stressor overlaps. The structure’s outermost keys are tuples of (Habitat, Stressor) names. The overall structure will be as pictured:

{(Habitat A, Stressor 1):
{‘Crit_Ratings’:
{‘CritName’:
{‘Rating’: 2.0, ‘DQ’: 1.0, ‘Weight’: 1.0}

},

‘Crit_Rasters’:
{‘CritName’:
{‘Weight’: 1.0, ‘DQ’: 1.0}

},

}, ‘DS’: “HabitatStressor Raster URI”

}

habitats- Similar to the h-s dictionary, a multi-level
dictionary containing all habitat-specific criteria ratings and raster information. The outermost keys are habitat names. Within the dictionary, the habitats[‘habName’][‘DS’] will be the URI of the raster of that habitat.
h_s_e- Similar to the h-s dictionary, a multi-level dictionary
containing all stressor-specific criteria ratings and raster information. The outermost keys are tuples of (Habitat, Stressor) names.
grid_size- An int representing the desired pixel size for the criteria
rasters.
Output:
A set of rasterized criteria files. The criteria shapefiles will be
burned based on their ‘Rating’ attribute. These will be placed in the ‘dir’ folder.

An appended version of habitats, h_s_e, and h_s_c which will include entries for criteria rasters at ‘Rating’ in the appropriate dictionary. ‘Rating’ will map to the URI of the corresponding criteria dataset.

Returns nothing.

natcap.invest.habitat_risk_assessment.hra.add_hab_rasters(dir, habitats, hab_list, grid_size, grid_path)

Want to get all shapefiles within any directories in hab_list, and burn them to a raster.

Input:
dir- Directory into which all completed habitat rasters should be
placed.
habitats- A multi-level dictionary containing all habitat and
species-specific criteria ratings and rasters.
hab_list- File URI’s for all shapefile in habitats dir, species dir, or
both.
grid_size- Int representing the desired pixel dimensions of
both intermediate and ouput rasters.
grid_path- A string for a raster file path on disk. Used as a
universal base raster to create other rasters which to burn vectors onto.
Output:
A modified version of habitats, into which we have placed the URI to
the rasterized version of the habitat shapefile. It will be placed at habitats[habitatName][‘DS’].
natcap.invest.habitat_risk_assessment.hra.calc_max_rating(risk_eq, max_rating)

Should take in the max possible risk, and return the highest possible per pixel risk that would be seen on a H-S raster pixel.

Input:

risk_eq- The equation that will be used to determine risk. max_rating- The highest possible value that could be given as a

criteria rating, data quality, or weight.
Returns:An int representing the highest possible risk value for any given h-s overlap raster.
natcap.invest.habitat_risk_assessment.hra.execute(args)

Habitat Risk Assessment.

This function will prepare files passed from the UI to be sent on to the hra_core module.

All inputs are required.

Parameters:
  • workspace_dir (string) – The location of the directory into which intermediate and output files should be placed.
  • csv_uri (string) – The location of the directory containing the CSV files of habitat, stressor, and overlap ratings. Will also contain a .txt JSON file that has directory locations (potentially) for habitats, species, stressors, and criteria.
  • grid_size (int) – Represents the desired pixel dimensions of both intermediate and ouput rasters.
  • risk_eq (string) – A string identifying the equation that should be used in calculating risk scores for each H-S overlap cell. This will be either ‘Euclidean’ or ‘Multiplicative’.
  • decay_eq (string) – A string identifying the equation that should be used in calculating the decay of stressor buffer influence. This can be ‘None’, ‘Linear’, or ‘Exponential’.
  • max_rating (int) – An int representing the highest potential value that should be represented in rating, data quality, or weight in the CSV table.
  • max_stress (int) – This is the highest score that is used to rate a criteria within this model run. These values would be placed within the Rating column of the habitat, species, and stressor CSVs.
  • aoi_tables (string) – A shapefile containing one or more planning regions for a given model. This will be used to get the average risk value over a larger area. Each potential region MUST contain the attribute “name” as a way of identifying each individual shape.

Example Args Dictionary:

{
    'workspace_dir': 'path/to/workspace_dir',
    'csv_uri': 'path/to/csv',
    'grid_size': 200,
    'risk_eq': 'Euclidean',
    'decay_eq': 'None',
    'max_rating': 3,
    'max_stress': 4,
    'aoi_tables': 'path/to/shapefile',
}
Returns:None
natcap.invest.habitat_risk_assessment.hra.listdir(path)

A replacement for the standar os.listdir which, instead of returning only the filename, will include the entire path. This will use os as a base, then just lambda transform the whole list.

Input:
path- The location container from which we want to gather all files.
Returns:A list of full URIs contained within ‘path’.
natcap.invest.habitat_risk_assessment.hra.make_add_overlap_rasters(dir, habitats, stress_dict, h_s_c, h_s_e, grid_size)

For every pair in h_s_c and h_s_e, want to get the corresponding habitat and stressor raster, and return the overlap of the two. Should add that as the ‘DS’ entry within each (h, s) pair key in h_s_e and h_s_c.

Input:
dir- Directory into which all completed h-s overlap files shoudl be
placed.
habitats- The habitats criteria dictionary, which will contain a

dict[Habitat][‘DS’]. The structure will be as follows:

{Habitat A:
{‘Crit_Ratings’:
{‘CritName’:
{‘Rating’: 2.0, ‘DQ’: 1.0, ‘Weight’: 1.0}

},

‘Crit_Rasters’:
{‘CritName’:
{
‘DS’: “CritName Raster URI”, ‘Weight’: 1.0, ‘DQ’: 1.0

}

},

‘DS’: “A Dataset URI” }

}

stress_dict- A dictionary containing all stressor DS’s. The key will be
the name of the stressor, and it will map to the URI of the stressor DS.
h_s_c- A multi-level structure which holds numerical criteria

ratings, as well as weights and data qualities for criteria rasters. h-s will hold criteria that apply to habitat and stressor overlaps, and be applied to the consequence score. The structure’s outermost keys are tuples of (Habitat, Stressor) names. The overall structure will be as pictured:

{(Habitat A, Stressor 1):
{‘Crit_Ratings’:
{‘CritName’:
{‘Rating’: 2.0, ‘DQ’: 1.0, ‘Weight’: 1.0}

},

‘Crit_Rasters’:
{‘CritName’:
{‘Weight’: 1.0, ‘DQ’: 1.0}

},

}

}

h_s_e- Similar to the h_s dictionary, a multi-level
dictionary containing habitat-stressor-specific criteria ratings and raster information which should be applied to the exposure score. The outermost keys are tuples of (Habitat, Stressor) names.
grid_size- The desired pixel size for the rasters that will be created
for each habitat and stressor.
Output:
An edited versions of h_s_e and h_s_c, each of which contains an overlap DS at dict[(Hab, Stress)][‘DS’]. That key will map to the URI for the corresponding raster DS.

Returns nothing.

natcap.invest.habitat_risk_assessment.hra.make_exp_decay_array(dist_trans_uri, out_uri, buff, nodata)

Should create a raster where the area around the land is a function of exponential decay from the land values.

Input:
dist_trans_uri- uri to a gdal raster where each pixel value represents
the distance to the closest piece of land.

out_uri- uri for the gdal raster output with the buffered outputs buff- The distance surrounding the land that the user desires to buffer

with exponentially decaying values.
nodata- The value which should be placed into anything not land or
buffer area.

Returns: Nothing

natcap.invest.habitat_risk_assessment.hra.make_lin_decay_array(dist_trans_uri, out_uri, buff, nodata)

Should create a raster where the area around land is a function of linear decay from the values representing the land.

Input:
dist_trans_uri- uri to a gdal raster where each pixel value represents
the distance to the closest piece of land.

out_uri- uri for the gdal raster output with the buffered outputs buff- The distance surrounding the land that the user desires to buffer

with linearly decaying values.
nodata- The value which should be placed into anything not land or
buffer area.

Returns: Nothing

natcap.invest.habitat_risk_assessment.hra.make_no_decay_array(dist_trans_uri, out_uri, buff, nodata)

Should create a raster where the buffer zone surrounding the land is buffered with the same values as the land, essentially creating an equally weighted larger landmass.

Input:
dist_trans_uri- uri to a gdal raster where each pixel value represents
the distance to the closest piece of land.

out_uri- uri for the gdal raster output with the buffered outputs buff- The distance surrounding the land that the user desires to buffer

with land data values.
nodata- The value which should be placed into anything not land or
buffer area.

Returns: Nothing

natcap.invest.habitat_risk_assessment.hra.make_stress_rasters(dir, stress_list, grid_size, decay_eq, buffer_dict, grid_path)

Creating a simple dictionary that will map stressor name to a rasterized version of that stressor shapefile. The key will be a string containing stressor name, and the value will be the URI of the rasterized shapefile.

Input:

dir- The directory into which completed shapefiles should be placed. stress_list- A list containing stressor shapefile URIs for all

stressors desired within the given model run.
grid_size- The pixel size desired for the rasters produced based on the
shapefiles.
decay_eq- A string identifying the equation that should be used
in calculating the decay of stressor buffer influence.
buffer_dict- A dictionary that holds desired buffer sizes for each
stressors. The key is the name of the stressor, and the value is an int which correlates to desired buffer size.
grid_path- A string for a raster file path on disk. Used as a
universal base raster to create other rasters which to burn vectors onto.
Output:
A potentially buffered and rasterized version of each stressor
shapefile provided, which will be stored in ‘dir’.
Returns:stress_dict- A simple dictionary which maps a string key of the stressor name to the URI for the output raster.
natcap.invest.habitat_risk_assessment.hra.make_zero_buff_decay_array(dist_trans_uri, out_uri, nodata)

Creates a raster in the case of a zero buffer width, where we should have is land and nodata values.

Input:
dist_trans_uri- uri to a gdal raster where each pixel value represents
the distance to the closest piece of land.

out_uri- uri for the gdal raster output with the buffered outputs nodata- The value which should be placed into anything that is not

land.

Returns: Nothing

natcap.invest.habitat_risk_assessment.hra.merge_bounding_boxes(bb1, bb2, mode)

Merge two bounding boxes through union or intersection.

Parameters:
  • bb1 (list) – [upper_left_x, upper_left_y, lower_right_x, lower_right_y]
  • bb2 (list) – [upper_left_x, upper_left_y, lower_right_x, lower_right_y]
  • mode (string) –
Returns:

A list of the merged bounding boxes.

natcap.invest.habitat_risk_assessment.hra.unpack_over_dict(csv_uri, args)

This throws the dictionary coming from the pre-processor into the equivalent dictionaries in args so that they can be processed before being passed into the core module.

Input:
csv_uri- Reference to the folder location of the CSV tables containing
all habitat and stressor rating information.
args- The dictionary into which the individual ratings dictionaries
should be placed.
Output:

A modified args dictionary containing dictionary versions of the CSV tables located in csv_uri. The dictionaries should be of the forms as follows.

h_s_c- A multi-level structure which will hold all criteria ratings,

both numerical and raster that apply to habitat and stressor overlaps. The structure, whose keys are tuples of (Habitat, Stressor) names and map to an inner dictionary will have 2 outer keys containing numeric-only criteria, and raster-based criteria. At this time, we should only have two entries in a criteria raster entry, since we have yet to add the rasterized versions of the criteria.

{(Habitat A, Stressor 1):
{‘Crit_Ratings’:
{‘CritName’:
{‘Rating’: 2.0, ‘DQ’: 1.0, ‘Weight’: 1.0}

},

‘Crit_Rasters’:
{‘CritName’:
{‘Weight’: 1.0, ‘DQ’: 1.0}

},

}

}

habitats- Similar to the h-s dictionary, a multi-level
dictionary containing all habitat-specific criteria ratings and weights and data quality for the rasters.
h_s_e- Similar to the h-s dictionary, a multi-level dictionary
containing habitat stressor-specific criteria ratings and weights and data quality for the rasters.

Returns nothing.

natcap.invest.habitat_risk_assessment.hra_core module

InVEST HRA model.

natcap.invest.habitat_risk_assessment.hra_core.aggregate_multi_rasters_uri(aoi_rast_uri, rast_uris, rast_labels, ignore_value_list)

Will take a stack of rasters and an AOI, and return a dictionary containing the number of overlap pixels, and the value of those pixels for each overlap of raster and AOI.

Input:
aoi_uri- The location of an AOI raster which MUST have individual ID
numbers with the attribute name ‘BURN_ID’ for each feature on the map.
rast_uris- List of locations of the rasters which should be overlapped
with the AOI.
rast_labels- Names for each raster layer that will be retrievable from
the output dictionary.
ignore_value_list- Optional argument that provides a list of values
which should be ignored if they crop up for a pixel value of one of the layers.
Returns:layer_overlap_info- {AOI Data Value 1:
{rast_label: [#of pix, pix value], rast_label: [200, 2567.97], ...

}

natcap.invest.habitat_risk_assessment.hra_core.calc_C_raster(out_uri, h_s_list, h_s_denom_dict, h_list, h_denom_dict, h_uri, h_s_uri)

Should return a raster burned with a ‘C’ raster that is a combination of all the rasters passed in within the list, divided by the denominator.

Input:
out_uri- The location to which the calculated C raster should be
bGurned.
h_s_list- A list of rasters burned with the equation r/dq*w for every
criteria applicable for that h, s pair.
h_s_denom_dict- A dictionary containing criteria names applicable to
this particular h,s pair. Each criteria string name maps to a double representing the denominator for that raster, using the equation 1/dq*w.
h_list- A list of rasters burned with the equation r/dq*w for every
criteria applicable for that s.
h_denom_dict- A dictionary containing criteria names applicable to this
particular habitat. Each criteria string name maps to a double representing the denominator for that raster, using the equation 1/dq*w.

Returns nothing.

natcap.invest.habitat_risk_assessment.hra_core.calc_E_raster(out_uri, h_s_list, denom_dict, h_s_base_uri, h_base_uri)

Should return a raster burned with an ‘E’ raster that is a combination of all the rasters passed in within the list, divided by the denominator.

Input:

out_uri- The location to which the E raster should be burned. h_s_list- A list of rasters burned with the equation r/dq*w for every

criteria applicable for that h, s pair.
denom_dict- A double representing the sum total of all applicable
criteria using the equation 1/dq*w. criteria applicable for that s.

Returns nothing.

natcap.invest.habitat_risk_assessment.hra_core.copy_raster(in_uri, out_uri)

Quick function that will copy the raster in in_raster, and put it into out_raster.

natcap.invest.habitat_risk_assessment.hra_core.execute(args)

This provides the main calculation functionaility of the HRA model. This will call all parts necessary for calculation of final outputs.

Inputs:
args- Dictionary containing everything that hra_core will need to
complete the rest of the model run. It will contain the following.
args[‘workspace_dir’]- Directory in which all data resides. Output
and intermediate folders will be subfolders of this one.
args[‘h_s_c’]- The same as intermediate/’h-s’, but with the addition

of a 3rd key ‘DS’ to the outer dictionary layer. This will map to a dataset URI that shows the potentially buffered overlap between the habitat and stressor. Additionally, any raster criteria will be placed in their criteria name subdictionary. The overall structure will be as pictured:

{(Habitat A, Stressor 1):
{‘Crit_Ratings’:
{‘CritName’:
{‘Rating’: 2.0, ‘DQ’: 1.0, ‘Weight’: 1.0}

},

‘Crit_Rasters’:
{‘CritName’:
{
‘DS’: “CritName Raster URI”, ‘Weight’: 1.0, ‘DQ’: 1.0

}

},

‘DS’: “A-1 Dataset URI” }

}

args[‘habitats’]- Similar to the h-s dictionary, a multi-level
dictionary containing all habitat-specific criteria ratings and rasters. In this case, however, the outermost key is by habitat name, and habitats[‘habitatName’][‘DS’] points to the rasterized habitat shapefile URI provided by the user.
args[‘h_s_e’]- Similar to the h_s_c dictionary, a multi-level
dictionary containing habitat-stressor-specific criteria ratings and shapes. The same as intermediate/’h-s’, but with the addition of a 3rd key ‘DS’ to the outer dictionary layer. This will map to a dataset URI that shows the potentially buffered overlap between the habitat and stressor. Additionally, any raster criteria will be placed in their criteria name subdictionary.
args[‘risk_eq’]- String which identifies the equation to be used
for calculating risk. The core module should check for possibilities, and send to a different function when deciding R dependent on this.
args[‘max_risk’]- The highest possible risk value for any given pairing
of habitat and stressor.
args[‘max_stress’]- The largest number of stressors that the user
believes will overlap. This will be used to get an accurate estimate of risk.
args[‘aoi_tables’]- May or may not exist within this model run, but if
it does, the user desires to have the average risk values by stressor/habitat using E/C axes for each feature in the AOI layer specified by ‘aoi_tables’. If the risk_eq is ‘Euclidean’, this will create risk plots, otherwise it will just create the standard HTML table for either ‘Euclidean’ or ‘Multiplicative.’
args[‘aoi_key’]- The form of the word ‘Name’ that the aoi layer uses
for this particular model run.
args[‘warnings’]- A dictionary containing items which need to be

acted upon by hra_core. These will be split into two categories. ‘print’ contains statements which will be printed using logger.warn() at the end of a run. ‘unbuff’ is for pairs which should use the unbuffered stressor file in lieu of the decayed rated raster.

{‘print’: [‘This is a warning to the user.’, ‘This is another.’],
‘unbuff’: [(HabA, Stress1), (HabC, Stress2)]

}

Outputs:
--Intermediate--
 These should be the temp risk and criteria files needed for the final output calcs.
--Output--
/output/maps/recov_potent_H[habitatname].tif- Raster layer
depicting the recovery potential of each individual habitat.
/output/maps/cum_risk_H[habitatname]- Raster layer depicting the
cumulative risk for all stressors in a cell for the given habitat.
/output/maps/ecosys_risk- Raster layer that depicts the sum of all
cumulative risk scores of all habitats for that cell.
/output/maps/[habitatname]_HIGH_RISK- A raster-shaped shapefile
containing only the “high risk” areas of each habitat, defined as being above a certain risk threshold.

Returns nothing.

natcap.invest.habitat_risk_assessment.hra_core.make_aoi_tables(out_dir, aoi_pairs)

This function will take in an shapefile containing multiple AOIs, and output a table containing values averaged over those areas.

Input:
out_dir- The directory into which the completed HTML tables should be
placed.
aoi_pairs- Replacement for avgs_dict, holds all the averaged values on

a H, S basis.

{‘AOIName’:

}

Output:
A set of HTML tables which will contain averaged values of E, C, and risk for each H, S pair within each AOI. Additionally, the tables will contain a column for risk %, which is the averaged risk value in that area divided by the total potential risk for a given pixel in the map.

Returns nothing.

natcap.invest.habitat_risk_assessment.hra_core.make_ecosys_risk_raster(dir, h_dict)

This will make the compiled raster for all habitats within the ecosystem. The ecosystem raster will be a direct sum of each of the included habitat rasters.

Input:

dir- The directory in which all completed should be placed. h_dict- A dictionary of raster dataset URIs which can be combined to

create an overall ecosystem raster. The key is the habitat name, and the value is the dataset URI.

{‘Habitat A’: “Overall Habitat A Risk Map URI”, ‘Habitat B’: “Overall Habitat B Risk URI”

...

}

Output:
ecosys_risk.tif- An overall risk raster for the ecosystem. It will
be placed in the dir folder.

Returns nothing.

natcap.invest.habitat_risk_assessment.hra_core.make_hab_risk_raster(dir, risk_dict)

This will create a combined raster for all habitat-stressor pairings within one habitat. It should return a list of open rasters that correspond to all habitats within the model.

Input:
dir- The directory in which all completed habitat rasters should be
placed.
risk_dict- A dictionary containing the risk rasters for each pairing of

habitat and stressor. The key is the tuple of (habitat, stressor), and the value is the raster dataset URI corresponding to that combination.

{(‘HabA’, ‘Stress1’): “A-1 Risk Raster URI”, (‘HabA’, ‘Stress2’): “A-2 Risk Raster URI”, ... }

Output:
A cumulative risk raster for every habitat included within the model.
Returns:
h_rasters- A dictionary containing habitat names mapped to the dataset
URI of the overarching habitat risk map for this model run.

{‘Habitat A’: “Overall Habitat A Risk Map URI”, ‘Habitat B’: “Overall Habitat B Risk URI”

...

}

h_s_rasters- A dictionary that maps a habitat name to the risk rasters
for each of the applicable stressors.
{‘HabA’: [“A-1 Risk Raster URI”, “A-2 Risk Raster URI”, ...],
‘HabB’: [“B-1 Risk Raster URI”, “B-2 Risk Raster URI”, ...], ...

}

natcap.invest.habitat_risk_assessment.hra_core.make_recov_potent_raster(dir, crit_lists, denoms)

This will do the same h-s calculation as used for the individual E/C calculations, but instead will use r/dq as the equation for each criteria. The full equation will be:

SUM HAB CRITS( 1/dq )
Input:

dir- Directory in which the completed raster files should be placed. crit_lists- A dictionary containing pre-burned criteria which can be

combined to get the E/C for that H-S pairing.

{‘Risk’: {
‘h_s_c’: {
(hab1, stressA):
[“indiv num raster URI”,
“raster 1 URI”, ...],

(hab1, stressB): ...

},

‘h’: {
hab1: [“indiv num raster URI”, “raster 1 URI”],
...

},

‘h_s_e’: { (hab1, stressA): [“indiv num raster URI”]
}

}

‘Recovery’: { hab1: [“indiv num raster URI”, ...],
hab2: ...

}

}

denoms- Dictionary containing the combined denominator for a given

H-S overlap. Once all of the rasters are combined, each H-S raster can be divided by this.

{‘Risk’: {
‘h_s_c’: {
(hab1, stressA): {
‘CritName’: 2.0, ...},
(hab1, stressB): {‘CritName’: 1.3, ...}
},
‘h’: { hab1: {‘CritName’: 1.3, ...},
...

},

‘h_s_e’: { (hab1, stressA): {‘CritName’: 1.3, ...}
}

}

‘Recovery’: { hab1: {‘critname’: 1.6, ...}
hab2: ...

}

}

Output:
A raster file for each of the habitats included in the model displaying
the recovery potential within each potential grid cell.

Returns nothing.

natcap.invest.habitat_risk_assessment.hra_core.make_risk_euc(base_uri, e_uri, c_uri, risk_uri)

Combines the E and C rasters according to the euclidean combination equation.

Input:
base- The h-s overlap raster, including potentially decayed values from
the stressor layer.
e_rast- The r/dq*w burned raster for all stressor-specific criteria
in this model run.
c_rast- The r/dq*w burned raster for all habitat-specific and
habitat-stressor-specific criteria in this model run.

risk_uri- The file path to which we should be burning our new raster.

Returns a raster representing the euclidean calculated E raster, C raster, and the base raster. The equation will be sqrt((C-1)^2 + (E-1)^2)

natcap.invest.habitat_risk_assessment.hra_core.make_risk_mult(base_uri, e_uri, c_uri, risk_uri)

Combines the E and C rasters according to the multiplicative combination equation.

Input:
base- The h-s overlap raster, including potentially decayed values from
the stressor layer.
e_rast- The r/dq*w burned raster for all stressor-specific criteria
in this model run.
c_rast- The r/dq*w burned raster for all habitat-specific and
habitat-stressor-specific criteria in this model run.

risk_uri- The file path to which we should be burning our new raster.

Returns the URI for a raster representing the multiplied E raster,
C raster, and the base raster.
natcap.invest.habitat_risk_assessment.hra_core.make_risk_plots(out_dir, aoi_pairs, max_risk, max_stress, num_stress, num_habs)

This function will produce risk plots when the risk equation is euclidean.

Parameters:
  • out_dir (string) – The directory into which the completed risk plots should be placed.
  • aoi_pairs (dictionary) –
    {‘AOIName’:

    }

  • max_risk (float) – Double representing the highest potential value for a single h-s raster. The amount of risk for a given Habitat raster would be SUM(s) for a given h.
  • max_stress (float) – The largest number of stressors that the user believes will overlap. This will be used to get an accurate estimate of risk.
  • num_stress (dict) – A dictionary that simply associates every habaitat with the number of stressors associated with it. This will help us determine the max E/C we should be expecting in our overarching ecosystem plot.
Returns:

None

Outputs:

A set of .png images containing the matplotlib plots for every H-S combination. Within that, each AOI will be displayed as plotted by (E,C) values.

A single png that is the “ecosystem plot” where the E’s for each AOI are the summed

natcap.invest.habitat_risk_assessment.hra_core.make_risk_rasters(h_s_c, habs, inter_dir, crit_lists, denoms, risk_eq, warnings)

This will combine all of the intermediate criteria rasters that we pre-processed with their r/dq*w. At this juncture, we should be able to straight add the E/C within themselves. The way in which the E/C rasters are combined depends on the risk equation desired.

Input:
h_s_c- Args dictionary containing much of the H-S overlap data in
addition to the H-S base rasters. (In this function, we are only using it for the base h-s raster information.)
habs- Args dictionary containing habitat criteria information in
addition to the habitat base rasters. (In this function, we are only using it for the base raster information.)
inter_dir- Intermediate directory in which the H_S risk-burned rasters
can be placed.
crit_lists- A dictionary containing pre-burned criteria which can be

combined to get the E/C for that H-S pairing.

{‘Risk’: {
‘h_s_c’: {
(hab1, stressA): [“indiv num raster URI”,
“raster 1 URI”, ...],

(hab1, stressB): ...

},

‘h’: {
hab1: [“indiv num raster URI”,
“raster 1 URI”, ...],

...

},

‘h_s_e’: { (hab1, stressA): [“indiv num raster URI”,
...]

}

}

‘Recovery’: { hab1: [“indiv num raster URI”, ...],
hab2: ...

}

}

denoms- Dictionary containing the denomincator scores for each overlap

for each criteria. These can be combined to get the final denom by which the rasters should be divided.

{‘Risk’: { ‘h_s_c’: { (hab1, stressA): {‘CritName’: 2.0,...},
(hab1, stressB): {CritName’: 1.3, ...}

},

‘h’: { hab1: {‘CritName’: 2.5, ...},
...

},

‘h_s_e’: { (hab1, stressA): {‘CritName’: 2.3},
}

}

‘Recovery’: { hab1: {‘CritName’: 3.4},
hab2: ...

}

}

risk_eq- A string description of the desired equation to use when
preforming risk calculation.
warnings- A dictionary containing items which need to be acted upon by

hra_core. These will be split into two categories. ‘print’ contains statements which will be printed using logger.warn() at the end of a run. ‘unbuff’ is for pairs which should use the unbuffered stressor file in lieu of the decayed rated raster.

{‘print’: [‘This is a warning to the user.’, ‘This is another.’],
‘unbuff’: [(HabA, Stress1), (HabC, Stress2)]

}

Output:
A new raster file for each overlapping of habitat and stressor. This file will be the overall risk for that pairing from all H/S/H-S subdictionaries.
Returns:risk_rasters- A simple dictionary that maps a tuple of (Habitat, Stressor) to the URI for the risk raster created when the various sub components (H/S/H_S) are combined.

{(‘HabA’, ‘Stress1’): “A-1 Risk Raster URI”, (‘HabA’, ‘Stress2’): “A-2 Risk Raster URI”, ... }

natcap.invest.habitat_risk_assessment.hra_core.make_risk_shapes(dir, crit_lists, h_dict, h_s_dict, max_risk, max_stress)

This function will take in the current rasterized risk files for each habitat, and output a shapefile where the areas that are “HIGH RISK” (high percentage of risk over potential risk) are the only existing polygonized areas.

Additonally, we also want to create a shapefile which is only the “low risk” areas- actually, those that are just not high risk (it’s the combination of low risk areas and medium risk areas).

Since the pygeoprocessing.geoprocessing function can only take in ints, want to predetermine

what areas are or are not going to be shapefile, and pass in a raster that is only 1 or nodata.

Input:

dir- Directory in which the completed shapefiles should be placed. crit_lists- A dictionary containing pre-burned criteria which can be

combined to get the E/C for that H-S pairing.

{‘Risk’: {
‘h_s_c’: { (hab1, stressA): [“indiv num raster URI”,
“raster 1 URI”, ...],

(hab1, stressB): ...

},

‘h’: {
hab1: [“indiv num raster URI”, “raster 1 URI”],
...

},

‘h_s_e’: {(hab1, stressA): [“indiv num raster URI”]
}

}

‘Recovery’: { hab1: [“indiv num raster URI”, ...],
hab2: ...

}

}

h_dict- A dictionary that contains raster dataset URIs corresponding
to each of the habitats in the model. The key in this dictionary is the name of the habiat, and it maps to the open dataset.
h_s_dict- A dictionary that maps a habitat name to the risk rasters

for each of the applicable stressors.

{‘HabA’: [“A-1 Risk Raster URI”, “A-2 Risk Raster URI”, ...],
‘HabB’: [“B-1 Risk Raster URI”, “B-2 Risk Raster URI”, ...], ...

}

max_risk- Double representing the highest potential value for a single
h-s raster. The amount of risk for a given Habitat raster would be SUM(s) for a given h.
max_stress- The largest number of stressors that the user believes will
overlap. This will be used to get an accurate estimate of risk.
Output:
Returns two shapefiles for every habitat, one which shows features only for the areas that are “high risk” within that habitat, and one which shows features only for the combined low + medium risk areas.
Return:
num_stress- A dictionary containing the number of stressors being
associated with each habitat. The key is the string name of the habitat, and it maps to an int counter of number of stressors.
natcap.invest.habitat_risk_assessment.hra_core.pre_calc_avgs(inter_dir, risk_dict, aoi_uri, aoi_key, risk_eq, max_risk)

This funtion is a helper to make_aoi_tables, and will just handle pre-calculation of the average values for each aoi zone.

Input:
inter_dir- The directory which contains the individual E and C rasters.
We can use these to get the avg. E and C values per area. Since we don’t really have these in any sort of dictionary, will probably just need to explicitly call each individual file based on the names that we pull from the risk_dict keys.
risk_dict- A simple dictionary that maps a tuple of

(Habitat, Stressor) to the URI for the risk raster created when the various sub components (H/S/H_S) are combined.

{(‘HabA’, ‘Stress1’): “A-1 Risk Raster URI”, (‘HabA’, ‘Stress2’): “A-2 Risk Raster URI”, ... }

aoi_uri- The location of the AOI zone files. Each feature within this
file (identified by a ‘name’ attribute) will be used to average an area of E/C/Risk values.
risk_eq- A string identifier, either ‘Euclidean’ or ‘Multiplicative’
that tells us which equation should be used for calculation of risk. This will be used to get the risk value for the average E and C.

max_risk- The user reported highest risk score present in the CSVs.

Returns:
avgs_dict- A multi level dictionary to hold the average values that
will be placed into the HTML table.
{‘HabitatName’:
{‘StressorName’:
[{‘Name’: AOIName, ‘E’: 4.6, ‘C’: 2.8, ‘Risk’: 4.2},
{...},

... ]

}

aoi_names- Quick and dirty way of getting the AOI keys.

natcap.invest.habitat_risk_assessment.hra_core.pre_calc_denoms_and_criteria(dir, h_s_c, hab, h_s_e)

Want to return two dictionaries in the format of the following: (Note: the individual num raster comes from the crit_ratings subdictionary and should be pre-summed together to get the numerator for that particular raster. )

Input:
dir- Directory into which the rasterized criteria can be placed. This
will need to have a subfolder added to it specifically to hold the rasterized criteria for now.
h_s_c- A multi-level structure which holds all criteria ratings,

both numerical and raster that apply to habitat and stressor overlaps. The structure, whose keys are tuples of (Habitat, Stressor) names and map to an inner dictionary will have 3 outer keys containing numeric-only criteria, raster-based criteria, and a dataset that shows the potentially buffered overlap between the habitat and stressor. The overall structure will be as pictured:

{(Habitat A, Stressor 1):
{‘Crit_Ratings’:
{‘CritName’:
{‘Rating’: 2.0, ‘DQ’: 1.0, ‘Weight’: 1.0}

},

‘Crit_Rasters’:
{‘CritName’:
{
‘DS’: “CritName Raster URI”,
‘Weight’: 1.0, ‘DQ’: 1.0}

},

‘DS’: “A-1 Raster URI” }

}

hab- Similar to the h-s dictionary, a multi-level
dictionary containing all habitat-specific criteria ratings and rasters. In this case, however, the outermost key is by habitat name, and habitats[‘habitatName’][‘DS’] points to the rasterized habitat shapefile URI provided by the user.
h_s_e- Similar to the h_s_c dictionary, a multi-level
dictionary containing habitat-stressor-specific criteria ratings and rasters. The outermost key is by (habitat, stressor) pair, but the criteria will be applied to the exposure portion of the risk calcs.
Output:
Creates a version of every criteria for every h-s paring that is burned with both a r/dq*w value for risk calculation, as well as a r/dq burned raster for recovery potential calculations.
Returns:
crit_lists- A dictionary containing pre-burned criteria URI which can
be combined to get the E/C for that H-S pairing.
{‘Risk’: {
‘h_s_c’:
{ (hab1, stressA): [“indiv num raster”, “raster 1”, ...],
(hab1, stressB): ...

},

‘h’: {
hab1: [“indiv num raster URI”,
“raster 1 URI”, ...],

...

},

‘h_s_e’: {
(hab1, stressA):
[“indiv num raster URI”, ...]

}

}

‘Recovery’: { hab1: [“indiv num raster URI”, ...],
hab2: ...

}

}

denoms- Dictionary containing the combined denominator for a given
H-S overlap. Once all of the rasters are combined, each H-S raster can be divided by this.
{‘Risk’: {
‘h_s_c’: {
(hab1, stressA): {‘CritName’: 2.0, ...},
(hab1, stressB): {‘CritName’: 1.3, ...}

},

‘h’: { hab1: {‘CritName’: 1.3, ...},
...

},

‘h_s_e’: { (hab1, stressA): {‘CritName’: 1.3, ...}
}

}

‘Recovery’: { hab1: 1.6,
hab2: ...

}

}

natcap.invest.habitat_risk_assessment.hra_core.raster_to_polygon(raster_uri, out_uri, layer_name, field_name)

This will take in a raster file, and output a shapefile of the same area and shape.

Input:
raster_uri- The raster that needs to be turned into a shapefile. This
is only the URI to the raster, we will need to get the band.

out_uri- The desired URI for the new shapefile. layer_name- The name of the layer going into the new shapefile. field-name- The name of the field that will contain the raster pixel

value.
Output:
This will be a shapefile in the shape of the raster. The raster being passed in will be solely “high risk” areas that conatin data, and nodata values for everything else.

Returns nothing.

natcap.invest.habitat_risk_assessment.hra_core.rewrite_avgs_dict(avgs_dict, aoi_names)

Aftermarket rejigger of the avgs_dict setup so that everything is AOI centric instead. Should produce something like the following:

{‘AOIName’:

}

natcap.invest.habitat_risk_assessment.hra_preprocessor module

Entry point for the Habitat Risk Assessment module

exception natcap.invest.habitat_risk_assessment.hra_preprocessor.ImproperCriteriaSpread

Bases: exceptions.Exception

An exception for hra_preprocessor which can be passed if there are not one or more criteria in each of the 3 criteria categories: resilience, exposure, and sensitivity.

exception natcap.invest.habitat_risk_assessment.hra_preprocessor.ImproperECSelection

Bases: exceptions.Exception

An exception for hra_preprocessor that should catch selections for exposure vs consequence scoring that are not either E or C. The user must decide in this column which the criteria applies to, and my only designate this with an ‘E’ or ‘C’.

exception natcap.invest.habitat_risk_assessment.hra_preprocessor.MissingHabitatsOrSpecies

Bases: exceptions.Exception

An exception to pass if the hra_preprocessor args dictionary being passed is missing a habitats directory or a species directory.

exception natcap.invest.habitat_risk_assessment.hra_preprocessor.MissingSensOrResilException

Bases: exceptions.Exception

An exception for hra_preprocessor that catches h-s pairings who are missing either Sensitivity or Resilience or C criteria, though not both. The user must either zero all criteria for that pair, or make sure that both E and C are represented.

exception natcap.invest.habitat_risk_assessment.hra_preprocessor.NA_RatingsError

Bases: exceptions.Exception

An exception that is raised on an invalid ‘NA’ input.

When one or more Ratings value is set to “NA” for a habitat - stressor pair, but not ALL are set to “NA”. If ALL Rating values for a habitat - stressor pair are “NA”, then the habitat - stressor pair is considered to have NO interaction.

exception natcap.invest.habitat_risk_assessment.hra_preprocessor.NotEnoughCriteria

Bases: exceptions.Exception

An exception for hra_preprocessor which can be passed if the number of criteria in the resilience, exposure, and sensitivity categories all sums to less than 4.

exception natcap.invest.habitat_risk_assessment.hra_preprocessor.UnexpectedString

Bases: exceptions.Exception

An exception for hra_preprocessor that should catch any strings that are left over in the CSVs. Since everything from the CSV’s are being cast to floats, this will be a hook off of python’s ValueError, which will re-raise our exception with a more accurate message.

exception natcap.invest.habitat_risk_assessment.hra_preprocessor.ZeroDQWeightValue

Bases: exceptions.Exception

An exception specifically for the parsing of the preprocessor tables in which the model should break loudly if a user tries to enter a zero value for either a data quality or a weight. However, we should confirm that it will only break if the rating is not also zero. If they’re removing the criteria entirely from that H-S overlap, it should be allowed.

natcap.invest.habitat_risk_assessment.hra_preprocessor.error_check(line, hab_name, stress_name)

Throwing together a simple error checking function for all of the inputs coming from the CSV file. Want to do checks for strings vs floats, as well as some explicit string checking for ‘E’/’C’.

Input:
line- An array containing a line of H-S overlap data. The format of a

line would look like the following:

[‘CritName’, ‘Rating’, ‘Weight’, ‘DataQuality’, ‘Exp/Cons’]

The following restrictions should be placed on the data:

CritName- This will be propogated by default by
HRA_Preprocessor. Since it’s coming in as a string, we shouldn’t need to check anything.
Rating- Can either be the explicit string ‘SHAPE’, which would
be placed automatically by HRA_Preprocessor, or a float. ERROR: if string that isn’t ‘SHAPE’.
Weight- Must be a float (or an int), but cannot be 0.
ERROR: if string, or anything not castable to float, or 0.
DataQuality- Most be a float (or an int), but cannot be 0.
ERROR: if string, or anything not castable to float, or 0.
Exp/Cons- Most be the string ‘E’ or ‘C’.
ERROR: if string that isn’t one of the acceptable ones, or ANYTHING else.

Returns nothing, should raise exception if there’s an issue.

natcap.invest.habitat_risk_assessment.hra_preprocessor.execute(args)

Habitat Risk Assessment Preprocessor.

Want to read in multiple hab/stressors directories, in addition to named criteria, and make an appropriate csv file.

Parameters:
  • args['workspace_dir'] (string) – The directory to dump the output CSV files to. (required)
  • args['habitats_dir'] (string) – A directory of shapefiles that are habitats. This is not required, and may not exist if there is a species layer directory. (optional)
  • args['species_dir'] (string) – Directory which holds all species shapefiles, but may or may not exist if there is a habitats layer directory. (optional)
  • args['stressors_dir'] (string) – A directory of ArcGIS shapefiles that are stressors. (required)
  • args['exposure_crits'] (list) – list containing string names of exposure criteria (hab-stress) which should be applied to the exposure score. (optional)
  • args['sensitivity-crits'] (list) – List containing string names of sensitivity (habitat-stressor overlap specific) criteria which should be applied to the consequence score. (optional)
  • args['resilience_crits'] (list) – List containing string names of resilience (habitat or species-specific) criteria which should be applied to the consequence score. (optional)
  • args['criteria_dir'] (string) – Directory which holds the criteria shapefiles. May not exist if the user does not desire criteria shapefiles. This needs to be in a VERY specific format, which shall be described in the user’s guide. (optional)
Returns:

None

This function creates a series of CSVs within args['workspace_dir']. There will be one CSV for every habitat/species. These files will contain information relevant to each habitat or species, including all criteria. The criteria will be broken up into those which apply to only the habitat, and those which apply to the overlap of that habitat, and each stressor.

JSON file containing vars that need to be passed on to hra non-core when that gets run. Should live inside the preprocessor folder which will be created in args['workspace_dir']. It will contain habitats_dir, species_dir, stressors_dir, and criteria_dir.

natcap.invest.habitat_risk_assessment.hra_preprocessor.listdir(path)

A replacement for the standar os.listdir which, instead of returning only the filename, will include the entire path. This will use os as a base, then just lambda transform the whole list.

Input:
path- The location container from which we want to gather all files.
Returns:A list of full URIs contained within ‘path’.
natcap.invest.habitat_risk_assessment.hra_preprocessor.make_crit_shape_dict(crit_uri)

This will take in the location of the file structure, and will return a dictionary containing all the shapefiles that we find. Hypothetically, we should be able to parse easily through the files, since it should be EXACTLY of the specs that we laid out.

Input:
crit_uri- Location of the file structure containing all of the
shapefile criteria.
Returns:A dictionary containing shapefile URI’s, indexed by their criteria name, in addition to which dictionaries and h-s pairs they apply to. The structure will be as follows:
{‘h’:
{‘HabA’:
{‘CriteriaName: “Shapefile Datasource URI”...}, ...

},

‘h_s_c’:
{(‘HabA’, ‘Stress1’):
{‘CriteriaName: “Shapefile Datasource URI”, ...}, ...

},

‘h_s_e’
{(‘HabA’, ‘Stress1’):
{‘CriteriaName: “Shapefile Datasource URI”, ...}, ...

}

}

natcap.invest.habitat_risk_assessment.hra_preprocessor.parse_hra_tables(folder_uri)

This takes in the directory containing the criteria rating csv’s, and returns a coherent set of dictionaries that can be used to do EVERYTHING in non-core and core.

It will return a massive dictionary containing all of the subdictionaries needed by non core, as well as directory URI’s. It will be of the following form:

{‘habitats_dir’: ‘Habitat Directory URI’, ‘species_dir’: ‘Species Directory URI’, ‘stressors_dir’: ‘Stressors Directory URI’, ‘criteria_dir’: ‘Criteria Directory URI’, ‘buffer_dict’:

{‘Stressor 1’: 50, ‘Stressor 2’: ..., },
‘h_s_c’:
{(Habitat A, Stressor 1):
{‘Crit_Ratings’:
{‘CritName’:
{‘Rating’: 2.0, ‘DQ’: 1.0, ‘Weight’: 1.0}

},

‘Crit_Rasters’:
{‘CritName’:
{‘Weight’: 1.0, ‘DQ’: 1.0}

},

}

},

‘h_s_c’:
{(Habitat A, Stressor 1):
{‘Crit_Ratings’:
{‘CritName’:
{‘Rating’: 2.0, ‘DQ’: 1.0, ‘Weight’: 1.0}

},

‘Crit_Rasters’:
{‘CritName’:
{‘Weight’: 1.0, ‘DQ’: 1.0}

},

}

},

‘habitats’:
{Habitat A:
{‘Crit_Ratings’:
{‘CritName’:
{‘Rating’: 2.0, ‘DQ’: 1.0, ‘Weight’: 1.0}

},

‘Crit_Rasters’:
{‘CritName’:
{‘Weight’: 1.0, ‘DQ’: 1.0}

},

}

}

‘warnings’:
{‘print’:
[‘This is a warning to the user.’, ‘This is another.’],
‘unbuff’:
[(HabA, Stress1), (HabC, Stress2)]

}

}

natcap.invest.habitat_risk_assessment.hra_preprocessor.parse_overlaps(uri, habs, h_s_e, h_s_c)

This function will take in a location, and update the dictionaries being passed with the new Hab/Stress subdictionary info that we’re getting from the CSV at URI.

Input:
uri- The location of the CSV that we want to get ratings info from.
This will contain information for a given habitat’s individual criteria ratings, as well as criteria ratings for the overlap of every stressor.
habs- A dictionary which contains all resilience specific criteria

info. The key for these will be the habitat name. It will map to a subdictionary containing criteria information. The whole dictionary will look like the following:

{Habitat A:
{‘Crit_Ratings’:
{‘CritName’:
{‘Rating’: 2.0, ‘DQ’: 1.0, ‘Weight’: 1.0}

},

‘Crit_Rasters’:
{‘CritName’:
{‘Weight’: 1.0, ‘DQ’: 1.0}

},

}

}

h_s_e- A dictionary containing all information applicable to exposure
criteria. The dictionary will look identical to the ‘habs’ dictionary, but each key will be a tuple of two strings - (HabName, StressName).
h_s_c- A dictionary containing all information applicable to
sensitivity criteria. The dictionary will look identical to the ‘habs’ dictionary, but each key will be a tuple of two strings - (HabName, StressName).
natcap.invest.habitat_risk_assessment.hra_preprocessor.parse_stress_buffer(uri)

This will take the stressor buffer CSV and parse it into a dictionary where the stressor name maps to a float of the about by which it should be buffered.

Input:
uri- The location of the CSV file from which we should pull the buffer
amounts.
Returns:A dictionary containing stressor names mapped to their corresponding buffer amounts. The float may be 0, but may not be a string. The form will be the following:
{‘Stress 1’: 2000, ‘Stress 2’: 1500, ‘Stress 3’: 0, ...}
natcap.invest.habitat_risk_assessment.hra_preprocessor.zero_check(h_s_c, h_s_e, habs)

Any criteria that have a rating of 0 mean that they are not a desired input to the assessment. We should delete the criteria’s entire subdictionary out of the dictionary.

Input:
habs- A dictionary which contains all resilience specific criteria

info. The key for these will be the habitat name. It will map to a subdictionary containing criteria information. The whole dictionary will look like the following:

{Habitat A:
{‘Crit_Ratings’:
{‘CritName’:
{‘Rating’: 2.0, ‘DQ’: 1.0, ‘Weight’: 1.0}

},

‘Crit_Rasters’:
{‘CritName’:
{‘Weight’: 1.0, ‘DQ’: 1.0}

},

}

}

h_s_e- A dictionary containing all information applicable to exposure
criteria. The dictionary will look identical to the ‘habs’ dictionary, but each key will be a tuple of two strings - (HabName, StressName).
h_s_c- A dictionary containing all information applicable to
sensitivity criteria. The dictionary will look identical to the ‘habs’ dictionary, but each key will be a tuple of two strings - (HabName, StressName).
Output:
Will update each of the three dictionaries by deleting any criteria where the rating aspect is 0.
Returns:warnings- A dictionary containing items which need to be acted upon by hra_core. These will be split into two categories. ‘print’ contains statements which will be printed using logger.warn() at the end of a run. ‘unbuff’ is for pairs which should use the unbuffered stressor file in lieu of the decayed rated raster.
{‘print’: [‘This is a warning to the user.’, ‘This is another.’],
‘unbuff’: [(HabA, Stress1), (HabC, Stress2)]

}

Module contents