Skip to content

Commit

Permalink
Merge pull request #378 from gro-intelligence/GAIA-20447-add-dev-docs…
Browse files Browse the repository at this point in the history 
…-for-experimental-v2-prime

Gaia 20447 - Add developers docs for experimental v2 prime get_data_points function
  • Loading branch information
@prabesh-paudel
prabesh-paudel authored Apr 20, 2023
2 parents 4a69186 + 264ccd0 commit 588a990
Show file tree
Hide file tree
Showing 3 changed files with 67 additions and 51 deletions.
6 changes: 6 additions & 0 deletions docs/api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,3 +81,9 @@ Crop Modeling
.. automethod:: groclient.CropModel.compute_gdd

.. automethod:: groclient.CropModel.growing_degree_days

=============
Experimental
=============

.. automethod:: groclient.Experimental.get_data_points
4 changes: 2 additions & 2 deletions docs/prerequisites/anaconda-additional-information.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Anaconda Additional Information

#. If your username includes spaces, as is common on Windows systems, you are not allowed to install Anaconda in the default path (C:\Users\<your-username>\Anaconda3\)

a. See this `Anaconda link <https://docs.anaconda.com/anaconda/user-guide/faq/>`_ for additional information.
a. See this `Anaconda link <https://docs.anaconda.com/free/anaconda/reference/faq/>`_ for additional information.

#. If you install Anaconda outside of the default path, then you will need to update the config for the jupyter notebook default directory as outlined below:

Expand All @@ -27,6 +27,6 @@ Anaconda Additional Information
f. Relaunch Anaconda Navigator
g. Launch jupyter notebook

#. See the following link from Anaconda if you have a `proxy <https://docs.anaconda.com/anaconda/user-guide/tasks/proxy/>`_
#. See the following link from Anaconda if you have a `proxy <https://enterprise-docs.anaconda.com/en/latest/admin/chan-pkg/proxy.html>`_
#. See the following link from Anaconda if you have a `firewall <https://docs.anaconda.com/anaconda-enterprise-4/ae-and-nav/#configuring-firewall-settings>`_

108 changes: 59 additions & 49 deletions groclient/experimental.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,31 +3,71 @@


class Experimental(GroClient):
"""
Experimental class to consume v2prime data.
"""
"""The experimental client will introduce a range of experimental functions with better user experience.
While you will be able to access better performance and new features at an early stage,
you should be aware that things might change (e.g response format)."""

def get_data_points(self, **selections):
"""
Get all the data points for a given selection from /v2prime/data.
"""This function is a mirror of existing :meth:`~groclient.GroClient.get_data_points`, but with limited scope.
For example:
- Ontology expansion is under development.
- "Gro derived on-the-fly" is under development.
- Many sources are still under migration (please refer to internal confluence page for source migration timeline)
Parameters
----------
metric_id : integer
How something is measured. e.g. "Export Value" or "Area Harvested"
item_ids : integer or list of integers
What is being measured. e.g. "Corn" or "Rainfall"
region_ids : integer or list of integers
Where something is being measured e.g. "United States Corn Belt" or "China"
partner_region_ids : integer or list of integers, optional
partner_region refers to an interaction between two regions, like trade or
transportation. For example, for an Export metric, the "region" would be the exporter
and the "partner_region" would be the importer. For most series, this can be excluded
or set to 0 ("World") by default.
source_id : integer
frequency_id : integer
unit_id : integer, optional
start_date : string, optional
All data points with end dates after this date.
end_date : string, optional
All data points with start dates before this date.
coverage_threshold: float, optional
Custom threshold on the coverage of geospatial data. Value should be between 0 and 1.
Returns
-------
dict
dictionary containing list of data_points and series_description
Example::
exp_client = Experimental(access_token="your_token_here")
exp_client.get_data_points(
**{
'metric_id': 2540047,
'item_ids': [3457],
'region_ids': [100023971, 100023990],
'frequency_id': 1,
'source_id': 26,
'start_date': '2021-12-20',
'end_date': '2021-12-21',
}
)
Returns::
Example:
experimental_client.get_data_points(**{'metric_id': 2540047,
'item_ids': [3457],
'region_ids': [100023971, 100023990],
'frequency_id': 1,
'source_id': 26,
'start_date': '2021-12-20',
'end_date': '2021-12-21',
'stream': False
})
Returns:
{
"data_series": [
{
"data_points": [
{
"timestamp_sec": "1640044800",
"value": 33.20465087890625,
"start_timestamp": "1639958400",
"end_timestamp": "1640044800"
Expand All @@ -45,7 +85,6 @@ def get_data_points(self, **selections):
{
"data_points": [
{
"timestamp_sec": "1640044800",
"value": 32.73432922363281,
"start_timestamp": "1639958400",
"end_timestamp": "1640044800"
Expand All @@ -62,40 +101,11 @@ def get_data_points(self, **selections):
}
],
"meta": {
"version": "local",
"version": "v1.266.0",
"copyright": "Copyright (c) Gro Intelligence",
"timestamp": "Mon, 03 Apr 2023 19:34:38 GMT"
"timestamp": "Wed, 19 Apr 2023 14:34:05 GMT"
}
}
Parameters
----------
metric_id : integer
How something is measured. e.g. "Export Value" or "Area Harvested"
item_ids : integer or list of integers
What is being measured. e.g. "Corn" or "Rainfall"
region_ids : integer or list of integers
Where something is being measured e.g. "United States Corn Belt" or "China"
partner_region_ids : integer or list of integers, optional
partner_region refers to an interaction between two regions, like trade or
transportation. For example, for an Export metric, the "region" would be the exporter
and the "partner_region" would be the importer. For most series, this can be excluded
or set to 0 ("World") by default.
source_id : integer
frequency_id : integer
unit_id : integer, optional
start_date : string, optional
All points with end dates equal to or after this date
end_date : string, optional
All points with start dates equal to or before this date
coverage_threshold: float, optional
Custom threshold on the coverage of geospatial data. Value should be between 0 and 1.
stream: bool, optional
Returns
-------
dict of data_series containing data points and its description as shown in above example.
"""
return lib.get_data_points_v2_prime(
self.access_token, self.api_host, **selections
Expand Down

0 comments on commit 588a990

Please sign in to comment.