opendrift.readers.basereader

Submodules

Attributes

`logger`
`standard_names`
`vector_pairs_xy`

Classes

`StructuredReader`	A structured reader. Data is gridded on a regular grid. Used by e.g.:
`UnstructuredReader`	An unstructured reader. Data is gridded irregularily.
`ContinuousReader`	A continuous (in space and time) reader, able to provide
`Variables`	Handles reading and interpolation of variables.
`Combine`	Combining two readers into a third one. You can use usual operators,
`Filter`
`ReaderBlock`	Class to store and interpolate the output from a reader with data on a regular (structured) grid.
`BaseReader`	An abstract reader. Implementors provide a method to read data and specify how it is interpolated.

Package Contents

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

opendrift.readers

clipped = 0

x = None

y = None

interpolation = 'linearNDFast'

convolve = None

save_interpolator = None

interpolator_filename = None

__lonlat2xy_parallel__ = None

__disable_parallel__ = False

var_block_before

var_block_after

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.

__convolve_block__(env)[source]: Convolve arrays with a kernel, if reader.convolve is set

lon_range()[source]

_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 no-op.

See also

variables.Variables.__check_env_arrays__().

xy2lonlat(x, y)[source]: Calculate x,y in own projection from given lon,lat (scalars/arrays).

lonlat2xy(lon, lat)[source]: Calculate lon,lat from given x,y (scalars/arrays) in own projection.

pixel_size()[source]

get_ocean_depth_area_volume(lonmin, lonmax, latmin, latmax)[source]: Get depth, area and volume of ocean basin within given coordinates

_coverage_unit_()[source]

_bbox_(x, y)[source]: Find bounding box on grid containing points (x, y)

_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 xy-coordinates, x and y is constant in z. z might be non-cartesian (e.g. sigma-levels).

See also

opendrift.readers

structured.StructuredReader

PARALLEL_WORKERS = -1

boundary = None

x = None

y = None

node_variables = None

nodes_idx = None

xc = None

yc = None

face_variables = None

faces_idx = None

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.

covers_positions(x, y, z=0)[source]: Check which points are within boundary of mesh.

_build_rtree_(x, y)[source]: Builds an R-tree of x, y

_build_ckdtree_(x, y)[source]

__nearest_ckdtree__(idx, x, y)[source]: Return index of nearest point in cKDTree

static __nearest_rtree__(idx, x, y)[source]: Take array of points and get nearest point in rtree index.

_nearest_node_(x, y)[source]: Return nearest node (id) for x and y

_nearest_face_(xc, yc)[source]: Return nearest element or face (id) for xc and yc

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

opendrift.readers

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 = None

derived_variables = None

name = None

buffer = 0

environment_mappings

prepare(extent, start_time, end_time, max_speed)[source]: Prepare reader for given simulation coverage in time and space.

activate_environment_mapping(mapping_name)[source]

__calculate_derived_environment_variables__(env)[source]

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 one-sided 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

__check_env_coordinates__(env)[source]: Make sure x and y are floats (and not e.g. int64)

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:

structured.StructuredReader.__check_env_arrays__()

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.

See also

get_variables_interpolated().
_get_variables_interpolated_().

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 z-depth 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 depth-profiles 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 z-direction.

See also

get_variables_interpolated_xy().

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.

__add__(other)[source]

__radd__(other)[source]

__mul__(other)[source]

__rmul__(other)[source]

__truediv__(other)[source]

__sub__(other)[source]

combine_gaussian(measurement_reader, std)[source]: Mix two readers with a gaussian, whose std is the one given as an argument. The measurment reader have to be of type timeseries, with a lon and lat attributes that are taken as the center of the measure.

class opendrift.readers.basereader.Filter[source]

property variables: List[str]

Abstractmethod:
Return type:: List[str]

filter_vars(vars)[source]: Only keep the specified variables.

exclude_vars(vars)[source]: Remove the specified variables.

class opendrift.readers.basereader.ReaderBlock(data_dict, interpolation_horizontal='linearNDFast', interpolation_vertical='linear', wrap_x=False)[source]

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

x

y

time

data_dict

wrap_x = False

_initialize_interpolator(x, y, z=None)[source]

interpolate(x, y, z=None, variables=None, profiles=[], profiles_depth=None)[source]

_interpolate_horizontal_layers(data, nearest=False)[source]: Interpolate all layers of 3d (or 2d) array.

covers_positions(x, y, z=None)[source]: Check if given positions are covered by this reader block.

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 inherits variables.ReaderDomain. ReaderDomain is responsible for the extent and domain of the reader, including checking for out-of-bounds 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 for opendrift.models.basemodel, it defines the abstract interface to variables.Variables._get_variables_interpolated_() which reader-implementations must provide (_usually_ through one of the main reader-types, see: opendrift.readers).

See also

opendrift.readers.

variables.

Common constructor for all readers

__metaclass__

verticalbuffer = 1

variable_aliases

xy2eastnorth_mapping

number_of_fails = 0

always_valid = False

is_lazy = False

y_is_north()[source]

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

performance()[source]: Report the time spent on various tasks

clip_boundary_pixels(numpix)[source]: Trim some (potentially bad) pixels along boundary

plot(variable=None, vmin=None, vmax=None, time=None, filename=None, title=None, buffer=1, lscale='auto', cmap=None, cbar_label=None)[source]: Plot geographical coverage of reader.

get_timeseries_at_position(lon, lat, variables=None, start_time=None, end_time=None, times=None)[source]: Get timeseries of variables from this reader at given position.

shift_start_time(start_time)[source]: Shift the time coverage of reader to match given start_time