Raster Timeseries Data

class openet_client.timeseries.RasterTimeSeries(raster_manager)

point_sample(longitude, latitude, start_date, end_date, interval='monthly', make_lookup=False, **params)

A general function to retrieve the timeseries data from OpenET for a specific coordinate and date range. Uses the Raster API endpoint at raster/timeseries/point to retrieve data. This function retrieves the full timeseries between the start and the end date, but convenience functions for retrieving a single value are also available as single_month_point_sample or single_day_point_sample

This function accepts specified keyword arguments for the most common items to specify, but all other parameters to the endpoint can be provided as additional keyword arguments to this function. You do not need to include the keys for lon or lat - if provided - they will be set (or overwritten) by the values provided in the keys longitude and latitude (note that this function uses the full words for longitude and latitude though)

This function returns a list of dictionaries, as provided by the OpenET API. Each dictionary represents a single observation/value and will have a key time, whose value indicates the timepoint of the observation. The dictionaries will also have a second key for the variable returned (defaults to et) - see the OpenET API documentation for options.

Parameters:

longitude – Longitude portion of the coordinate to retrieve data from, in decimal degrees. See OpenET API documentation for any additional specifications for this item (param lon to the OpenET API)
latitude – Latitude portion of the coordinate to retrieve data from, in decimal degrees
start_date – The date to start the sample. Can be a Python standard library datetime.datetime object, an arrow.Arrow object or a string in “YYYY-MM-DD” format.
end_date – The date to end the sample. Can be a Python standard library datetime.datetime object, an arrow.Arrow object or a string in “YYYY-MM-DD” format.
interval – The time step to use in the timeseries. The OpenET API documentation doesn’t specify valid values here, but monthly: and :code:`daily are both known allowed values When using the monthly timestep, the returned timeseries will use dates for the first of every month within the timeseries. See return below for more details
make_lookup –
By default, the API returns a list of dictionaries that each have a key for time and the variable requested (e.g. et). To find specific values in that list you would need to search all objects. If, instead, you want to rely on a known structure of the time values (e.g., that with monthly data, values will look like 2018-01-01 then 2018-02-01), you canm set make_lookup to true. This flag changes the return type of the function into a dictionary, where the keys are the dates and the values are the data in the variable field of the original dictionaries (e.g. the et value).

For example, if their API returned the following data for a request, by default, this function would return a similar Python representation of the data:
```
[
        {
                "time": "2018-01-01",
                "et": 30
        },
        {
                "time": "2018-02-01",
                "et": 52
        },
]
```
If make_lookup is set to True then this function will instead return the following dictionary
```
{
        "2018-01-01": 30,
        "2018-02-01": 52,
}
```
params – Additional keyword arguments that the OpenET API allows can be provided to this function and they will be passed along to the API. Do not provide a keyword params to this function. Instead, provide keyword arguments that match the OpenET API’s parameter names

Returns:

See make_lookup above for return behavior, which is dependent on the value of make_lookup. Either a list of dictionaries (loaded from JSON) by default, or a dictionary when make_lookup == True

single_day_point_sample(longitude, latitude, date, **params)

The point_sample function can return an arbitrary timeseries for a single point. This function instead returns only the ET value specified, or other variable if an argument is provided for the API. Optional additional parameters may sent to the same endpoint as keyword arguments to this function - the same as other functions in this same timeseries module. Returns a single value for the day specified.

If you need to retrieve multiple values, you may stay within your OpenET API quotas better with well-constructed use of the point_sample, but for scattered or small numbers of samples, this function may be easier to use.

Parameters:

longitude –
Longitude portion of the coordinate to retrieve data from, in decimal degrees. See OpenET API documentation for any additional specifications for this item (param lon to the OpenET API)
latitude – Latitude portion of the coordinate to retrieve data from, in decimal degrees
date – The day to obtain the sample for. The date may be a Python standard library datetime.datetime object, an arrow.Arrow object or a string in “YYYY-MM-DD” format.
params – Additional keyword arguments that the OpenET API allows can be provided to this function and they will be passed along to the API. Do not provide a keyword params to this function. Instead, provide keyword arguments that match the OpenET API’s parameter names. Note that in this function, you should not provide keyword arguments for interval, lat, lon, start_date, or end_date, as these values will be created automatically by this function.

Returns:

A single value (may be a string, check the type before using) for the variable of interest, in the units returned by the API for the day specified. By default, the API will return values for ET, from the ensemble model, in metric units. To change these parameters, pass the appropriate additional keyword arguments for the API into this function.

single_month_point_sample(longitude, latitude, date, **params)

The point_sample function can return an arbitrary timeseries for a single point. This function instead returns only the ET value specified, or other variable if an argument is provided for the API. Optional additional parameters may sent to the same endpoint as keyword arguments to this function - the same as other functions in this same timeseries module. Returns a single value for the month specified.

If you need to retrieve multiple values, you may stay within your OpenET API quotas better with well-constructed use of the point_sample, but for scattered or small numbers of samples, this function may be easier to use.

Parameters:

longitude –
Longitude portion of the coordinate to retrieve data from, in decimal degrees. See OpenET API documentation for any additional specifications for this item (param lon to the OpenET API)
latitude – Latitude portion of the coordinate to retrieve data from, in decimal degrees
date – The month to obtain the sample for. The date may be a Python standard library datetime.datetime object, an arrow.Arrow object or a string in “YYYY-MM-DD” format.
params – Additional keyword arguments that the OpenET API allows can be provided to this function and they will be passed along to the API. Do not provide a keyword params to this function. Instead, provide keyword arguments that match the OpenET API’s parameter names. Note that in this function, you should not provide keyword arguments for interval, lat, lon, start_date, or end_date, as these values will be created automatically by this function.

Returns:

A single value (may be a string, check the type before using) for the variable of interest, in the units returned by the API for the month specified. By default, the API will return values for ET, from the ensemble model, in metric units. To change these parameters, pass the appropriate additional keyword arguments for the API into this function.