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

meteostat/api/normals.py

@@ -0,0 +1,144 @@
+"""
+Climate Normals
+
+Access climate normals data for one or multiple weather stations.
+"""
+
+from typing import List, Optional
+
+import numpy as np
+import pandas as pd
+
+from meteostat.enumerations import Parameter, Provider, Granularity
+from meteostat.core.schema import schema_service
+from meteostat.api.monthly import DEFAULT_PARAMETERS, monthly
+from meteostat.api.timeseries import TimeSeries
+from meteostat.typing import Station
+from meteostat.api.point import Point
+from meteostat.utils.data import reshape_by_source
+from meteostat.utils.parsers import parse_year
+
+
+def normals(
+    station: str | Station | Point | List[str | Station | Point] | pd.DataFrame,
+    start: int = 1961,
+    end: int = 1990,
+    parameters: Optional[List[Parameter]] = None,
+    providers: Optional[List[Provider]] = None,
+    max_missing: int = 3,
+):
+    """
+    Access climate normals 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 : int, optional
+        Start year for the data query. Defaults to 1961.
+    end : int, optional
+        End year for the data query. Defaults to 1990.
+    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.
+    max_missing : int, optional
+        Maximum number of missing values allowed in a month to calculate the mean. Defaults to 3.
+
+    Returns
+    -------
+    TimeSeries
+        A TimeSeries object containing the climate normals data for the specified
+        stations and parameters.
+    """
+    if parameters is None:
+        parameters = DEFAULT_PARAMETERS
+    if providers is None:
+        providers = [Provider.MONTHLY]
+
+    def _mean(group: pd.Series):
+        """
+        Calculate the monthly mean from multiple years of monthly data
+        """
+        if group.isna().sum() > max_missing:
+            return np.nan
+        return group.mean()
+
+    # Fetch monthly data for the specified stations and parameters
+    ts = monthly(
+        station,
+        parse_year(start),
+        parse_year(end, True),
+        parameters=parameters,
+        providers=providers,
+    )
+    df = ts.fetch(sources=True)
+
+    # Process data if available
+    if df is not None and not df.empty:
+        # Add station level if only a single station is provided
+        if not ts._multi_station:
+            df = pd.concat(
+                [df],
+                keys=[ts.stations.index.get_level_values("id")[0]],
+                names=["station"],
+            )
+
+        # Extract month from time index
+        df["month"] = df.index.get_level_values("time").month
+
+        # Create aggregation functions for different column types
+        agg_funcs = {}
+        for col in df.columns:
+            if col.endswith("_source"):
+                # For source columns, concatenate unique values
+                agg_funcs[col] = lambda x: ", ".join(x.dropna().unique())
+            elif col == "txmx":
+                # For temperature maximum, use max function
+                agg_funcs[col] = lambda x: x.max() if not x.isna().all() else np.nan
+            elif col == "txmn":
+                # For temperature minimum, use min function
+                agg_funcs[col] = lambda x: x.min() if not x.isna().all() else np.nan
+            else:
+                # For data columns, use the mean function
+                agg_funcs[col] = _mean
+
+        # Apply aggregation functions
+        df = df.groupby(["station", "month"]).agg(agg_funcs)
+        df = df.rename_axis(index={"month": "time"})
+
+        # Separate parameter columns from source columns for formatting
+        param_cols = [str(param) for param in parameters if str(param) in df.columns]
+        source_cols = [col for col in df.columns if col.endswith("_source")]
+
+        # Format only the parameter columns
+        if param_cols:
+            df_data = schema_service.format(df[param_cols], Granularity.NORMALS)
+            # Combine formatted parameter columns with unformatted source columns
+            if source_cols:
+                df = pd.concat([df_data, df[source_cols]], axis=1)
+            else:
+                df = df_data
+
+        # Reshape data by source for each station
+        df_fragments = []
+        for s in df.index.get_level_values("station").unique():
+            station_df = df.loc[s]
+            fragment = reshape_by_source(station_df)
+            fragment = pd.concat([fragment], keys=[s], names=["station"])
+            df_fragments.append(fragment)
+
+        df = pd.concat(df_fragments)
+    else:
+        df = None
+
+    # Return the final TimeSeries object
+    return TimeSeries(
+        granularity=Granularity.NORMALS,
+        stations=ts.stations,
+        df=df,
+        start=ts.start,
+        end=ts.end,
+        multi_station=ts._multi_station,
+    )

meteostat/api/point.py

@@ -0,0 +1,30 @@
+"""
+Point Class
+
+A geographical point used for querying nearby weather stations and spatial interpolation.
+"""
+
+from typing import Optional
+
+
+class Point:
+    """
+    A geographical point
+    """
+
+    latitude: float
+    longitude: float
+    elevation: Optional[int]
+
+    def __init__(
+        self, latitude: float, longitude: float, elevation: Optional[int] = None
+    ) -> None:
+        if latitude < -90 or latitude > 90:
+            raise ValueError("Latitude must be between -90 and 90")
+
+        if longitude < -180 or longitude > 180:
+            raise ValueError("Longitude must be between -180 and 180")
+
+        self.latitude = latitude
+        self.longitude = longitude
+        self.elevation = elevation

meteostat/api/stations.py

@@ -0,0 +1,234 @@
+"""
+Stations Module
+
+Provides the Stations class for working with weather station metadata.
+"""
+
+import os
+from typing import List, Optional
+from io import BytesIO
+import sqlite3
+
+import pandas as pd
+
+from requests import Response
+from meteostat.api.inventory import Inventory
+from meteostat.api.point import Point
+from meteostat.core.cache import cache_service
+from meteostat.api.config import config
+from meteostat.core.logger import logger
+from meteostat.core.network import network_service
+from meteostat.enumerations import Provider
+from meteostat.typing import Station
+
+
+class Stations:
+    """
+    Stations Database
+    """
+
+    def _fetch_file(self, stream=False) -> Response:
+        """
+        Download the SQLite database file from the configured URL
+        """
+        urls = config.stations_db_endpoints
+
+        if not urls:
+            raise Exception("No stations database URLs configured")
+
+        response = network_service.get_from_mirrors(urls, stream=stream)
+
+        if response is None:
+            raise Exception("Failed to download the database file")
+
+        return response
+
+    def _get_file_path(self) -> str:
+        """
+        Get the file path for the SQLite database
+        """
+        filepath = config.stations_db_file
+        ttl = config.stations_db_ttl
+
+        if os.path.exists(filepath) and not cache_service.is_stale(filepath, ttl):
+            return filepath
+
+        # Download the database file
+        response = self._fetch_file(stream=True)
+
+        # Create cache directory if it doesn't exist
+        cache_service.create_cache_dir()
+
+        with open(filepath, "wb") as file:
+            for chunk in response.iter_content(chunk_size=8192):
+                file.write(chunk)
+
+        return filepath
+
+    def _connect_memory(self) -> sqlite3.Connection:
+        """
+        Create an in-memory SQLite database and load the downloaded database file into it
+        """
+        # Download the database file
+        response = self._fetch_file()
+
+        # Create an in-memory SQLite database
+        conn = sqlite3.connect(":memory:")
+
+        # Read the downloaded database file into memory
+        content = BytesIO(response.content)
+
+        # Convert bytes to string and write the content to the in-memory database
+        conn.deserialize(content.read())
+
+        return conn
+
+    def _connect_fs(self) -> sqlite3.Connection:
+        """
+        Connect to the SQLite database file on the filesystem
+        """
+        file = self._get_file_path()
+
+        if not file:
+            raise FileNotFoundError("SQLite database file not found")
+
+        conn = sqlite3.connect(file)
+
+        return conn
+
+    def connect(self, in_memory: Optional[bool] = None) -> sqlite3.Connection:
+        """
+        Connect to the database
+        """
+        if in_memory is None:
+            in_memory = config.stations_db_file is None
+
+        logger.info("Connecting to stations database (in_memory=%s)", in_memory)
+
+        if in_memory:
+            return self._connect_memory()
+
+        return self._connect_fs()
+
+    def query(
+        self,
+        sql: str,
+        index_col: Optional[str | list] = None,
+        params: Optional[tuple | dict] = None,
+    ) -> pd.DataFrame:
+        """
+        Execute a SQL query and return the result as a DataFrame
+        """
+        with self.connect() as conn:
+            df = pd.read_sql(sql, conn, index_col=index_col, params=params)
+
+        return df
+
+    def meta(self, station: str) -> Station:
+        """
+        Get meta data for a specific weather station
+        """
+        meta = self.query(
+            """
+            SELECT 
+                `stations`.*,
+                `names`.`name` as `name`
+            FROM `stations` 
+            LEFT JOIN `names` ON `stations`.`id` = `names`.`station` 
+                AND `names`.`language` = 'en'
+            WHERE `stations`.`id` LIKE ?
+            """,
+            index_col="id",
+            params=(station,),
+        ).to_dict("records")[0]
+
+        identifiers = self.query(
+            "SELECT `key`, `value` FROM `identifiers` WHERE `station` LIKE ?",
+            params=(station,),
+        ).to_dict("records")
+
+        return Station(
+            id=station,
+            **meta,
+            identifiers={
+                identifier["key"]: identifier["value"] for identifier in identifiers
+            },
+        )
+
+    def inventory(
+        self, station: str | List[str], providers: Optional[List[Provider]] = None
+    ) -> Inventory:
+        """
+        Get inventory records for a single weather station
+        """
+        query = "SELECT station, provider, parameter, start, end, completeness FROM `inventory`"
+        station_list = station if isinstance(station, list) else [station]
+
+        # Generate the right number of placeholders (?, ?, ?, ...)
+        placeholders = ", ".join(["?"] * len(station_list))
+        # Add the placeholders to the query
+        query += f" WHERE `station`  IN ({placeholders})"
+        # Add the stations to the params
+        params = tuple(station_list)
+
+        if providers:
+            # Generate the right number of placeholders (?, ?, ?, ...)
+            placeholders = ", ".join(["?"] * len(providers))
+            # Add the placeholders to the query
+            query += f" AND provider IN ({placeholders})"
+            # Add the providers to the params
+            params += tuple(providers)
+
+        df = self.query(
+            query, index_col=["station", "provider", "parameter"], params=params
+        )
+
+        return Inventory(df)
+
+    def nearby(self, point: Point, radius=50000, limit=100) -> pd.DataFrame:
+        """
+        Get a list of weather station IDs ordered by distance
+        """
+        return self.query(
+            """
+            SELECT
+                `id`,
+                `names`.`name` as `name`,
+                `country`,
+                `region`,
+                `latitude`,
+                `longitude`,
+                `elevation`,
+                `timezone`,
+                ROUND(
+                    (
+                        6371000 * acos(
+                            cos(radians(:lat)) * cos(radians(`latitude`)) * 
+                            cos(radians(`longitude`) - radians(:lon)) + 
+                            sin(radians(:lat)) * sin(radians(`latitude`))
+                        )
+                    ),
+                    1
+                ) AS `distance`
+            FROM
+                `stations`
+                INNER JOIN `names` ON `stations`.`id` = `names`.`station`
+                AND `names`.`language` = "en"
+            WHERE
+                `distance` <= :radius
+            ORDER BY
+                `distance`
+            LIMIT
+                :limit
+            """,
+            index_col="id",
+            params={
+                "lat": point.latitude,
+                "lon": point.longitude,
+                "radius": radius,
+                "limit": limit,
+            },
+        )
+
+
+stations = Stations()