:py:mod:`gnome.utilities.convert`
=================================

.. py:module:: gnome.utilities.convert

.. autoapi-nested-parse::

   Helper classes to do common tasks in pyGnome like;
   - convert_formats to convert datetime_value to time_value_pair



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


Functions
~~~~~~~~~

.. autoapisummary::

   gnome.utilities.convert.to_time_value_pair
   gnome.utilities.convert.to_datetime_value_2d
   gnome.utilities.convert.to_datetime_value_1d
   gnome.utilities.convert.tsformat



.. py:function:: to_time_value_pair(datetime_value, in_ts_format=None)

   converts a numpy array containing basic_types.datetime_value_2d in
   user specified basic_types.ts_format into a time_value_pair array
   or it takes a basic_types.datetime_value_1d array and converts it to
   a time_value_pair array -- for 1d data, assume the ['value'] contains
   the 'u' component and set the 'v' component to 0.0

   :param datetime_value: numpy array of type basic_types.datetime_value_2d or
       basic_types.datetime_value_1d
   :param in_ts_format=None: format of the datetime_value_2d array - not
       required when converting from datetime_value_1d. Can be defined by a
       string 'r-theta', 'uv' or by an integer defined by one of the options
       given in basic_types.ts_format.


.. py:function:: to_datetime_value_2d(time_value_pair, out_ts_format)

   converts a numpy array containing basic_types.time_value_pair to a
   numpy array containing basic_types.datetime_value_2d in user specified
   basic_types.ts_format

   :param time_value_pair: numpy array of type basic_types.time_value_pair
   :param out_ts_format: desired format of the array defined by one of the
                         options given in basic_types.ts_format


.. py:function:: to_datetime_value_1d(time_value_pair)

   converts a numpy array containing basic_types.time_value_pair to a
   numpy array containing basic_types.datetime_value_1d. It simply drops the
   2nd component of value: eg:

     time_value_pair[0] = ((datetime), (val_0, val_1))

   becomes: output = ((datetime), (val_0,))
   This is partly used for timeseries for Tide data and in this case, the
   v-component of velocity (u, v) is 0.0

   This function does not perform a check to see if 2nd component is 0.0, it
   simply drops it.

   :param time_value_pair: numpy array of type basic_types.time_value_pair


.. py:function:: tsformat(format_obj)

   convert string 'uv' or 'magnitude_direction' or 'r_theta' or 'r-theta'
   into appropriate enum in basic_types.ts_format