gnome.utilities.timeseries

Exceptions

TimeseriesError

Error class for a problem with the timeseries check

Classes

Timeseries

A class for assigning a unique ID for an object

Module Contents

exception gnome.utilities.timeseries.TimeseriesError

Bases: Exception

Error class for a problem with the timeseries check

Initialize self. See help(type(self)) for accurate signature.

class gnome.utilities.timeseries.Timeseries(timeseries=None, filename=None, coord_sys='uv', extrapolation_is_allowed=False, **kwargs)

Bases: gnome.GnomeId

A class for assigning a unique ID for an object

Initializes a timeseries object from either a timeseries or datafile containing the timeseries. If both timeseries and file are given, it will read data from the file

If neither are given, timeseries gets initialized as:

timeseries = np.zeros((1,), dtype=basic_types.datetime_value_2d)

If user provides timeseries, the default coordinate system is ‘uv’. The C++ stores the data in ‘uv’ coordinates - transformations are done in this Python code (set_timeseries(), get_timeseries()).

C++ code only transforms the data from ‘r-theta’ to ‘uv’ coordinates if data is read from file. And this happens during initialization because C++ stores data in ‘uv’ coordinates internally.

Units option are not included - let derived classes manage units since the units for CyTimeseries (OSSMTimeValue_c) are limited. No unit conversion is performed when get_timeseries, set_timeseries is invoked. It does, however convert between ‘uv’ and ‘r-theta’ depending on the coordinate system specified. Choose coord_sys=’uv’ if no transformation is desired.

Note

For the Wind datafiles, the units will get read from the file. These are stored in ossm.user_units. It would be ideal to remove units and unit conversion from here, but can’t completely do away with it since C++ file reading uses/sets it. But, managing units is responsibility of derived objects.

All other keywords are optional

Parameters:

  • timeseries (numpy.ndarray containing basic_types.datetime_value_2d or basic_types.datetime_value_1d. It gets converted to an array containing basic_types.time_value_pair datatype since that's what the C++ code expects) – numpy array containing time_value_pair

  • filename –

    path to a timeseries file from which to read data. Datafile must contain either a 3 line or a 5 line header with following info:

    1. Station Name: name of the station as a string

    2. (long, lat, z): station location as tuple containing floats

    3. units: for wind this is knots, meteres per second or miles per hour. For datafile containing something other than velocity, this should be ‘undefined’

Optional parameters (kwargs):

Parameters:

coord_sys (string 'r-theta' or 'uv'. Default is 'r-theta'. Converts string to integer defined by gnome.basic_types.ts_format.*) – (Optional) default timeseries coordinate system is magnitude direction: ‘r-theta’

property extrapolation_is_allowed
get_start_time()

:this will be the real_data_start time (seconds).

get_end_time()

:this will be the real_data_stop time (seconds).

property filename
get_timeseries(datetime=None, coord_sys='uv')

Returns the timeseries in requested coordinate system. If datetime=None, then the original timeseries that was entered is returned. If datetime is a list containing datetime objects, then the value for each of those date times is determined by the underlying C++ object and the timeseries is returned.

The output coordinate system is defined by the strings ‘r-theta’, ‘uv’

Parameters:

  • datetime (datetime object) – [optional] datetime object or list of datetime objects for which the value is desired

  • coord_sys (either string or integer value defined by basic_types.ts_format.* (see cy_basic_types.pyx)) – output coordinate system for the times series: either ‘r-theta’ or ‘uv’

Returns:

numpy array containing dtype=basic_types.datetime_value_2d. Contains user specified datetime and the corresponding values in user specified ts_format

set_timeseries(datetime_value_2d, coord_sys='uv')

Sets the timeseries to the new value given by a numpy array. The coordinate system for the input data defaults to basic_types.format.magnitude_direction but can be changed by the user.

Assumes timeseries is valid so _check_timeseries has been invoked and any unit conversions are done. This function simply converts datetime_value_2d to time_value_pair and updates the data in underlying cython/C++ object

Parameters:

  • datetime_value_2d (numpy array of dtype basic_types.datetime_value_2d) – timeseries of wind data defined in a numpy array

  • coord_sys (either string or integer value defined by basic_types.ts_format.* (see cy_basic_types.pyx)) – output coordinate system for the times series, as defined by basic_types.ts_format.