:py:mod:`opendrift.readers.reader_schism_native`
================================================

.. py:module:: opendrift.readers.reader_schism_native


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   opendrift.readers.reader_schism_native.Reader
   opendrift.readers.reader_schism_native.ReaderBlockUnstruct




Attributes
~~~~~~~~~~

.. autoapisummary::

   opendrift.readers.reader_schism_native.logger


.. py:data:: logger

   

.. py:class:: Reader(filename=None, name=None, proj4=None, use_3d=None)


   Bases: :py:obj:`opendrift.readers.basereader.BaseReader`, :py:obj:`opendrift.readers.basereader.UnstructuredReader`

   A reader for unstructured (irregularily gridded) `SCHISM` files.

   Args:
       :param filename: a single SCHISM netcdf output file, or a pattern of files.
                        The netCDF file can also be an URL to an OPeNDAP server.
       :type filename: string, required.

       :param name: Name of reader
       :type name: string, optional

       :param proj4: PROJ.4 string describing projection of data.
       :type proj4: string, optional

       :param use_3d: switch to use 3d flows (if available)
       :type use_3d: boolean, optional

   .. seealso::

       py:mod:`opendrift.readers.basereader.unstructured`.

   Common constructor for all readers

   .. py:method:: get_variables(requested_variables, time=None, x=None, y=None, z=None, block=False)

      The function extracts 'requested_variables' from the native SCHISM files
      which will then be used in _get_variables_interpolated_() to initialise the ReaderBlockUnstruct objects
      used to interpolate data in space and time

      For now the function will extract the entire slice of data of 'requested_variables' at given 'time'

      There is an option to extract only a subset of data around particles clouds to have less data but
      it means we need to recompute the KDtree of the subset nodes every time in ReaderBlockUnstruct.
      (Speed gain to be tested)



   .. py:method:: convert_3d_to_array(id_time, data, variable_dict)

      The function reshapes a data matrix of dimensions = [node,vertical_levels] (i.e. data at vertical levels, at given time step)
      into a one-column array and works out corresponding 3d coordinates [lon,lat,z] using the time-varying
      'zcor' variable in SCHISM files (i.e. vertical level positions).

      These 3D coordinates will be used to build the 3D KDtree for data interpolation and will be added to the 'variable_dict'
      which is eventually passed to get_variables_interpolated().

      args:
          -id_time
          -data
          -variable_dict
      out :
          -flattened 'data' array
          -addition of ['x_3d','y_3d','z_3d'] items to variable_dict if needed.


   .. py:method:: _get_variables_interpolated_(variables, profiles, profiles_depth, time, reader_x, reader_y, z)

      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:: set_convolution_kernel(convolve)

      Set a convolution kernel or kernel size (of array of ones) used by `get_variables` on read variables.


   .. py:method:: __convolve_block__(env)

      Convolve arrays with a kernel, if reader.convolve is set


   .. py:method:: covers_positions_xy(x, y, z=0)

      Check which points are within boundary of mesh.
      Wrapper function of covers_positions() from unstructured.py which is called in
      get_variables_interpolated_xy() function from variables.py
      It returns indices of in-mesh points, and in-mesh point coordinates rather than a boolean array (inside/outside)
      Within get_variables_interpolated_xy() from variables.py, data is queried for these in-mesh points only and the
      full array (incl. out of mesh positions) is re-generated with correct masking


   .. py:method:: plot_mesh(variable=None, vmin=None, vmax=None, filename=None, title=None, buffer=1, lscale='auto', plot_time=None)

      Plot geographical coverage of reader.



.. py:class:: ReaderBlockUnstruct(data_dict, KDtree=None, interpolation_horizontal='linearNDFast', interpolation_vertical='linear')


   Class to store and interpolate the data from an *unstructured* reader.
   This is the equivalent of ReaderBlock (regular grid) for *unstructured* grids.

   arguments: (in addition to ReaderBlock)

       KDtree : for nearest-neighbor search (initialized using SCHISM nodes in reader's _init_() )
                This is read from reader object, so that it is not recomputed every time


   .. py:attribute:: logger

      

   .. 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:: covers_positions(x, y, z=None)

      Check if given positions are covered by this reader block.