climatewatches 1.0.1__tar.gz

climatewatches-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andriamihaja R.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

climatewatches-1.0.1/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: climatewatches
+Version: 1.0.1
+Summary: Climate data monitoring and visualization for temporal and spatial dataset
+Author-email: "Andriamihaja R." <andriamihajaranaivoson@yahoo.fr>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Dihj/climatewatches
+Project-URL: Repository, https://github.com/Dihj/climatewatches
+Project-URL: Issues, https://github.com/Dihj/climatewatches/issues
+Keywords: climate,meteorology,rainfall,temperature,cyclone,climatewatches
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cartopy
+Requires-Dist: geopandas
+Requires-Dist: geopy
+Requires-Dist: matplotlib<3.11,>=3.8
+Requires-Dist: netCDF4
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: rasterio
+Requires-Dist: rioxarray
+Requires-Dist: scipy
+Requires-Dist: shapely
+Requires-Dist: xarray
+Dynamic: license-file
+
+# climatewatches
+
+`climatewatches` is a small Python toolkit for climate bulletin monitoring and
+visualization. It includes station monitoring plots, rainfall and temperature
+maps, climatology maps, tropical cyclone monitoring, and large-scale climate
+driver diagnostics.
+
+## Installation
+
+```bash
+pip install climatewatches
+```
+
+## Documentation
+
+See on the wiki page on this repository. 

climatewatches-1.0.1/README.md

@@ -0,0 +1,16 @@
+# climatewatches
+
+`climatewatches` is a small Python toolkit for climate bulletin monitoring and
+visualization. It includes station monitoring plots, rainfall and temperature
+maps, climatology maps, tropical cyclone monitoring, and large-scale climate
+driver diagnostics.
+
+## Installation
+
+```bash
+pip install climatewatches
+```
+
+## Documentation
+
+See on the wiki page on this repository. 

climatewatches-1.0.1/climatewatches/__init__.py

@@ -0,0 +1,100 @@
+"""ClimateWatches is a Python toolkit for climate bulletin monitoring and visualization."""
+
+__version__ = "1.0.1"
+
+_EXPORTS = {
+    "plot_precip_interannual_variability": (
+        "interannual_variability",
+        "plot_precip_interannual_variability",
+    ),
+    "plot_temp_interannual_variability": (
+        "interannual_variability",
+        "plot_temp_interannual_variability",
+    ),
+    "read_stn_data": ("interannual_variability", "read_stn_data"),
+    "assign_season_year": ("interannual_variability", "assign_season_year"),
+    "plot_precip_map": ("spatial_map", "plot_precip_map"),
+    "plot_precip_anomaly": ("spatial_map", "plot_precip_anomaly"),
+    "plot_temp_map": ("spatial_map", "plot_temp_map"),
+    "plot_temp_anomaly": ("spatial_map", "plot_temp_anomaly"),
+    "plot_precip_climatology_map": (
+        "climatology",
+        "plot_precip_climatology_map",
+    ),
+    "plot_temperature_climatology_map": (
+        "climatology",
+        "plot_temperature_climatology_map",
+    ),
+    "plot_climatology_spatial_mean": (
+        "climatology",
+        "plot_climatology_spatial_mean",
+    ),
+    "plot_diagram_ombro_one_point": (
+        "climatology",
+        "plot_diagram_ombro_one_point",
+    ),
+    "plot_composite_map": ("climatology", "plot_composite_map"),
+    "plot_stn_temp_monitoring": (
+        "monitoring_stn",
+        "plot_stn_temp_monitoring",
+    ),
+    "plot_stn_precip_monitoring": (
+        "monitoring_stn",
+        "plot_stn_precip_monitoring",
+    ),
+    "plot_stn_monthly_monitoring": (
+        "monitoring_stn",
+        "plot_stn_monthly_monitoring",
+    ),
+    "plot_monthly_interannual_variability": (
+        "monitoring_stn",
+        "plot_monthly_interannual_variability",
+    ),
+    "plot_track_tc": ("monitor_tc", "plot_track_tc"),
+    "temporal_evolution_tc": ("monitor_tc", "temporal_evolution_tc"),
+    "plot_all_tc_season": ("monitor_tc", "plot_all_tc_season"),
+    "plot_map_latest_sst": (
+        "monitoring_large_scale_param",
+        "plot_map_latest_sst",
+    ),
+    "plot_map_latest_mslp": (
+        "monitoring_large_scale_param",
+        "plot_map_latest_mslp",
+    ),
+    "plot_climate_indices": (
+        "monitoring_climate_driver",
+        "plot_climate_indices",
+    ),
+    "plot_sst_map_variability": (
+        "monitoring_climate_driver",
+        "plot_sst_map_variability",
+    ),
+    "blend_stn_cdt_data": ("preparation_data", "blend_stn_cdt_data"),
+    "download_sst_mean_data": ("preparation_data", "download_sst_mean_data"),
+    "normalize_lat_lon": ("preparation_data", "normalize_lat_lon"),
+    "resolve_variable": ("preparation_data", "resolve_variable"),
+    "is_precip_variable": ("preparation_data", "is_precip_variable"),
+    "set_plot_defaults": ("preparation_data", "set_plot_defaults"),
+    "set_title": ("preparation_data", "set_title"),
+    "set_grid": ("preparation_data", "set_grid"),
+    "set_map_grid": ("preparation_data", "set_map_grid"),
+    "annual_trend": ("annual_analysis", "annual_trend"),
+    "disaster_impact": ("disaster_analysis", "disaster_impact"),
+    "plot_disaster_impact": ("plot_disaster_impact", "plot_disaster_impact"),
+}
+
+__all__ = sorted(_EXPORTS)
+
+
+def __getattr__(name):
+    if name not in _EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module_name, object_name = _EXPORTS[name]
+    module = __import__(
+        f"{__name__}.{module_name}",
+        fromlist=[object_name],
+    )
+    value = getattr(module, object_name)
+    globals()[name] = value
+    return value

climatewatches-1.0.1/climatewatches/annual_analysis.py

@@ -0,0 +1,191 @@
+"""Annual climate analysis."""
+
+import pandas as pd
+import matplotlib.pyplot as plt
+
+
+DEFAULT_MISSING_VALUES = [
+    -999,
+    -99.9,
+    -99,
+    "NA",
+    "N/A",
+    "",
+    "missing",
+    "Missing",
+    "MISSING",
+    "nan",
+    "NaN",
+    "NULL",
+    None,
+]
+
+
+def annual_trend(
+    file,
+    date_col="Date",
+    temp_col="Tmean",
+    rainfall_col="Rainfall",
+    date_format="%Y%m%d",
+    missing_values=-99.9,
+    smooth=True,
+    smooth_year=5,
+    title="Climate trends",
+    output_file="annual_valueTrend.png",
+    show=True,
+):
+    """
+    Plot annual mean temperature and annual total rainfall trends.
+
+    Parameters
+    ----------
+    file : str or path-like
+        Path to the station CSV file.
+    date_col : str, default "Date"
+        Date column name.
+    temp_col : str, default "Tmean"
+        Mean temperature column name.
+    rainfall_col : str, default "Rainfall"
+        Rainfall column name.
+    date_format : str or None, default "%Y%m%d"
+        Date format used by ``pandas.to_datetime``. Use None to infer dates.
+    missing_values : list-like or scalar, optional
+        Extra missing-value markers. Common markers are handled by default.
+    smooth : bool, default True
+        If True, add rolling average lines.
+    smooth_year : int, default 5
+        Rolling average window size in years.
+    title : str, default "Climate trends"
+        Main title displayed above the plot.
+    output_file : str or path-like or None, default "annual_valueTrend.png"
+        Path where the plot is saved. Use None to skip saving.
+    show : bool, default True
+        If True, display the plot.
+
+    Returns
+    -------
+    None
+    """
+    if smooth_year < 1:
+        raise ValueError("smooth_year must be at least 1.")
+
+    na_values = list(DEFAULT_MISSING_VALUES)
+    if missing_values is not None:
+        if isinstance(missing_values, (list, tuple, set)):
+            na_values.extend(missing_values)
+        else:
+            na_values.append(missing_values)
+
+    df = pd.read_csv(file, na_values=na_values)
+
+    required_columns = {date_col, temp_col, rainfall_col}
+    missing_columns = required_columns.difference(df.columns)
+    if missing_columns:
+        missing_text = ", ".join(sorted(missing_columns))
+        raise ValueError(f"Missing required column(s): {missing_text}")
+
+    df = df[[date_col, temp_col, rainfall_col]].copy()
+    df[date_col] = pd.to_datetime(
+        df[date_col].astype("string"),
+        format=date_format,
+        errors="coerce",
+    )
+    df[temp_col] = pd.to_numeric(df[temp_col], errors="coerce")
+    df[rainfall_col] = pd.to_numeric(df[rainfall_col], errors="coerce")
+    df = df.dropna(subset=[date_col])
+
+    if df.empty:
+        raise ValueError("No valid dates found after removing missing values.")
+
+    df["Year"] = df[date_col].dt.year
+
+    annual_df = (
+        df.groupby("Year", as_index=False)
+        .agg(
+            Mean_Temp=(temp_col, "mean"),
+            Total_Rainfall=(rainfall_col, lambda values: values.sum(min_count=1)),
+        )
+        .sort_values("Year")
+        .reset_index(drop=True)
+    )
+
+    if annual_df[["Mean_Temp", "Total_Rainfall"]].isna().all().all():
+        raise ValueError("No valid temperature or rainfall values found.")
+
+    if smooth:
+        annual_df["Temp_Rolling_Avg"] = (
+            annual_df["Mean_Temp"].rolling(window=smooth_year, min_periods=1).mean()
+        )
+        annual_df["Rain_Rolling_Avg"] = (
+            annual_df["Total_Rainfall"].rolling(window=smooth_year, min_periods=1).mean()
+        )
+
+    fig, axes = plt.subplots(1, 2, figsize=(14, 6), sharex=True)
+    fig.suptitle(
+        title,
+        fontsize=16,
+        fontweight="bold",
+        y=0.98,
+        color="#1e293b",
+    )
+
+    for ax in axes:
+        ax.spines["top"].set_visible(False)
+        ax.spines["right"].set_visible(False)
+        ax.grid(axis="y", linestyle="-", alpha=0.3, color="#cbd5e1")
+        ax.tick_params(colors="#475569")
+
+    axes[0].plot(
+        annual_df["Year"],
+        annual_df["Mean_Temp"],
+        color="#93c5fd",
+        linewidth=1,
+        alpha=0.75,
+        label="Annual mean",
+    )
+    if smooth:
+        axes[0].plot(
+            annual_df["Year"],
+            annual_df["Temp_Rolling_Avg"],
+            color="#1e3a8a",
+            linewidth=2.5,
+            label=f"{smooth_year}-yr rolling avg",
+        )
+
+    axes[0].set_title("Mean annual temperature (deg C)", color="#1e293b", pad=12)
+    axes[0].set_ylabel("deg C", fontweight="bold", color="#475569")
+    axes[0].legend(frameon=False, loc="upper right")
+
+    axes[1].plot(
+        annual_df["Year"],
+        annual_df["Total_Rainfall"],
+        color="#fde68a",
+        linewidth=1,
+        alpha=0.85,
+        label="Annual total",
+    )
+    if smooth:
+        axes[1].plot(
+            annual_df["Year"],
+            annual_df["Rain_Rolling_Avg"],
+            color="#78350f",
+            linewidth=2.5,
+            label=f"{smooth_year}-yr rolling avg",
+        )
+
+    axes[1].set_title("Total annual precipitation (mm)", color="#1e293b", pad=12)
+    axes[1].set_ylabel("mm", fontweight="bold", color="#475569")
+    axes[1].legend(frameon=False, loc="upper left")
+
+    plt.tight_layout()
+
+    if output_file is not None:
+        plt.savefig(output_file, dpi=300)
+    if show:
+        plt.show()
+    else:
+        plt.close(fig)
+    if output_file is not None:
+        print(f"Plot created and saved: {output_file}")
+
+    return None