# natcap.invest.wave_energy package¶

## natcap.invest.wave_energy.wave_energy module¶

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 longitude

prj - 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. 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. pixel_diff – a 2-tuple containing (pixel width in meters, pixel height in meters) 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