opendrift.readers.basereader ============================ .. py:module:: opendrift.readers.basereader Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/opendrift/readers/basereader/consts/index /autoapi/opendrift/readers/basereader/continuous/index /autoapi/opendrift/readers/basereader/fakeproj/index /autoapi/opendrift/readers/basereader/structured/index /autoapi/opendrift/readers/basereader/unstructured/index /autoapi/opendrift/readers/basereader/variables/index Attributes ---------- .. autoapisummary:: opendrift.readers.basereader.logger opendrift.readers.basereader.standard_names opendrift.readers.basereader.vector_pairs_xy Classes ------- .. autoapisummary:: opendrift.readers.basereader.Variables opendrift.readers.basereader.Combine opendrift.readers.basereader.Filter opendrift.readers.basereader.ReaderBlock opendrift.readers.basereader.BaseReader Package Contents ---------------- .. py:data:: logger .. py:class:: Variables Bases: :py:obj:`ReaderDomain` Handles reading and interpolation of variables. .. py:attribute:: variables :value: None .. py:attribute:: derived_variables :value: None .. py:attribute:: name :value: None .. py:attribute:: buffer :value: 0 .. py:attribute:: environment_mappings .. py:method:: prepare(extent, start_time, end_time, max_speed) Prepare reader for given simulation coverage in time and space. .. py:method:: activate_environment_mapping(mapping_name) .. py:method:: __calculate_derived_environment_variables__(env) .. py:method:: set_buffer_size(max_speed, time_coverage=None) 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 .. py:method:: __check_env_coordinates__(env) Make sure x and y are floats (and not e.g. int64) .. py:method:: __check_variable_array__(name, variable) :staticmethod: Ensure arrays are not masked arrays and that values are within valid ranges. .. py:method:: __check_env_arrays__(env) Ensure arrays are not masked arrays and that values are within valid ranges. .. seealso:: Disabled in `StructuredReader` because variables are valided before entered into interpolator: :meth:`.structured.StructuredReader.__check_env_arrays__` .. py:method:: _get_variables_interpolated_(variables, profiles, profiles_depth, time, reader_x, reader_y, z) :abstractmethod: This method _must_ be implemented by every reader. Usually by subclassing one of the reader types (e.g. :class:`structured.StructuredReader`). Arguments are in _native projection_ of reader. .. seealso: * :meth:`get_variables_interpolated_xy`. * :meth:`get_variables_interpolated`. .. py:method:: get_variables_interpolated_xy(variables, profiles=None, profiles_depth=None, time=None, x=None, y=None, z=None, rotate_to_proj=None) Get variables in native projection of reader. .. seealso:: * :meth:`get_variables_interpolated`. * :meth:`_get_variables_interpolated_`. .. py:method:: get_variables_interpolated(variables, profiles=None, profiles_depth=None, time=None, lon=None, lat=None, z=None, rotate_to_proj=None) `get_variables_interpolated` is the main interface to :class:`opendrift.basemodel.OpenDriftSimulation`, and is responsible for returning variables at the correct positions. Readers should implement :meth:`_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. .. seealso:: :meth:`get_variables_interpolated_xy`. .. py:data:: standard_names .. py:data:: vector_pairs_xy :value: [['x_wind', 'y_wind', 'wind_speed', 'wind_to_direction', 'wind_from_direction'],... .. py:class:: Combine Combining two readers into a third one. You can use usual operators, but also more complex ones such as gaussian combining. .. py:method:: __add__(other) .. py:method:: __radd__(other) .. py:method:: __mul__(other) .. py:method:: __rmul__(other) .. py:method:: __truediv__(other) .. py:method:: __sub__(other) .. py:method:: combine_gaussian(measurement_reader, std) 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. .. py:class:: Filter .. py:property:: variables :type: List[str] :abstractmethod: .. py:method:: filter_vars(vars) Only keep the specified variables. .. py:method:: exclude_vars(vars) Remove the specified variables. .. py:class:: ReaderBlock(data_dict, interpolation_horizontal='linearNDFast', interpolation_vertical='linear', wrap_x=False) Class to store and interpolate the output from a reader with data on a regular (structured) grid. .. py:attribute:: x .. py:attribute:: y .. py:attribute:: time .. py:attribute:: data_dict .. py:attribute:: wrap_x :value: False .. py:method:: _initialize_interpolator(x, y, z=None) .. py:method:: interpolate(x, y, z=None, variables=None, profiles=[], profiles_depth=None) .. py:method:: _interpolate_horizontal_layers(data, nearest=False) Interpolate all layers of 3d (or 2d) array. .. py:method:: _wrap_longitude(x) .. py:method:: covers_positions(x, y, z=None) Check if given positions are covered by this reader block. .. py:class:: BaseReader Bases: :py:obj:`variables.Variables`, :py:obj:`opendrift.readers.operators.ops.Combine`, :py:obj:`opendrift.readers.operators.ops.Filter` An abstract reader. Implementors provide a method to read data and specify how it is interpolated. This class inherits :class:`.variables.Variables` which inherits :class:`.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 :py:mod:`opendrift.models.basemodel`, it defines the abstract interface to :meth:`.variables.Variables._get_variables_interpolated_` which reader-implementations must provide (_usually_ through one of the main reader-types, see: :py:mod:`opendrift.readers`). .. seealso:: :py:mod:`opendrift.readers`. :py:mod:`.variables`. Common constructor for all readers .. py:attribute:: __metaclass__ .. py:attribute:: verticalbuffer :value: 1 .. py:attribute:: variable_aliases .. py:attribute:: xy2eastnorth_mapping .. py:attribute:: number_of_fails :value: 0 .. py:attribute:: always_valid :value: False .. py:attribute:: is_lazy :value: False .. py:attribute:: _element_ID :value: None .. py:method:: y_is_north() .. py:method:: index_of_closest_z(requested_z) Return (internal) index of z closest to requested z. Thickness of layers (of ocean model) are not assumed to be constant. .. py:method:: indices_min_max_z(z) 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 .. py:method:: performance() Report the time spent on various tasks .. py:method:: clip_boundary_pixels(numpix) Trim some (potentially bad) pixels along boundary .. py:method:: plot(variable=None, vmin=None, vmax=None, time=None, filename=None, title=None, buffer=1, lscale='auto', cmap=None, cbar_label=None) Plot geographical coverage of reader. .. py:method:: get_timeseries_at_position(lon, lat, variables=None, start_time=None, end_time=None, times=None) Get timeseries of variables from this reader at given position. .. py:method:: shift_start_time(start_time) Shift the time coverage of reader to match given start_time