Move methods from values to stations, restructure data acquisition wi…

…th stations
earthobservations · Mar 5, 2021 · 3a094c3 · 3a094c3
1 parent b680861
commit 3a094c3
Show file tree

Hide file tree

Showing 27 changed files with 1,230 additions and 1,351 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -4,7 +4,9 @@ Changelog
 Development
 ***********
 
-...
+- Add StationsResult and ValuesResult to allow for new workflow and connect stations and
+  values request
+- Add accessor .values to Stations class to get straight to values for a request
 
 0.14.1 (21.02.2021)
 *******************

diff --git a/README.rst b/README.rst
@@ -211,23 +211,17 @@ Acquisition of historical data for specific stations using ``wetterdienst`` as l
 
 .. code-block:: python
 
-    >>> from wetterdienst.dwd.observations import (
-    ...     DWDObservationValues,
-    ...     DWDObservationParameterSet,
-    ...     DWDObservationPeriod,
-    ...     DWDObservationResolution
-    ... )
-    >>> observations = DWDObservationValues(
-    ...    station_id=[1048,4411],
-    ...    parameter=[DWDObservationParameterSet.CLIMATE_SUMMARY,
-    ...                DWDObservationParameterSet.SOLAR],
-    ...    resolution=DWDObservationResolution.DAILY,
+    >>> from wetterdienst.dwd.observations import DWDObservationStations
+    >>> request = DWDObservationStations(
+    ...    parameter=["climate_summary"],
+    ...    resolution="daily",
     ...    start_date="1990-01-01",  # Timezone: UTC
     ...    end_date="2020-01-01",  # Timezone: UTC
     ...    tidy_data=True,  # default
     ...    humanize_parameters=True,  # default
-    ... )
-    >>> df = observations.all()
+    ... ).filter(station_id=[1048, 4411])
+    >>> stations = request.df  # station list
+    >>> values = request.values.all().df  # values
 
 Receiving of stations for defined parameters using the ``wetterdienst`` client:
 

diff --git a/docs/usage/api.rst b/docs/usage/api.rst
@@ -114,9 +114,9 @@ Get station information for a given *parameter/parameter_set*, *resolution* and
         parameter=DWDObservationParameterSet.PRECIPITATION_MORE,
         resolution=DWDObservationResolution.DAILY,
         period=DWDObservationPeriod.HISTORICAL
-    )
+    ).all()
 
-    df = stations.all()
+    df = stations.df
 
     print(df.head())
 
@@ -125,35 +125,34 @@ The function returns a Pandas DataFrame with information about the available sta
 Values
 ------
 
-Use the ``DWDObservationValues`` class in order to get hold of values.
+Use the ``DWDObservationStations`` class in order to get hold of stations.
 
 .. ipython:: python
 
-    from wetterdienst.dwd.observations import DWDObservationValues, DWDObservationParameterSet, DWDObservationPeriod, DWDObservationResolution
+    from wetterdienst.dwd.observations import DWDObservationStations, DWDObservationParameterSet, DWDObservationPeriod, DWDObservationResolution
 
-    observations = DWDObservationValues(
-        station_id=[3, 1048],
+    request = DWDObservationStations(
         parameter=[DWDObservationParameterSet.CLIMATE_SUMMARY, DWDObservationParameterSet.SOLAR],
         resolution=DWDObservationResolution.DAILY,
         start_date="1990-01-01",
         end_date="2020-01-01",
         tidy_data=True,
         humanize_parameters=True,
-    )
+    ).filter(station_id=[3, 1048])
 
-Query data by station:
+From here you can query data by station:
 
 .. ipython:: python
 
-    for result in observations.query():
+    for result in request.values.query():
         # analyse the station here
-        print(result.data.dropna().head())
+        print(result.df.dropna().head())
 
 Query data all together:
 
 .. ipython:: python
 
-    df = observations.all().dropna()
+    df = request.values.all().df.dropna()
     print(df.head())
 
 This gives us the most options to work with the data, getting multiple parameters at
@@ -186,45 +185,41 @@ Inquire the list of stations by geographic coordinates.
         latitude=50.0,
         longitude=8.9,
         max_distance_in_km=30
-    )
+    ).df
 
     print(df.head())
 
     df = stations.nearby_number(
         latitude=50.0,
         longitude=8.9,
         number=5
-    )
+    ).df
 
     print(df.head())
 
 
-The function returns a DataFrame with the list of stations with distances [in km]
-to the given coordinates.
-
-The station ids within the DataFrame:
-
-.. ipython:: python
-
-    station_ids = df.STATION_ID.unique()
+The function returns a StationsResult with the list of stations being filtered for
+distances [in km] to the given coordinates.
 
-can be used to download the observation data:
+Again from here we can jump to the corresponding data:
 
 .. ipython:: python
 
-    observations = DWDObservationValues(
-        station_id=station_ids,
-        parameter=[DWDObservationParameterSet.TEMPERATURE_AIR, DWDObservationParameterSet.SOLAR],
+    stations = DWDObservationStations(
+        parameter=DWDObservationParameterSet.TEMPERATURE_AIR,
         resolution=DWDObservationResolution.HOURLY,
-        start_date="1990-01-01",
-        end_date="2020-01-01",
-        tidy_data=True,
-        humanize_parameters=True,
+        period=DWDObservationPeriod.RECENT,
+        start_date=datetime(2020, 1, 1),
+        end_date=datetime(2020, 1, 20)
+    ).nearby_radius(
+        latitude=50.0,
+        longitude=8.9,
+        max_distance_in_km=30
     )
 
-    for result in observations.query():
+    for result in stations.values.query():
         # analyse the station here
-        print(result.data.dropna().head())
+        print(result.df.dropna().head())
 
 Et voila: We just got the data we wanted for our location and are ready to analyse the
 temperature on historical developments.
@@ -240,19 +235,18 @@ The result data is provided through a virtual table called ``data``.
 
 .. code-block:: python
 
-    from wetterdienst.dwd.observations import DWDObservationValues, DWDObservationParameterSet, DWDObservationPeriod, DWDObservationResolution
+    from wetterdienst.dwd.observations import DWDObservationStations, DWDObservationParameterSet, DWDObservationPeriod, DWDObservationResolution
 
-    observations = DWDObservationValues(
-        station_id=[1048],
+    stations = DWDObservationStations(
         parameter=[DWDObservationParameterSet.TEMPERATURE_AIR],
         resolution=DWDObservationResolution.HOURLY,
         start_date="2019-01-01",
         end_date="2020-01-01",
         tidy_data=True,
         humanize_parameters=True,
-    )
+    ).filter(station_id=[1048])
 
-    df = observations.all().dwd.lower()
+    df = stations.values.all().df.dwd.lower()
     df = df.io.sql("SELECT * FROM data WHERE parameter='temperature_air_200' AND value < -7.0;")
     print(df.head())
 
@@ -271,20 +265,19 @@ Examples:
 
 .. code-block:: python
 
-    from wetterdienst.dwd.observations import DWDObservationValues, DWDObservationParameterSet,
+    from wetterdienst.dwd.observations import DWDObservationStations, DWDObservationParameterSet,
         DWDObservationPeriod, DWDObservationResolution, StorageAdapter
 
-    observations = DWDObservationValues(
-        station_id=[1048],
+    stations = DWDObservationStations(
         parameter=[DWDObservationParameterSet.TEMPERATURE_AIR],
         resolution=DWDObservationResolution.HOURLY,
         start_date="2019-01-01",
         end_date="2020-01-01",
         tidy_data=True,
         humanize_parameters=True,
-    )
+    ).filter(station_id=[1048])
 
-    df = observations.all().dwd.lower()
+    df = stations.values.all().df.dwd.lower()
     df.io.export("influxdb://localhost/?database=dwd&table=weather")
 
 Mosmix
@@ -296,9 +289,9 @@ Get stations for Mosmix:
 
     from wetterdienst.dwd.forecasts import DWDMosmixStations
 
-    stations = DWDMosmixStations()
+    stations = DWDMosmixStations(mosmix_type="large")  # actually same for small and large
 
-    print(stations.all().head())
+    print(stations.all().df.head())
 
 Mosmix forecasts require us to define ``station_ids`` and ``mosmix_type``. Furthermore
 we can also define explicitly the requested parameters.
@@ -307,16 +300,15 @@ Get Mosmix-L data:
 
 .. ipython:: python
 
-    from wetterdienst.dwd.forecasts import DWDMosmixValues, DWDMosmixType
+    from wetterdienst.dwd.forecasts import DWDMosmixStations, DWDMosmixType
 
-    mosmix = DWDMosmixValues(
-        station_id=["01001", "01008"],
+    stations = DWDMosmixStations(
         mosmix_type=DWDMosmixType.LARGE
-    )
-    response =  next(mosmix.query())
+    ).filter(station_id=["01001", "01008"])
+    response =  next(stations.values.query())
 
-    print(response.metadata)
-    print(response.data)
+    print(response.stations.df)
+    print(response.df)
 
 Radar
 =====

diff --git a/docs/usage/code_snippets.rst b/docs/usage/code_snippets.rst
@@ -44,39 +44,37 @@ Get stations for daily historical precipitation:
         period=DWDObservationPeriod.HISTORICAL
     )
 
-    print(stations.all().head())
+    print(stations.all().df.head())
 
 
 
 Get data for a parameter set:
 
 .. ipython:: python
 
-    from wetterdienst.dwd.observations import DWDObservationValues, DWDObservationParameterSet, DWDObservationResolution, DWDObservationPeriod
+    from wetterdienst.dwd.observations import DWDObservationStations, DWDObservationParameterSet, DWDObservationResolution, DWDObservationPeriod
 
-    observation_data = DWDObservationValues(
-        station_id=stations.all().STATION_ID[0],
+    stations = DWDObservationStations(
         parameter=DWDObservationParameterSet.PRECIPITATION_MORE,
         resolution=DWDObservationResolution.DAILY,
         period=DWDObservationPeriod.HISTORICAL
     )
 
-    print(observation_data.all().head())
+    print(next(stations.all().values.query()))
 
 Get data for a parameter:
 
 .. ipython:: python
 
-    from wetterdienst.dwd.observations import DWDObservationValues, DWDObservationParameter, DWDObservationResolution, DWDObservationPeriod
+    from wetterdienst.dwd.observations import DWDObservationStations, DWDObservationParameter, DWDObservationResolution, DWDObservationPeriod
 
-    observation_data = DWDObservationValues(
-        station_id=stations.all().STATION_ID[0],
+    observation_data = DWDObservationStations(
         parameter=DWDObservationParameter.DAILY.PRECIPITATION_HEIGHT,
         resolution=DWDObservationResolution.DAILY,
         period=DWDObservationPeriod.HISTORICAL
     )
 
-    print(observation_data.all().head())
+    print(next(stations.all().values.query()))
 
 Mosmix
 ------
@@ -85,21 +83,20 @@ Get stations for Mosmix:
 
 .. ipython:: python
 
-    from wetterdienst.dwd.forecasts import DWDMosmixStations
+    from wetterdienst.dwd.forecasts import DWDMosmixStations, DWDMosmixType
 
-    stations = DWDMosmixStations()
+    stations = DWDMosmixStations(mosmix_type=DWDMosmixType.LARGE)
 
-    print(stations.all().head())
+    print(stations.all().df.head())
 
 Get data for Mosmix-L:
 
 .. ipython:: python
 
-    from wetterdienst.dwd.forecasts import DWDMosmixValues, DWDMosmixType
+    from wetterdienst.dwd.forecasts import DWDMosmixStations, DWDMosmixType
 
-    forecast_data = DWDMosmixValues(
-        station_id=stations.all().STATION_ID[0],
+    stations = DWDMosmixStations(
         mosmix_type=DWDMosmixType.LARGE
-    )
+    ).filter(station_id=["01001", "01008"])
 
-    print(forecast_data.all().head())
+    print(stations.values.all().df.head())
diff --git a/example/climate_observations.ipynb b/example/climate_observations.ipynb
diff --git a/example/mosmix_forecasts.py b/example/mosmix_forecasts.py
@@ -13,41 +13,50 @@
 Other MOSMIX variants are also listed and can be
 enabled on demand.
 """
-from wetterdienst.dwd.forecasts import DWDMosmixType, DWDMosmixValues
+from wetterdienst.dwd.forecasts import DWDMosmixStations, DWDMosmixType
 from wetterdienst.dwd.forecasts.metadata.dates import DWDForecastDate
 from wetterdienst.util.cli import setup_logging
 
 
 def mosmix_example():
 
     # A. MOSMIX-L -- Specific stations - each station with own file
-    mosmix = DWDMosmixValues(
-        station_id=["01001", "01008"],
+    request = DWDMosmixStations(
         parameter=["DD", "ww"],
         start_issue=DWDForecastDate.LATEST,  # automatically set if left empty
         mosmix_type=DWDMosmixType.LARGE,
         tidy_data=True,
         humanize_parameters=True,
     )
-    response = next(mosmix.query())
+
+    stations = request.filter(
+        station_id=["01001", "01008"],
+    )
+
+    response = next(stations.values.query())
 
     # meta data enriched with information from metadata_for_forecasts()
-    output_section("Metadata", response.metadata)
-    output_section("Forecasts", response.data)
+    output_section("Metadata", response.stations.df)
+    output_section("Forecasts", response.df)
 
     # B. MOSMIX-S -- All stations - specified stations are extracted.
-    mosmix = DWDMosmixValues(
-        station_id=["01028", "01092"],
+
+    request = DWDMosmixStations(
         parameter=["DD", "ww"],
         start_issue=DWDForecastDate.LATEST,  # automatically set if left empty
         mosmix_type=DWDMosmixType.SMALL,
         tidy_data=True,
         humanize_parameters=True,
     )
-    response = next(mosmix.query())
 
-    output_section("Metadata", response.metadata)
-    output_section("Forecasts", response.data)
+    stations = request.filter(
+        station_id=["01001", "01008"],
+    )
+
+    response = next(stations.values.query())
+
+    output_section("Metadata", response.stations.df)
+    output_section("Forecasts", response.df)
 
 
 def output_section(title, data):  # pragma: no cover