Wave Energy Package¶
Model Entry Point¶
-
natcap.invest.wave_energy.wave_energy.
execute
(args)¶ Wave Energy.
Executes both the biophysical and valuation parts of the wave energy model (WEM). Files will be written on disk to the intermediate and output directories. The outputs computed for biophysical and valuation include: wave energy capacity raster, wave power raster, net present value raster, percentile rasters for the previous three, and a point shapefile of the wave points with attributes.
Parameters: - workspace_dir (string) – Where the intermediate and output folder/files will be saved. (required)
- wave_base_data_uri (string) – Directory location of wave base data including WW3 data and analysis area shapefile. (required)
- analysis_area_uri (string) – A string identifying the analysis area of interest. Used to determine wave data shapefile, wave data text file, and analysis area boundary shape. (required)
- aoi_uri (string) – A polygon shapefile outlining a more detailed area within the analysis area. This shapefile should be projected with linear units being in meters. (required to run Valuation model)
- machine_perf_uri (string) – The path of a CSV file that holds the machine performance table. (required)
- machine_param_uri (string) – The path of a CSV file that holds the machine parameter table. (required)
- dem_uri (string) – The path of the Global Digital Elevation Model (DEM). (required)
- suffix (string) – A python string of characters to append to each output filename (optional)
- valuation_container (boolean) – Indicates whether the model includes valuation
- land_gridPts_uri (string) – A CSV file path containing the Landing and Power Grid Connection Points table. (required for Valuation)
- machine_econ_uri (string) – A CSV file path for the machine economic parameters table. (required for Valuation)
- number_of_machines (int) – An integer specifying the number of machines for a wave farm site. (required for Valuation)
Example Args Dictionary:
{ 'workspace_dir': 'path/to/workspace_dir', 'wave_base_data_uri': 'path/to/base_data_dir', 'analysis_area_uri': 'West Coast of North America and Hawaii', 'aoi_uri': 'path/to/shapefile', 'machine_perf_uri': 'path/to/csv', 'machine_param_uri': 'path/to/csv', 'dem_uri': 'path/to/raster', 'suffix': '_results', 'valuation_container': True, 'land_gridPts_uri': 'path/to/csv', 'machine_econ_uri': 'path/to/csv', 'number_of_machines': 28, }
Wave Energy¶
InVEST Wave Energy Model Core Code
-
exception
natcap.invest.wave_energy.wave_energy.
IntersectionError
¶ Bases:
exceptions.Exception
A custom error message for when the AOI does not intersect any wave data points.
-
natcap.invest.wave_energy.wave_energy.
build_point_shapefile
(driver_name, layer_name, path, data, prj, coord_trans)¶ This function creates and saves a point geometry shapefile to disk. It specifically only creates one ‘Id’ field and creates as many features as specified in ‘data’
driver_name - A string specifying a valid ogr driver type layer_name - A string representing the name of the layer path - A string of the output path of the file data - A dictionary who’s keys are the Id’s for the field
and who’s values are arrays with two elements being latitude and longitudeprj - A spatial reference acting as the projection/datum coord_trans - A coordinate transformation
returns - Nothing
-
natcap.invest.wave_energy.wave_energy.
calculate_distance
(xy_1, xy_2)¶ For all points in xy_1, this function calculates the distance from point xy_1 to various points in xy_2, and stores the shortest distances found in a list min_dist. The function also stores the index from which ever point in xy_2 was closest, as an id in a list that corresponds to min_dist.
xy_1 - A numpy array of points in the form [x,y] xy_2 - A numpy array of points in the form [x,y]
- returns - A numpy array of shortest distances and a numpy array
- of id’s corresponding to the array of shortest distances
-
natcap.invest.wave_energy.wave_energy.
calculate_percentiles_from_raster
(raster_uri, percentiles)¶ Does a memory efficient sort to determine the percentiles of a raster. Percentile algorithm currently used is the nearest rank method.
raster_uri - a uri to a gdal raster on disk percentiles - a list of desired percentiles to lookup
ex: [25,50,75,90]- returns - a list of values corresponding to the percentiles
- from the percentiles list
-
natcap.invest.wave_energy.wave_energy.
captured_wave_energy_to_shape
(energy_cap, wave_shape_uri)¶ Adds each captured wave energy value from the dictionary energy_cap to a field of the shapefile wave_shape. The values are set corresponding to the same I,J values which is the key of the dictionary and used as the unique identier of the shape.
- energy_cap - A dictionary with keys (I,J), representing the
- wave energy capacity values.
- wave_shape_uri - A uri to a point geometry shapefile to
- write the new field/values to
returns - Nothing
-
natcap.invest.wave_energy.wave_energy.
clip_datasource_layer
(shape_to_clip_path, binding_shape_path, output_path)¶ Clip Shapefile Layer by second Shapefile Layer.
Uses ogr.Layer.Clip() to clip a Shapefile, where the output Layer inherits the projection and fields from the original Shapefile.
Parameters: - shape_to_clip_path (string) – a path to a Shapefile on disk. This is the Layer to clip. Must have same spatial reference as ‘binding_shape_path’.
- binding_shape_path (string) – a path to a Shapefile on disk. This is the Layer to clip to. Must have same spatial reference as ‘shape_to_clip_path’
- output_path (string) – a path on disk to write the clipped Shapefile to. Should end with a ‘.shp’ extension.
Returns: Nothing
-
natcap.invest.wave_energy.wave_energy.
compute_wave_energy_capacity
(wave_data, interp_z, machine_param)¶ - Computes the wave energy capacity for each point and
generates a dictionary whos keys are the points (I,J) and whos value is the wave energy capacity.
- wave_data - A dictionary containing wave watch data with the following
- structure:
- {‘periods’: [1,2,3,4,...],
‘heights’: [.5,1.0,1.5,...], ‘bin_matrix’: { (i0,j0): [[2,5,3,2,...], [6,3,4,1,...],...],
- (i1,j1): [[2,5,3,2,...], [6,3,4,1,...],...],
- ...
(in, jn): [[2,5,3,2,...], [6,3,4,1,...],...]
}
}
- interp_z - A 2D array of the interpolated values for the machine
- performance table
- machine_param - A dictionary containing the restrictions for the
- machines (CapMax, TpMax, HsMax)
- returns - A dictionary representing the wave energy capacity at
- each wave point
-
natcap.invest.wave_energy.wave_energy.
count_pixels_groups
(raster_uri, group_values)¶ Does a pixel count for each value in ‘group_values’ over the raster provided by ‘raster_uri’. Returns a list of pixel counts for each value in ‘group_values’
raster_uri - a uri path to a gdal raster on disk group_values - a list of unique numbers for which to get a pixel count
- returns - A list of integers, where each integer at an index
- corresponds to the pixel count of the value from ‘group_values’ found at the same index
-
natcap.invest.wave_energy.wave_energy.
create_attribute_csv_table
(attribute_table_uri, fields, data)¶ Create a new csv table from a dictionary
filename - a URI path for the new table to be written to disk
- fields - a python list of the column names. The order of the fields in
- the list will be the order in how they are written. ex: [‘id’, ‘precip’, ‘total’]
- data - a python dictionary representing the table. The dictionary
should be constructed with unique numerical keys that point to a dictionary which represents a row in the table: data = {0 : {‘id’:1, ‘precip’:43, ‘total’: 65},
1 : {‘id’:2, ‘precip’:65, ‘total’: 94}}
returns - nothing
-
natcap.invest.wave_energy.wave_energy.
create_percentile_ranges
(percentiles, units_short, units_long, start_value)¶ Constructs the percentile ranges as Strings, with the first range starting at 1 and the last range being greater than the last percentile mark. Each string range is stored in a list that gets returned
percentiles - A list of the percentile marks in ascending order units_short - A String that represents the shorthand for the units of
the raster values (ex: kW/m)- units_long - A String that represents the description of the units of
- the raster values (ex: wave power per unit width of wave crest length (kW/m))
- start_value - A String representing the first value that goes to the
- first percentile range (start_value - percentile_one)
returns - A list of Strings representing the ranges of the percentiles
-
natcap.invest.wave_energy.wave_energy.
create_percentile_rasters
(raster_path, output_path, units_short, units_long, start_value, percentile_list, aoi_shape_path)¶ Creates a percentile (quartile) raster based on the raster_dataset. An attribute table is also constructed for the raster_dataset that displays the ranges provided by taking the quartile of values. The following inputs are required:
raster_path - A uri to a gdal raster dataset with data of type integer output_path - A String for the destination of new raster units_short - A String that represents the shorthand for the units
of the raster values (ex: kW/m)- units_long - A String that represents the description of the units
- of the raster values (ex: wave power per unit width of wave crest length (kW/m))
- start_value - A String representing the first value that goes to the
- first percentile range (start_value - percentile_one)
- percentile_list - a python list of the percentiles ranges
- ex: [25, 50, 75, 90]
- aoi_shape_path - a uri to an OGR polygon shapefile to clip the
- rasters to
return - Nothing
-
natcap.invest.wave_energy.wave_energy.
execute
(args) Wave Energy.
Executes both the biophysical and valuation parts of the wave energy model (WEM). Files will be written on disk to the intermediate and output directories. The outputs computed for biophysical and valuation include: wave energy capacity raster, wave power raster, net present value raster, percentile rasters for the previous three, and a point shapefile of the wave points with attributes.
Parameters: - workspace_dir (string) – Where the intermediate and output folder/files will be saved. (required)
- wave_base_data_uri (string) – Directory location of wave base data including WW3 data and analysis area shapefile. (required)
- analysis_area_uri (string) – A string identifying the analysis area of interest. Used to determine wave data shapefile, wave data text file, and analysis area boundary shape. (required)
- aoi_uri (string) – A polygon shapefile outlining a more detailed area within the analysis area. This shapefile should be projected with linear units being in meters. (required to run Valuation model)
- machine_perf_uri (string) – The path of a CSV file that holds the machine performance table. (required)
- machine_param_uri (string) – The path of a CSV file that holds the machine parameter table. (required)
- dem_uri (string) – The path of the Global Digital Elevation Model (DEM). (required)
- suffix (string) – A python string of characters to append to each output filename (optional)
- valuation_container (boolean) – Indicates whether the model includes valuation
- land_gridPts_uri (string) – A CSV file path containing the Landing and Power Grid Connection Points table. (required for Valuation)
- machine_econ_uri (string) – A CSV file path for the machine economic parameters table. (required for Valuation)
- number_of_machines (int) – An integer specifying the number of machines for a wave farm site. (required for Valuation)
Example Args Dictionary:
{ 'workspace_dir': 'path/to/workspace_dir', 'wave_base_data_uri': 'path/to/base_data_dir', 'analysis_area_uri': 'West Coast of North America and Hawaii', 'aoi_uri': 'path/to/shapefile', 'machine_perf_uri': 'path/to/csv', 'machine_param_uri': 'path/to/csv', 'dem_uri': 'path/to/raster', 'suffix': '_results', 'valuation_container': True, 'land_gridPts_uri': 'path/to/csv', 'machine_econ_uri': 'path/to/csv', 'number_of_machines': 28, }
-
natcap.invest.wave_energy.wave_energy.
get_coordinate_transformation
(source_sr, target_sr)¶ This function takes a source and target spatial reference and creates a coordinate transformation from source to target, and one from target to source.
source_sr - A spatial reference target_sr - A spatial reference
- return - A tuple, coord_trans (source to target) and
- coord_trans_opposite (target to source)
-
natcap.invest.wave_energy.wave_energy.
get_points_geometries
(shape_uri)¶ This function takes a shapefile and for each feature retrieves the X and Y value from it’s geometry. The X and Y value are stored in a numpy array as a point [x_location,y_location], which is returned when all the features have been iterated through.
shape_uri - An uri to an OGR shapefile datasource
- returns - A numpy array of points, which represent the shape’s feature’s
- geometries.
-
natcap.invest.wave_energy.wave_energy.
load_binary_wave_data
(wave_file_uri)¶ The load_binary_wave_data function converts a pickled WW3 text file into a dictionary who’s keys are the corresponding (I,J) values and whose value is a two-dimensional array representing a matrix of the number of hours a seastate occurs over a 5 year period. The row and column headers are extracted once and stored in the dictionary as well.
wave_file_uri - The path to a pickled binary WW3 file.
- returns - A dictionary of matrices representing hours of specific
seastates, as well as the period and height ranges. It has the following structure:
- {‘periods’: [1,2,3,4,...],
‘heights’: [.5,1.0,1.5,...], ‘bin_matrix’: { (i0,j0): [[2,5,3,2,...], [6,3,4,1,...],...],
- (i1,j1): [[2,5,3,2,...], [6,3,4,1,...],...],
- ...
(in, jn): [[2,5,3,2,...], [6,3,4,1,...],...]
}
}
-
natcap.invest.wave_energy.wave_energy.
pixel_size_based_on_coordinate_transform
(dataset_uri, coord_trans, point)¶ Get width and height of cell in meters.
Calculates the pixel width and height in meters given a coordinate transform and reference point on the dataset that’s close to the transform’s projected coordinate sytem. This is only necessary if dataset is not already in a meter coordinate system, for example dataset may be in lat/long (WGS84).
Parameters: - dataset_uri (string) – a String for a GDAL path on disk, projected in the form of lat/long decimal degrees
- coord_trans (osr.CoordinateTransformation) – an OSR coordinate transformation from dataset coordinate system to meters
- point (tuple) – a reference point close to the coordinate transform coordinate system. must be in the same coordinate system as dataset.
Returns: - a 2-tuple containing (pixel width in meters, pixel
height in meters)
Return type: pixel_diff (tuple)
-
natcap.invest.wave_energy.wave_energy.
pixel_size_helper
(shape_path, coord_trans, coord_trans_opposite, ds_uri)¶ This function helps retrieve the pixel sizes of the global DEM when given an area of interest that has a certain projection.
- shape_path - A uri to a point shapefile datasource indicating where
- in the world we are interested in
coord_trans - A coordinate transformation coord_trans_opposite - A coordinate transformation that transforms in
the opposite direction of ‘coord_trans’ds_uri - A uri to a gdal dataset to get the pixel size from
- returns - A tuple of the x and y pixel sizes of the global DEM
- given in the units of what ‘shape’ is projected in
-
natcap.invest.wave_energy.wave_energy.
wave_energy_interp
(wave_data, machine_perf)¶ - Generates a matrix representing the interpolation of the
machine performance table using new ranges from wave watch data.
- wave_data - A dictionary holding the new x range (period) and
y range (height) values for the interpolation. The dictionary has the following structure:
- {‘periods’: [1,2,3,4,...],
‘heights’: [.5,1.0,1.5,...], ‘bin_matrix’: { (i0,j0): [[2,5,3,2,...], [6,3,4,1,...],...],
- (i1,j1): [[2,5,3,2,...], [6,3,4,1,...],...],
- ...
(in, jn): [[2,5,3,2,...], [6,3,4,1,...],...]
}
}
- machine_perf - a dictionary that holds the machine performance
- information with the following keys and structure:
- machine_perf[‘periods’] - [1,2,3,...] machine_perf[‘heights’] - [.5,1,1.5,...] machine_perf[‘bin_matrix’] - [[1,2,3,...],[5,6,7,...],...].
returns - The interpolated matrix
-
natcap.invest.wave_energy.wave_energy.
wave_power
(shape_uri)¶ Calculates the wave power from the fields in the shapefile and writes the wave power value to a field for the corresponding feature.
- shape_uri - A uri to a Shapefile that has all the attributes
- represented in fields to calculate wave power at a specific wave farm
returns - Nothing