:py:mod:`gnome.utilities.timeseries` ==================================== .. py:module:: gnome.utilities.timeseries Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: gnome.utilities.timeseries.Timeseries .. py:exception:: TimeseriesError Bases: :py:obj:`Exception` Error class for a problem with the timeseries check Initialize self. See help(type(self)) for accurate signature. .. py:class:: Timeseries(timeseries=None, filename=None, coord_sys='uv', extrapolation_is_allowed=False, **kwargs) Bases: :py:obj:`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 :param timeseries: numpy array containing time_value_pair :type 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 :param 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): :param coord_sys: (Optional) default timeseries coordinate system is magnitude direction: 'r-theta' :type coord_sys: string 'r-theta' or 'uv'. Default is 'r-theta'. Converts string to integer defined by gnome.basic_types.ts_format.* .. py:property:: filename .. py:property:: extrapolation_is_allowed .. py:attribute:: _schema .. py:method:: _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. .. py:method:: __len__() length is the number of data points in the timeseries .. py:method:: __eq__(o) .. py:method:: get_start_time() :this will be the real_data_start time (seconds). .. py:method:: get_end_time() :this will be the real_data_stop time (seconds). .. py:method:: _is_timeseries_value(value) .. py:method:: _timeseries_is_ascending(timeseries) Check if values are monotonically increasing This should catch both out of order and duplicate values. .. py:method:: _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. .. py:method:: __str__() Return str(self). .. py:method:: 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' :param datetime: [optional] datetime object or list of datetime objects for which the value is desired :type datetime: datetime object :param coord_sys: output coordinate system for the times series: either 'r-theta' or 'uv' :type coord_sys: either string or integer value defined by basic_types.ts_format.* (see cy_basic_types.pyx) :returns: numpy array containing dtype=basic_types.datetime_value_2d. Contains user specified datetime and the corresponding values in user specified ts_format .. py:method:: 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 :param datetime_value_2d: timeseries of wind data defined in a numpy array :type datetime_value_2d: numpy array of dtype basic_types.datetime_value_2d :param coord_sys: output coordinate system for the times series, as defined by basic_types.ts_format. :type coord_sys: either string or integer value defined by basic_types.ts_format.* (see cy_basic_types.pyx)