gnome.utilities.timeseries

Module Contents

Classes

Timeseries

A class for assigning a unique ID for an object

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 filename

property extrapolation_is_allowed

_schema

_check_timeseries(timeseries)

Run some checks to make sure timeseries is valid.

• We accept numpy arrays

• We accept a list of timeseries values of the form

  (datetime(…), (N, N))

• We also accept a constant single timeseries value.

__len__()

length is the number of data points in the timeseries

__eq__(o)

get_start_time()

:this will be the real_data_start time (seconds).

get_end_time()

:this will be the real_data_stop time (seconds).

_is_timeseries_value(value)

_timeseries_is_ascending(timeseries)

Check if values are monotonically increasing

This should catch both out of order and duplicate values.

_xform_input_timeseries(timeseries)

Ensure input data is numpy array with correct dtype and check timeseries doesn’t have invalid data Derived classes can use this before updating timeseries, prior to converting units.

__str__()

Return str(self).

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.