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

meteostat/utils/conversions.py

@@ -0,0 +1,231 @@
+"""
+Functions for converting between different
+meteorological data units.
+
+The code is licensed under the MIT license.
+"""
+
+import math
+from typing import Optional
+
+from numpy import isnan
+
+from meteostat.enumerations import Parameter, Unit, UnitSystem
+
+
+def celsius_to_fahrenheit(value):
+    """
+    Convert Celsius to Fahrenheit
+    """
+
+    return round((value * 9 / 5) + 32, 1)
+
+
+def celsius_to_kelvin(value):
+    """
+    Convert Celsius to Kelvin
+    """
+
+    return round(value + 273.15, 1)
+
+
+def millimeters_to_inches(value):
+    """
+    Convert millimeters to inches
+    """
+
+    return round(value / 25.4, 3)
+
+
+def centimeters_to_inches(value):
+    """
+    Convert centimeters to inches
+    """
+
+    return round(value / 2.54, 3)
+
+
+def meters_to_feet(value):
+    """
+    Convert meters to feet
+    """
+
+    return round(value / 0.3048, 1)
+
+
+def kmh_to_ms(value):
+    """
+    Convert kilometers per hour to meters per second
+    """
+
+    return round(value / 3.6, 1)
+
+
+def kmh_to_mph(value):
+    """
+    Convert kilometers per hour to miles per hour
+    """
+
+    return round(value * 0.6214, 1)
+
+
+def kelvin_to_celsius(value):
+    """
+    Convert Kelvin to Celsius
+    """
+    return value - 273.15 if value is not None and not isnan(value) else None
+
+
+def ms_to_kmh(value):
+    """
+    Convert m/s to km/h
+    """
+    return value * 3.6 if value is not None and not isnan(value) else None
+
+
+def temp_dwpt_to_rhum(row: dict):
+    """
+    Get relative humidity from temperature and dew point
+    """
+    return (
+        100
+        * (
+            math.exp((17.625 * row["dwpt"]) / (243.04 + row["dwpt"]))
+            / math.exp((17.625 * row["temp"]) / (243.04 + row["temp"]))
+        )
+        if row["temp"] is not None and row["dwpt"] is not None
+        else None
+    )
+
+
+def pres_to_msl(row: dict, altitude: Optional[int] = None, temp: str = Parameter.TEMP):
+    """
+    Convert local air pressure to MSL
+    """
+    try:
+        return (
+            None
+            if (
+                not row[Parameter.PRES]
+                or not row[temp]
+                or not altitude
+                or row[Parameter.PRES] == -999
+            )
+            else round(
+                row[Parameter.PRES]
+                * math.pow(
+                    (
+                        1
+                        - (
+                            (0.0065 * altitude)
+                            / (row[temp] + 0.0065 * altitude + 273.15)
+                        )
+                    ),
+                    -5.257,
+                ),
+                1,
+            )
+        )
+    except Exception:
+        return None
+
+
+def percentage_to_okta(value):
+    """
+    Convert cloud cover percentage to oktas
+    """
+    return round(value / 12.5) if value is not None and not isnan(value) else None
+
+
+def jcm2_to_wm2(value):
+    """
+    Convert Joule/CM^2 to Watt/M^2
+    """
+    return round(value * 2.78) if value is not None and not isnan(value) else None
+
+
+def to_direction(value):
+    """
+    Convert degrees to wind direction
+    """
+
+    wdir = None
+
+    if (337 <= value <= 360) or value <= 23:
+        wdir = "N"
+    if 24 <= value <= 68:
+        wdir = "NE"
+    if 69 <= value <= 113:
+        wdir = "E"
+    if 114 <= value <= 158:
+        wdir = "SE"
+    if 159 <= value <= 203:
+        wdir = "S"
+    if 204 <= value <= 248:
+        wdir = "SW"
+    if 249 <= value <= 293:
+        wdir = "W"
+    if 294 <= value <= 336:
+        wdir = "NW"
+
+    return wdir
+
+
+def to_condition(value):
+    """
+    Convert Meteostat condition code to descriptive string
+    """
+
+    if not value or value < 1 or value > 27:
+        return None
+
+    return [
+        "Clear",
+        "Fair",
+        "Cloudy",
+        "Overcast",
+        "Fog",
+        "Freezing Fog",
+        "Light Rain",
+        "Rain",
+        "Heavy Rain",
+        "Freezing Rain",
+        "Heavy Freezing Rain",
+        "Sleet",
+        "Heavy Sleet",
+        "Light Snowfall",
+        "Snowfall",
+        "Heavy Snowfall",
+        "Rain Shower",
+        "Heavy Rain Shower",
+        "Sleet Shower",
+        "Heavy Sleet Shower",
+        "Snow Shower",
+        "Heavy Snow Shower",
+        "Lightning",
+        "Hail",
+        "Thunderstorm",
+        "Heavy Thunderstorm",
+        "Storm",
+    ][int(value) - 1]
+
+
+CONVERSION_MAPPINGS = {
+    Unit.CELSIUS: {
+        UnitSystem.IMPERIAL: celsius_to_fahrenheit,
+        UnitSystem.SI: celsius_to_kelvin,
+    },
+    Unit.MILLIMETERS: {
+        UnitSystem.IMPERIAL: millimeters_to_inches,
+    },
+    Unit.CENTIMETERS: {
+        UnitSystem.IMPERIAL: centimeters_to_inches,
+    },
+    Unit.KMH: {
+        UnitSystem.SI: kmh_to_ms,
+        UnitSystem.IMPERIAL: kmh_to_mph,
+    },
+    Unit.METERS: {
+        UnitSystem.IMPERIAL: meters_to_feet,
+    },
+}

meteostat/utils/data.py

@@ -0,0 +1,194 @@
+"""
+DataFrame mutations
+
+Meteorological data provided by Meteostat (https://dev.meteostat.net)
+under the terms of the Creative Commons Attribution-NonCommercial
+4.0 International Public License.
+
+The code is licensed under the MIT license.
+"""
+
+from collections import Counter
+from datetime import datetime
+from itertools import chain
+from typing import List
+
+import numpy as np
+import pandas as pd
+
+from meteostat.core.providers import provider_service
+from meteostat.enumerations import Frequency
+from meteostat.typing import Station
+
+
+def stations_to_df(stations: List[Station]) -> pd.DataFrame:
+    """
+    Convert list of stations to DataFrame
+    """
+    assert len(stations) > 0 and all(
+        isinstance(station, Station) for station in stations
+    )
+
+    return pd.DataFrame.from_records(
+        [
+            {
+                "id": station.id,
+                "name": station.name,
+                "country": station.country,
+                "latitude": station.latitude,
+                "longitude": station.longitude,
+                "elevation": station.elevation,
+                "timezone": station.timezone,
+            }
+            for station in stations
+        ],
+        index="id",
+    )
+
+
+def squash_df(df: pd.DataFrame, sources=False) -> pd.DataFrame:
+    """
+    Squash a DataFrame based on the source priority
+    """
+    # Capture the columns
+    columns = df.columns
+
+    # Add source priority column
+    df["source_prio"] = df.index.get_level_values("source").map(
+        provider_service.get_source_priority
+    )
+
+    # Shift source information to columns
+    if sources:
+        df = df.reset_index(level="source")
+        for column in columns:
+            df[f"{column}_source"] = np.where(df[column].notna(), df["source"], np.nan)
+        df = df.set_index("source", append=True)
+
+    # Get highest priority value/source for each station and time
+    df = (
+        df.groupby(level=["station", "time", "source"])
+        .last()  # In case of duplicate index, the last row will be prefered
+        .sort_values(by="source_prio", ascending=False)
+        .groupby(["station", "time"])
+        .first()  # Prefer value with highest priority
+        .drop("source_prio", axis=1)
+    )
+
+    # Order columns and return squashed DataFrame
+    return df[order_source_columns(df.columns)] if sources else df
+
+
+def fill_df(
+    df: pd.DataFrame, start: datetime, end: datetime, freq: str
+) -> pd.DataFrame:
+    """
+    Fill a DataFrame with a complete date range for each station
+    """
+    try:
+        iterables = [
+            df.index.get_level_values("station").unique(),
+            pd.date_range(start=start, end=end, freq=freq),
+        ]
+        names = ["station", "time"]
+        if "source" in df.index.names:
+            iterables.append(df.index.get_level_values("source").unique())
+            names.append("source")
+        # Create a new MultiIndex with every hour for each station
+        new_index = pd.MultiIndex.from_product(iterables, names=names)
+
+        # Reindex the DataFrame to add missing rows
+        df = df.reindex(index=new_index)
+        return df
+    except KeyError:
+        return df
+
+
+def localize(df: pd.DataFrame, timezone: str) -> pd.DataFrame:
+    """
+    Convert time data to any time zone
+    """
+    return df.tz_localize("UTC", level="time").tz_convert(timezone, level="time")
+
+
+def reshape_by_source(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Reshape a DataFrame so that the source columns are pivoted into
+    their own level of the index
+    """
+    # Extract value rows and source rows
+    value_rows = df.loc[:, ~df.columns.str.endswith("_source")]
+    source_rows = df.loc[:, df.columns.str.endswith("_source")]
+
+    # Melt both value_rows and source_rows
+    value_melted = value_rows.reset_index().melt(id_vars="time")
+    source_melted = source_rows.reset_index().melt(id_vars="time")
+
+    # Remove '_source' from the variable names in source_melted
+    source_melted["variable"] = source_melted["variable"].str.replace("_source", "")
+
+    # Merge the melted DataFrames
+    merged_df = pd.merge(
+        value_melted, source_melted, on=["time", "variable"], suffixes=("", "_source")
+    )
+
+    # Drop rows with missing values
+    merged_df = merged_df.dropna(subset=["value"])
+
+    # Pivot the DataFrame
+    df_pivoted = merged_df.pivot(
+        index=["time", "value_source"], columns="variable", values="value"
+    )
+
+    # Flatten the MultiIndex
+    df_pivoted.index = df_pivoted.index.rename(["time", "source"])
+    df_pivoted.columns.name = None
+
+    # Preserve the original parameter column order from value_rows
+    # Pivot often produces alphabetical column order; reindex to match input
+    ordered_columns = [col for col in value_rows.columns if col in df_pivoted.columns]
+    if ordered_columns:
+        df_pivoted = df_pivoted.reindex(columns=ordered_columns)
+
+    return df_pivoted
+
+
+def aggregate_sources(series: pd.Series) -> str:
+    """
+    Concatenate multiple data sources into a unique source string,
+    ordered by the number of occurrences.
+    """
+    # Extract sources and flatten them
+    sources = [str(item) for item in series if pd.notna(item)]
+    flat_sources = list(chain(*[source.split() for source in sources]))
+
+    # Count occurrences of each source
+    source_counts = Counter(flat_sources)
+
+    # Sort sources by count in descending order
+    sorted_sources = sorted(source_counts, key=lambda s: source_counts[s], reverse=True)
+
+    # Concatenate sorted sources into a unique source string
+    return " ".join(sorted_sources)
+
+
+def enforce_freq(df: pd.DataFrame, freq: Frequency) -> pd.DataFrame:
+    """
+    Enforce a specific frequency on a DataFrame by resampling
+    """
+    df.index = pd.to_datetime(df.index.get_level_values("time"))
+    return df.resample(freq).first()
+
+
+def order_source_columns(columns: pd.Index) -> List[str]:
+    """
+    Order source columns
+    """
+    ordered_columns = []
+
+    for col in columns:
+        if not col.endswith("_source"):
+            ordered_columns.append(col)
+            ordered_columns.append(f"{col}_source")
+
+    return ordered_columns

meteostat/utils/geo.py

@@ -0,0 +1,28 @@
+"""
+Utilities for geographical calculations.
+
+The code is licensed under the MIT license.
+"""
+
+import numpy as np
+
+
+def get_distance(lat1, lon1, lat2, lon2) -> int:
+    """
+    Calculate distance between two geographical points using the Haversine formula
+    """
+    # Earth radius in meters
+    radius = 6371000
+
+    # Degress to radian
+    lat1, lon1, lat2, lon2 = map(np.deg2rad, [lat1, lon1, lat2, lon2])
+
+    # Deltas
+    dlat = lat2 - lat1
+    dlon = lon2 - lon1
+
+    # Calculate distance
+    arch = np.sin(dlat / 2) ** 2 + np.cos(lat1) * np.cos(lat2) * np.sin(dlon / 2) ** 2
+    arch_sin = 2 * np.arcsin(np.sqrt(arch))
+
+    return round(radius * arch_sin)

meteostat/utils/guards.py

@@ -0,0 +1,51 @@
+"""
+Guard functions for Meteostat.
+
+The code is licensed under the MIT license.
+"""
+
+from datetime import datetime
+from meteostat.api.config import config
+from meteostat.core.logger import logger
+from meteostat.enumerations import Granularity
+from meteostat.typing import Request
+
+
+def request_size_guard(req: Request) -> None:
+    """
+    Guard to block large requests
+    """
+    if not config.block_large_requests:
+        logger.debug("Large request blocking is disabled.")
+        return
+
+    if isinstance(req.station, list) and len(req.station) > 10:
+        raise ValueError(
+            "Requests with more than 10 stations are blocked by default. "
+            "To enable large requests, set `config.block_large_requests = False`."
+        )
+
+    if req.granularity not in [Granularity.HOURLY, Granularity.DAILY]:
+        return
+
+    if req.start is None:
+        raise ValueError(
+            "Hourly and daily requests without a start date are blocked by default. "
+            "To enable large requests, set `config.block_large_requests = False`."
+        )
+
+    time_diff_years = abs((req.end or datetime.now()).year - req.start.year)
+
+    logger.debug(f"Request time range: {time_diff_years} years.")
+
+    if req.granularity is Granularity.HOURLY and time_diff_years > 3:
+        raise ValueError(
+            "Hourly requests longer than 3 years are blocked by default. "
+            "To enable large requests, set `config.block_large_requests = False`."
+        )
+
+    if req.granularity is Granularity.DAILY and time_diff_years > 30:
+        raise ValueError(
+            "Daily requests longer than 30 years are blocked by default. "
+            "To enable large requests, set `config.block_large_requests = False`."
+        )

meteostat/utils/parsers.py

@@ -0,0 +1,161 @@
+"""
+Data parsers
+
+The code is licensed under the MIT license.
+"""
+
+import calendar
+from typing import List
+import datetime
+
+import pandas as pd
+import pytz
+
+from meteostat.api.stations import stations as stations_service
+from meteostat.api.point import Point
+from meteostat.typing import Station
+
+
+def parse_station(
+    station: (str | Station | Point | List[str | Station | Point] | pd.DataFrame),
+) -> Station | List[Station]:
+    """
+    Parse one or multiple station(s) or geo point(s)
+
+    Point objects are converted to virtual stations with IDs like $0001, $0002, etc.
+    based on their position in the input list.
+
+    Returns
+    -------
+    Station | List[Station]
+        - Returns a single Station object for single-station input (str, Station, Point)
+        - Returns a list of Station objects for multi-station input (list, pd.Index, etc.)
+    """
+    # Return data if it contains station meta data (single station)
+    if isinstance(station, Station):
+        return station
+
+    # Handle Point objects (single point)
+    if isinstance(station, Point):
+        return _point_to_station(station, 1)
+
+    # Handle string (single station ID)
+    if isinstance(station, str):
+        meta = stations_service.meta(station)
+        if meta is None:
+            raise ValueError(f'Weather station with ID "{station}" could not be found')
+        return meta
+
+    # Convert station identifier(s) to list (multi-station)
+    if isinstance(station, pd.DataFrame):
+        stations = station.index.tolist()
+    else:
+        # It's a list
+        stations = station
+
+    # Get station meta data
+    data = []
+    point_counter = 0
+    for s in stations:
+        # Append data early if it contains station meta data
+        if isinstance(s, Station):
+            data.append(s)
+            continue
+        # Handle Point objects
+        if isinstance(s, Point):
+            point_counter += 1
+            data.append(_point_to_station(s, point_counter))
+            continue
+        # Get station meta data
+        meta = stations_service.meta(s)
+        # Raise exception if station could not be found
+        if meta is None:
+            raise ValueError(f'Weather station with ID "{s}" could not be found')
+        # Append station meta data
+        data.append(meta)
+
+    # Return list of station meta data
+    return data
+
+
+def _point_to_station(point: Point, index: int) -> Station:
+    """
+    Convert a Point object to a virtual Station object
+
+    Parameters
+    ----------
+    point : Point
+        The Point object to convert
+    index : int
+        The position in the list of points (1-indexed)
+
+    Returns
+    -------
+    Station
+        A virtual Station object with an ID like $0001
+    """
+    # Create virtual station ID
+    station_id = f"${index:04d}"
+
+    # Create Station object with extracted coordinates
+    return Station(
+        id=station_id,
+        name=f"Location #{index}",
+        latitude=point.latitude,
+        longitude=point.longitude,
+        elevation=point.elevation,
+    )
+
+
+def parse_time(
+    value: datetime.date | datetime.datetime | None,
+    timezone: str | None = None,
+    is_end: bool = False,
+) -> datetime.datetime | None:
+    """
+    Convert a given date/time input to datetime
+
+    To set the time of a date to 23:59:59, pass is_end=True
+    """
+    if not value:
+        return None
+
+    if not isinstance(value, datetime.datetime):
+        parsed = datetime.datetime.combine(
+            value,
+            datetime.datetime.max.time() if is_end else datetime.datetime.min.time(),
+        )
+    else:
+        parsed = value
+
+    if timezone:
+        tz = pytz.timezone(timezone)
+        # If the datetime is already aware, convert it directly
+        # If it's naive, treat it as being in the target timezone
+        if parsed.tzinfo is not None:
+            parsed = parsed.astimezone(pytz.utc).replace(tzinfo=None)
+        else:
+            parsed = tz.localize(parsed).astimezone(pytz.utc).replace(tzinfo=None)
+
+    return parsed
+
+
+def parse_month(
+    value: datetime.date | datetime.datetime | None, is_end: bool = False
+) -> datetime.date | None:
+    """
+    Convert a given date/time input to the first or last day of the month respectively
+    """
+    if not value:
+        return None
+
+    last_day = calendar.monthrange(value.year, value.month)[1]
+
+    return datetime.date(value.year, value.month, last_day if is_end else 1)
+
+
+def parse_year(year: int, is_end: bool = False) -> datetime.date:
+    """
+    Parse a year into a date, returning either the first or last day of the year
+    """
+    return datetime.date(year, 12, 31) if is_end else datetime.date(year, 1, 1)