meteostat 1.7.6__py3-none-any.whl → 2.0.0__py3-none-any.whl

meteostat/__init__.py

@@ -2,34 +2,47 @@
 █▀▄▀█ █▀▀ ▀█▀ █▀▀ █▀█ █▀ ▀█▀ ▄▀█ ▀█▀
 █░▀░█ ██▄ ░█░ ██▄ █▄█ ▄█ ░█░ █▀█ ░█░
 
-A Python library for accessing open weather and climate data
+A Python library for accessing open weather and climate data.
 
 Meteorological data provided by Meteostat (https://dev.meteostat.net)
-under the terms of the Creative Commons Attribution-NonCommercial
-4.0 International Public License.
+under the terms of the Creative Commons Attribution 4.0 International
+License.
 
 The code is licensed under the MIT license.
 """
 
 __appname__ = "meteostat"
-__version__ = "1.7.6"
+__version__ = "2.0.0"
 
-from .interface.base import Base
-from .interface.timeseries import TimeSeries
-from .interface.stations import Stations
-from .interface.point import Point
-from .interface.hourly import Hourly
-from .interface.daily import Daily
-from .interface.monthly import Monthly
-from .interface.normals import Normals
+from meteostat.api.daily import daily
+from meteostat.api.hourly import hourly
+from meteostat.api.interpolate import interpolate
+from meteostat.api.merge import merge
+from meteostat.api.monthly import monthly
+from meteostat.api.normals import normals
+from meteostat.api.point import Point
+from meteostat.api.stations import stations
+from meteostat.core.cache import purge
+from meteostat.core.config import config
+from meteostat.enumerations import Parameter, Provider, UnitSystem
+from meteostat.interpolation.lapserate import lapse_rate
+from meteostat.typing import Station
 
+# Export public API
 __all__ = [
-    "Base",
-    "TimeSeries",
-    "Stations",
+    "config",
+    "daily",
+    "hourly",
+    "interpolate",
+    "lapse_rate",
+    "merge",
+    "monthly",
+    "normals",
+    "Parameter",
     "Point",
-    "Hourly",
-    "Daily",
-    "Monthly",
-    "Normals",
+    "Provider",
+    "purge",
+    "Station",
+    "stations",
+    "UnitSystem",
 ]

meteostat/api/daily.py

@@ -0,0 +1,76 @@
+"""
+Daily Time Series Data
+
+Access daily time series data for one or multiple weather stations.
+"""
+
+from typing import List, Optional
+from datetime import datetime, date
+
+import pandas as pd
+
+from meteostat.core.data import data_service
+from meteostat.enumerations import Parameter, Provider, Granularity
+from meteostat.typing import Station, Request
+from meteostat.api.point import Point
+from meteostat.utils.parsers import parse_station, parse_time
+
+DEFAULT_PARAMETERS = [
+    Parameter.TEMP,
+    Parameter.TMIN,
+    Parameter.TMAX,
+    Parameter.RHUM,
+    Parameter.PRCP,
+    Parameter.SNWD,
+    Parameter.WSPD,
+    Parameter.WPGT,
+    Parameter.PRES,
+    Parameter.TSUN,
+    Parameter.CLDC,
+]
+
+
+def daily(
+    station: str | Station | Point | List[str | Station | Point] | pd.DataFrame,
+    start: Optional[datetime | date],
+    end: Optional[datetime | date],
+    parameters: Optional[List[Parameter]] = None,
+    providers: Optional[List[Provider]] = None,
+):
+    """
+    Access daily time series data.
+
+    Parameters
+    ----------
+    station : str, Station, Point, List[str | Station | Point], pd.Index, pd.Series
+        Weather station(s) or Point(s) to query data for. Can be a single station/point or a list.
+        Points are converted to virtual stations with IDs like $0001, $0002, etc.
+    start : datetime, date, optional
+        Start date for the data query. If None, the earliest available date will be used.
+    end : datetime, date, optional
+        End date for the data query. If None, the latest available date will be used.
+    parameters : List[Parameter], optional
+        List of parameters to include in the data query. Defaults to a set of common parameters.
+    providers : List[Provider], optional
+        List of data providers to use for the query. Defaults to the daily provider.
+
+    Returns
+    -------
+    TimeSeries
+        A TimeSeries object containing the daily data for the specified stations and parameters.
+    """
+    if parameters is None:
+        parameters = DEFAULT_PARAMETERS
+    if providers is None:
+        providers = [Provider.DAILY]
+
+    req = Request(
+        granularity=Granularity.DAILY,
+        providers=providers,
+        parameters=parameters,
+        station=parse_station(station),
+        start=parse_time(start),
+        end=parse_time(end, is_end=True),
+    )
+
+    return data_service.fetch(req)

meteostat/api/hourly.py

@@ -0,0 +1,80 @@
+"""
+Hourly Time Series Data
+
+Access hourly time series data for one or multiple weather stations.
+"""
+
+from typing import List, Optional
+from datetime import datetime, date
+
+import pandas as pd
+
+from meteostat.core.data import data_service
+from meteostat.enumerations import Parameter, Provider, Granularity
+from meteostat.typing import Station, Request
+from meteostat.api.point import Point
+from meteostat.utils.parsers import parse_station, parse_time
+
+DEFAULT_PARAMETERS = [
+    Parameter.TEMP,
+    Parameter.RHUM,
+    Parameter.PRCP,
+    Parameter.SNWD,
+    Parameter.WDIR,
+    Parameter.WSPD,
+    Parameter.WPGT,
+    Parameter.PRES,
+    Parameter.TSUN,
+    Parameter.CLDC,
+    Parameter.COCO,
+]
+
+
+def hourly(
+    station: str | Station | Point | List[str | Station | Point] | pd.DataFrame,
+    start: Optional[datetime | date],
+    end: Optional[datetime | date],
+    timezone: Optional[str] = None,
+    parameters: Optional[List[Parameter]] = None,
+    providers: Optional[List[Provider]] = None,
+):
+    """
+    Access hourly time series data.
+
+    Parameters
+    ----------
+    station : str, Station, Point, List[str | Station | Point], pd.Index, pd.Series
+        Weather station(s) or Point(s) to query data for. Can be a single station/point or a list.
+        Points are converted to virtual stations with IDs like $0001, $0002, etc.
+    start : datetime, date, optional
+        Start date for the data query. If None, the earliest available date will be used.
+    end : datetime, date, optional
+        End date for the data query. If None, the latest available date will be used.
+    timezone : str, optional
+        Time zone for the data query. If None, UTC will be used.
+    parameters : List[Parameter], optional
+        List of parameters to include in the data query. Defaults to a set of common parameters.
+    providers : List[Provider], optional
+        List of data providers to use for the query. Defaults to the hourly provider.
+
+    Returns
+    -------
+    TimeSeries
+        A TimeSeries object containing the hourly data for the specified stations and parameters.
+    """
+    if parameters is None:
+        parameters = DEFAULT_PARAMETERS
+    if providers is None:
+        providers = [Provider.HOURLY]
+
+    req = Request(
+        granularity=Granularity.HOURLY,
+        providers=providers,
+        parameters=parameters,
+        station=parse_station(station),
+        start=parse_time(start, timezone),
+        end=parse_time(end, timezone, is_end=True),
+        timezone=timezone,
+    )
+
+    return data_service.fetch(req)

meteostat/api/interpolate.py

@@ -0,0 +1,240 @@
+"""
+Interpolation Module
+
+Provides spatial interpolation functions for meteorological data.
+"""
+
+from typing import Optional, Union
+
+import numpy as np
+import pandas as pd
+
+from meteostat.api.point import Point
+from meteostat.api.timeseries import TimeSeries
+from meteostat.typing import Station
+from meteostat.interpolation.lapserate import apply_lapse_rate
+from meteostat.interpolation.nearest import nearest_neighbor
+from meteostat.interpolation.idw import inverse_distance_weighting
+from meteostat.utils.data import aggregate_sources, reshape_by_source, stations_to_df
+from meteostat.utils.geo import get_distance
+from meteostat.utils.parsers import parse_station
+
+
+def _create_timeseries(
+    ts: TimeSeries, point: Point, df: Optional[pd.DataFrame] = None
+) -> TimeSeries:
+    """
+    Create a TimeSeries object from interpolated DataFrame
+    """
+    parsed = parse_station(point)
+    stations_list = [parsed] if isinstance(parsed, Station) else parsed
+
+    # Convert stations to DataFrame
+    stations_df = stations_to_df(stations_list)
+
+    return TimeSeries(
+        ts.granularity,
+        stations_df,
+        df=df,
+        start=ts.start,
+        end=ts.end,
+        timezone=ts.timezone,
+    )
+
+
+def _add_source_columns(
+    result: pd.DataFrame,
+    df: pd.DataFrame,
+) -> pd.DataFrame:
+    """
+    Add source columns to the result DataFrame
+    """
+    source_cols = [c for c in df.columns if c.endswith("_source")]
+    if source_cols:
+        grouped = df.groupby("time")[source_cols].agg(aggregate_sources)
+        if isinstance(grouped, pd.Series):
+            grouped = grouped.to_frame(name=source_cols[0])
+        grouped.index.name = "time"
+
+        # Safely align on time and add/fill source columns without causing overlaps
+        result_has_time_col = "time" in result.columns
+        if result_has_time_col:
+            result = result.set_index("time")
+
+        # Ensure both frames align on the same index (time)
+        # For each source column, add it if missing or fill NaNs if present
+        for col in source_cols:
+            if col in grouped.columns:
+                if col in result.columns:
+                    # Fill missing values in result using aggregated sources
+                    result[col] = result[col].where(result[col].notna(), grouped[col])
+                else:
+                    # Add aggregated source column
+                    result[col] = grouped[col]
+
+        if result_has_time_col:
+            result = result.reset_index()
+    return result
+
+
+def interpolate(
+    ts: TimeSeries,
+    point: Point,
+    distance_threshold: Union[int, None] = 5000,
+    elevation_threshold: Union[int, None] = 50,
+    elevation_weight: float = 10,
+    power: float = 2.0,
+    lapse_rate: Union[float, None] = 6.5,
+    lapse_rate_threshold: int = 50,
+) -> TimeSeries:
+    """
+    Interpolate time series data spatially to a specific point.
+
+    Parameters
+    ----------
+    ts : TimeSeries
+        The time series to interpolate.
+    point : Point
+        The point to interpolate the data for.
+    distance_threshold : int, optional
+        Maximum distance (in meters) to use nearest neighbor (default: 5000).
+        Beyond this, IDW is used.
+    elevation_threshold : int, optional
+        Maximum elevation difference (in meters) to use nearest neighbor (default: 50).
+        Beyond this, IDW is used even if distance is within threshold.
+    elevation_weight : float, optional
+        Weight for elevation difference in distance calculation (default: 0.1).
+        The effective distance is calculated as:
+        sqrt(horizontal_distance^2 + (elevation_diff * elevation_weight)^2)
+    power : float, optional
+        Power parameter for IDW (default: 2.0). Higher values give more
+        weight to closer stations.
+    lapse_rate : float, optional
+        Apply lapse rate correction based on elevation difference (default: 6.5).
+    lapse_rate_threshold : int, optional
+        Elevation difference threshold (in meters) to apply lapse rate correction
+        (default: 50). If the elevation difference between the point and stations
+        is less than this, no correction is applied.
+
+    Returns
+    -------
+    pd.DataFrame or None
+        A DataFrame containing the interpolated data for the specified point,
+        or None if no data is available.
+    """
+    # Fetch DataFrame, filling missing values and adding location data
+    df = ts.fetch(fill=True, location=True, sources=True)
+
+    # If no data is returned, return None
+    if df is None:
+        return _create_timeseries(ts, point)
+
+    # Add distance column
+    df["distance"] = get_distance(
+        point.latitude, point.longitude, df["latitude"], df["longitude"]
+    )
+
+    # Add effective distance column if elevation is available
+    if point.elevation is not None and "elevation" in df.columns:
+        elev_diff = np.abs(df["elevation"] - point.elevation)
+        df["effective_distance"] = np.sqrt(
+            df["distance"] ** 2 + (elev_diff * elevation_weight) ** 2
+        )
+    else:
+        df["effective_distance"] = df["distance"]
+
+    # Add elevation difference column
+    if "elevation" in df.columns and point.elevation is not None:
+        df["elevation_diff"] = np.abs(df["elevation"] - point.elevation)
+    else:
+        df["elevation_diff"] = np.nan
+
+    # Apply lapse rate if specified and elevation is available
+    if (
+        lapse_rate
+        and point.elevation
+        and df["elevation_diff"].max() >= lapse_rate_threshold
+    ):
+        df = apply_lapse_rate(df, point.elevation, lapse_rate)
+
+    # Check if any stations are close enough for nearest neighbor
+    min_distance = df["distance"].min()
+    use_nearest = distance_threshold is None or min_distance <= distance_threshold
+    if use_nearest and point.elevation is not None and "elevation" in df.columns:
+        # Calculate minimum elevation difference
+        min_elev_diff = np.abs(df["elevation"] - point.elevation).min()
+        use_nearest = (
+            elevation_threshold is None or min_elev_diff <= elevation_threshold
+        )
+
+    # Initialize variables
+    df_nearest = None
+    df_idw = None
+
+    # Perform nearest neighbor if applicable
+    if use_nearest:
+        # Filter applicable stations based on thresholds
+        distance_filter = (
+            pd.Series([True] * len(df), index=df.index)
+            if distance_threshold is None
+            else (df["distance"] <= distance_threshold)
+        )
+        elevation_filter = (
+            pd.Series([True] * len(df), index=df.index)
+            if elevation_threshold is None
+            else (np.abs(df["elevation"] - point.elevation) <= elevation_threshold)
+        )
+        df_filtered = df[distance_filter & elevation_filter]
+        df_nearest = nearest_neighbor(df_filtered, ts, point)
+
+    # Check if we need to use IDW
+    if (
+        not use_nearest
+        or df_nearest is None
+        or len(df_nearest) == 0
+        or df_nearest.isna().any().any()
+    ):
+        # Perform IDW interpolation
+        idw_func = inverse_distance_weighting(power=power)
+        df_idw = idw_func(df, ts, point)
+
+    # Merge DataFrames with priority to nearest neighbor
+    if use_nearest and df_nearest is not None and len(df_nearest) > 0:
+        if df_idw is not None:
+            # Combine nearest and IDW results, prioritizing nearest values
+            result = df_nearest.combine_first(df_idw)
+        else:
+            result = df_nearest
+    else:
+        result = df_idw
+
+    # If no data is returned, return None
+    if result is None or result.empty:
+        return _create_timeseries(ts, point)
+
+    # Drop location-related columns & return
+    result = result.drop(
+        [
+            "latitude",
+            "longitude",
+            "elevation",
+            "distance",
+            "effective_distance",
+            "elevation_diff",
+        ],
+        axis=1,
+    )
+
+    # Add source columns: aggregate all columns that end with "_source"
+    result = _add_source_columns(result, df)
+
+    # Reshape by source
+    result = reshape_by_source(result)
+
+    # Add station index
+    result["station"] = "$0001"
+    result = result.set_index("station", append=True).reorder_levels(
+        ["station", "time", "source"]
+    )
+
+    return _create_timeseries(ts, point, result)

meteostat/api/inventory.py

@@ -0,0 +1,59 @@
+"""
+Inventory Module
+
+Provides classes for working with weather station data inventories.
+"""
+
+from datetime import date, datetime
+from typing import List, Optional
+
+import pandas as pd
+
+from meteostat.enumerations import Parameter
+
+
+class Inventory:
+    """
+    A weather station's data inventory
+    """
+
+    df: Optional[pd.DataFrame] = None
+
+    def __init__(self, df: Optional[pd.DataFrame] = None):
+        if df is not None and not df.empty:
+            self.df = df
+
+    @property
+    def start(self) -> Optional[date]:
+        """
+        Get the earliest start date from the inventory
+        """
+        return (
+            datetime.strptime(self.df["start"].min(), "%Y-%m-%d").date()
+            if self.df is not None
+            else None
+        )
+
+    @property
+    def end(self) -> Optional[date]:
+        """
+        Get the latest end date from the inventory
+        """
+        return (
+            datetime.strptime(self.df["end"].max(), "%Y-%m-%d").date()
+            if self.df is not None
+            else None
+        )
+
+    @property
+    def parameters(self) -> Optional[List[Parameter]]:
+        """
+        Get the list of available parameters from the inventory
+        """
+        if self.df is None:
+            return []
+
+        return [
+            Parameter[parameter.upper()]
+            for parameter in self.df.index.get_level_values("parameter").unique()
+        ]

meteostat/api/merge.py

@@ -0,0 +1,103 @@
+"""
+Concatenation Module
+
+Provides functions to concatenate multiple time series objects into one.
+"""
+
+from copy import copy
+from datetime import datetime
+from typing import List, Optional
+
+import pandas as pd
+
+from meteostat.core.data import data_service
+from meteostat.core.schema import schema_service
+from meteostat.api.timeseries import TimeSeries
+
+
+def _get_dt(
+    dt_a: Optional[datetime], dt_b: Optional[datetime], start=True
+) -> Optional[datetime]:
+    """
+    Return the earlier or later (depending on "start" argument) of two datetimes,
+    considering None as 'no value'.
+
+    If both are None, return None.
+    """
+    if dt_a is None:
+        return dt_b
+    if dt_b is None:
+        return dt_a
+    return min(dt_a, dt_b) if start else max(dt_a, dt_b)
+
+
+def merge(objs: List[TimeSeries]) -> TimeSeries:
+    """
+    Merge one or multiple Meteostat time series into a common one
+
+    In case of duplicate index, the last row will be prefered.
+    Hence, please pass newest data last.
+
+    Parameters
+    ----------
+    objs : List[TimeSeries]
+        List of time series objects to concatenate
+
+    Returns
+    -------
+    TimeSeries
+        Concatenated time series object
+
+    Raises
+    ------
+    ValueError
+        If the time series objects have divergent granularity or time zone
+    """
+    ts = objs[0]
+
+    if not all(
+        obj.granularity == ts.granularity and obj.timezone == ts.timezone
+        for obj in objs[1:]
+    ):
+        raise ValueError(
+            "Can't concatenate time series objects with divergent granularity or time zone"
+        )
+
+    stations = copy(ts.stations)
+    start = copy(ts.start)
+    end = copy(ts.end)
+    parameters = ts.parameters
+    multi_station = ts._multi_station
+
+    for obj in objs[1:]:
+        stations = (
+            pd.concat([stations, obj.stations])
+            .reset_index()
+            .drop_duplicates(subset=["id"])
+            .set_index("id")
+        )
+        start = _get_dt(start, obj.start)
+        end = _get_dt(end, obj.end, False)
+        parameters.extend(obj.parameters)
+        if (
+            obj._multi_station
+            or stations.index.get_level_values("id")[0]
+            != obj.stations.index.get_level_values("id")[0]
+        ):
+            multi_station = True
+
+    df = data_service.concat_fragments(
+        [obj._df for obj in objs if obj._df is not None],
+        list(dict.fromkeys(parameters)),
+    )
+    df = schema_service.format(df, ts.granularity)
+
+    return TimeSeries(
+        ts.granularity,
+        stations,
+        df,
+        start,
+        end,
+        ts.timezone,
+        multi_station=multi_station,
+    )

meteostat/api/monthly.py

@@ -0,0 +1,73 @@
+"""
+Monthly Time Series Data
+
+Access monthly time series data for one or multiple weather stations.
+"""
+
+from typing import List, Optional
+from datetime import datetime, date
+
+import pandas as pd
+
+from meteostat.core.data import data_service
+from meteostat.enumerations import Parameter, Provider, Granularity
+from meteostat.typing import Station, Request
+from meteostat.api.point import Point
+from meteostat.utils.parsers import parse_station, parse_time
+
+DEFAULT_PARAMETERS = [
+    Parameter.TEMP,
+    Parameter.TMIN,
+    Parameter.TMAX,
+    Parameter.TXMN,
+    Parameter.TXMX,
+    Parameter.PRCP,
+    Parameter.PRES,
+    Parameter.TSUN,
+]
+
+
+def monthly(
+    station: str | Station | Point | List[str | Station | Point] | pd.DataFrame,
+    start: Optional[datetime | date],
+    end: Optional[datetime | date],
+    parameters: Optional[List[Parameter]] = None,
+    providers: Optional[List[Provider]] = None,
+):
+    """
+    Access monthly time series data.
+
+    Parameters
+    ----------
+    station : str, Station, Point, List[str | Station | Point], pd.Index, pd.Series
+        Weather station(s) or Point(s) to query data for. Can be a single station/point or a list.
+        Points are converted to virtual stations with IDs like $0001, $0002, etc.
+    start : datetime, date, optional
+        Start date for the data query. If None, the earliest available date will be used.
+    end : datetime, date, optional
+        End date for the data query. If None, the latest available date will be used.
+    parameters : List[Parameter], optional
+        List of parameters to include in the data query. Defaults to a set of common parameters.
+    providers : List[Provider], optional
+        List of data providers to use for the query. Defaults to the monthly provider.
+
+    Returns
+    -------
+    TimeSeries
+        A TimeSeries object containing the monthly data for the specified stations and parameters.
+    """
+    if parameters is None:
+        parameters = DEFAULT_PARAMETERS
+    if providers is None:
+        providers = [Provider.MONTHLY]
+
+    req = Request(
+        granularity=Granularity.MONTHLY,
+        providers=providers,
+        parameters=parameters,
+        station=parse_station(station),
+        start=parse_time(start),
+        end=parse_time(end, is_end=True),
+    )
+
+    return data_service.fetch(req)