opendrift.readers.basereader
Submodules
Package Contents
Classes
A structured reader. Data is gridded on a regular grid. Used by e.g.: 

An unstructured reader. Data is gridded irregularily. 

A continuous (in space and time) reader, able to provide 

Handles reading and interpolation of variables. 

Combining two readers into a third one. You can use usual operators, 

Class to store and interpolate the output from a reader with data on a regular (structured) grid. 

An abstract reader. Implementors provide a method to read data and specify how it is interpolated. 
Attributes
 opendrift.readers.basereader.logger
 class opendrift.readers.basereader.StructuredReader[source]
Bases:
opendrift.readers.basereader.variables.Variables
A structured reader. Data is gridded on a regular grid. Used by e.g.:
opendrift.readers.reader_netCDF_CF_generic.Reader
.Attributes:
projected: is True if
fakeproj.fakeproj
is used because of missing projection information. The data points are assumed to be approximately equidistant on the surface (i.e. in meters).clipped: pixels to to remove along boundary (e.g. in case of bad data).
See also
 clipped = 0
 x
 y
 interpolation = 'linearNDFast'
 convolve
 save_interpolator
 interpolator_filename
 __lonlat2xy_parallel__
 __disable_parallel__ = False
 abstract get_variables(variables, time=None, x=None, y=None, z=None)[source]
Obtain a _block_ of values of the requested variables at all positions (x, y, z) closest to given time. These will be stored in
opendrift.readers.interpolation.structured.ReaderBlock
and accessed from there. Arguments:
variables: list of variables.
time: datetime or None, time at which data are requested.
x, y: float or ndarrays; coordinates of requested points.
z: float or ndarray; vertical position (in meters, positive up)
 Returns:
Dictionary
keywords: variables (string) values: 2D ndarray bounding x and y.
 prepare(extent, start_time, end_time, max_speed)[source]
Prepare reader for given simulation coverage in time and space.
 set_convolution_kernel(convolve)[source]
Set a convolution kernel or kernel size (of array of ones) used by get_variables on read variables.
 _get_variables_interpolated_(variables, profiles, profiles_depth, time, reader_x, reader_y, z)[source]
This method _must_ be implemented by every reader. Usually by subclassing one of the reader types (e.g.
structured.StructuredReader
).Arguments are in _native projection_ of reader.
 __check_env_arrays__(env)[source]
For the StructuredReader the variables are checked before entered into the ReaderBlock interpolator. This methods makes the second check a noop.
 get_ocean_depth_area_volume(lonmin, lonmax, latmin, latmax)[source]
Get depth, area and volume of ocean basin within given coordinates
 _make_projected_grid_(lon, lat, eq_eps=0.1)[source]
Make the projected grid in cases where lon and lat are present as 2D variables, but not x and y and assert that it is approximately equidistant.
Args:
eq_eps: tolerance for equidistance checks.
 __validate_projected_grid__(eq_eps=0.1)[source]
Validate that the projected grid is approximately equidistant.
Args:
eq_eps: tolerance for equidistance checks.
Raises:
AssertionError if not equidistant within eq_eps.
 _slice_variable_(var, indxTime=None, indy=None, indx=None, indz=None, indrealization=None)[source]
Slice variable depending on number of dimensions available.
Args:
All arguments can be slice objects or index.
Returns:
var sliced using the slices or indexes necessary to use depending on number of dimensions available.
Raises:
Unsupported number of dimensions (outside 2..5) raises an exception.
 class opendrift.readers.basereader.UnstructuredReader[source]
Bases:
opendrift.readers.basereader.variables.Variables
An unstructured reader. Data is gridded irregularily.
The initial type of grid that this class supports are triangular prisms. Unstructured in xycoordinates, x and y is constant in z. z might be noncartesian (e.g. sigmalevels).
 PARALLEL_WORKERS
 boundary
 x
 y
 node_variables
 nodes_idx
 xc
 yc
 face_variables
 faces_idx
 abstract get_variables(variables, time=None, x=None, y=None, z=None)[source]
Obtain and return values of the requested variables at all positions (x, y, z) closest to given time.
Returns:
Dictionary with arrays of length len(time) with values at exact positions x, y and z.
 _get_variables_interpolated_(variables, profiles, profiles_depth, time, reader_x, reader_y, z)[source]
This method _must_ be implemented by every reader. Usually by subclassing one of the reader types (e.g.
structured.StructuredReader
).Arguments are in _native projection_ of reader.
 _build_boundary_polygon_(x, y)[source]
Build a polygon of the boundary of the mesh.
 Arguments:
 param x:
Array of node x position, lenght N
 param y:
Array of node y position, length N
 Returns:
A shapely.prepareped.prep shapely.Polygon.
The boundary of the mesh, ideally including holes in the mesh.
Algorithms:
Note
Try this alogrithm: https://stackoverflow.com/a/14109211/377927
Boundary edges (line between two nodes) are only referenced by a single triangle.
Find a starting edge segment: [v_start, v_next] (v is vertex or node)
Find another _unvisited_ edge segment [v_i, v_j] that has either v_i = v_next or v_j = v_next and add the one not equal to v_next to the polygon.
Reset v_next to the newly added point. Mark edge as visited.
Continue untill we reach v_start.
The polygon has a rotation, but this should not matter for our purpose of checking the bounds.
Note: In order to find holes in the polygon all points must be scanned.
Approximate using the convex hull:
An alternative simple approximation is to use the convex hull of the points, but this will miss points along the boundary which form a wedge in the boundary (as well as holes in the mesh).
Holes in the mesh will often be covered by the landmask anyway, so they will usually not be a problem.
 class opendrift.readers.basereader.ContinuousReader[source]
Bases:
opendrift.readers.basereader.variables.Variables
A continuous (in space and time) reader, able to provide exact values at any desired point (within bounds). This reader type is suitable for constant readers, analytical readers, or readers that are static and continuous within the valid domain (e.g. the landmask reader).
See also
 abstract get_variables(variables, time=None, x=None, y=None, z=None)[source]
Obtain and return values of the requested variables at all positions (x, y, z) closest to given time.
Returns:
Dictionary with arrays of length len(x) with values at exact positions x, y and z.
 _get_variables_interpolated_(variables, profiles, profiles_depth, time, reader_x, reader_y, z)[source]
This method _must_ be implemented by every reader. Usually by subclassing one of the reader types (e.g.
structured.StructuredReader
).Arguments are in _native projection_ of reader.
 class opendrift.readers.basereader.Variables[source]
Bases:
ReaderDomain
Handles reading and interpolation of variables.
 variables
 derived_variables
 name
 buffer = 0
 prepare(extent, start_time, end_time, max_speed)[source]
Prepare reader for given simulation coverage in time and space.
 set_buffer_size(max_speed, time_coverage=None)[source]
Adjust buffer to minimise data block size needed to cover elements.
The buffer size is calculated from the maximum anticpated speed. Seeding over a large area or over longer time can easily cause particles to be located outside the block. This is not critical, but causes interpolation to be onesided in time for the relevant particles.
Args:
max_speed (m/s): the maximum speed anticipated for particles. time_coverage (timedelta): the time span to cover
 static __check_variable_array__(name, variable)[source]
Ensure arrays are not masked arrays and that values are within valid ranges.
 __check_env_arrays__(env)[source]
Ensure arrays are not masked arrays and that values are within valid ranges.
See also
Disabled in StructuredReader because variables are valided before entered into interpolator:
 abstract _get_variables_interpolated_(variables, profiles, profiles_depth, time, reader_x, reader_y, z)[source]
This method _must_ be implemented by every reader. Usually by subclassing one of the reader types (e.g.
structured.StructuredReader
).Arguments are in _native projection_ of reader.
 get_variables_interpolated_xy(variables, profiles=None, profiles_depth=None, time=None, x=None, y=None, z=None, rotate_to_proj=None)[source]
Get variables in native projection of reader.
 get_variables_interpolated(variables, profiles=None, profiles_depth=None, time=None, lon=None, lat=None, z=None, rotate_to_proj=None)[source]
get_variables_interpolated is the main interface to
opendrift.basemodel.OpenDriftSimulation
, and is responsible for returning variables at the correct positions.Readers should implement
_get_variables_interpolated_()
. Arguments:
 variables: string, or list of strings (standard_name) of
requested variables. These must be provided by reader.
profiles: List of variable names that should be returned for the range in profiles_depth.
profiles_depth: Profiles variables will be retrieved from surface and down to this depth. The exact zdepth are given by the reader and returned as z variable in env_profiles.
 time: datetime or None, time at which data are requested.
Can be None (default) if reader/variable has no time dimension (e.g. climatology or landmask).
lon: longitude, 1d array.
lat: latitude, 1d array, same length as lon.
 z: float or ndarray; vertical position (in meters, positive up)
of requested points. either scalar or same length as lon, lat. default: 0 m (unless otherwise documented by reader)
block: bool, see return below
rotate_to_proj: N/A
Returns:
(env, env_profiles)
Interpolated variables at x, y and z. env contains values at a fixed depth (z), while env_profiles contains depthprofiles in the range profile_depth for the variables listed in profiles for each element (in x, y). The exact depth is determined by the reader and specified in env_profiles[‘z’]. Thus variables in env_profiles are not interpolated in zdirection.
See also
 opendrift.readers.basereader.standard_names
 opendrift.readers.basereader.vector_pairs_xy = [['x_wind', 'y_wind', 'wind_speed', 'wind_to_direction', 'wind_from_direction'],...
 class opendrift.readers.basereader.Combine[source]
Combining two readers into a third one. You can use usual operators, but also more complex ones such as gaussian combining.
 class opendrift.readers.basereader.Filter[source]
 abstract property variables: List[str]
 Return type:
List[str]
 class opendrift.readers.basereader.ReaderBlock(data_dict, interpolation_horizontal='linearNDFast', interpolation_vertical='linear')[source]
Class to store and interpolate the output from a reader with data on a regular (structured) grid.
 class opendrift.readers.basereader.BaseReader[source]
Bases:
variables.Variables
,opendrift.readers.operators.ops.Combine
,opendrift.readers.operators.ops.Filter
An abstract reader. Implementors provide a method to read data and specify how it is interpolated.
This class inherits
variables.Variables
which inheritsvariables.ReaderDomain
. ReaderDomain is responsible for the extent and domain of the reader, including checking for outofbounds and projection conversion. Variables is responsible for returning interpolated data at the requests positions or profiles. Apart from coercing the returned data into the right type foropendrift.models.basemodel
, it defines the abstract interface tovariables.Variables._get_variables_interpolated_()
which readerimplementations must provide (_usually_ through one of the main readertypes, see:opendrift.readers
).Common constructor for all readers
 __metaclass__
 verticalbuffer = 1
 variable_aliases
 xy2eastnorth_mapping
 index_of_closest_z(requested_z)[source]
Return (internal) index of z closest to requested z.
Thickness of layers (of ocean model) are not assumed to be constant.
 indices_min_max_z(z)[source]
Return min and max indices of internal vertical dimension, covering the requested vertical positions. Needed when block is requested (True).
 Arguments:
z: ndarray of floats, in meters
 plot(variable=None, vmin=None, vmax=None, time=None, filename=None, title=None, buffer=1, lscale='auto')[source]
Plot geographical coverage of reader.