imergpy 1.1.0__tar.gz

imergpy-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lakshitha S. Senavirathna
+
+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.

imergpy-1.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include imergpy/templates/*.html
+include imergpy/static/*
+include LICENSE
+include README.md
+recursive-include examples *.py
+recursive-include tests *.py
+global-exclude __pycache__/*
+global-exclude *.py[cod]
+global-exclude *.xlsx
+global-exclude *.nc
+global-exclude *.nc4
+global-exclude .env

imergpy-1.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: imergpy
+Version: 1.1.0
+Summary: Download, extract, average, plot, and analyze NASA GPM IMERG precipitation data from Python or a local web UI.
+Author-email: "Lakshitha S. Senavirathna" <lakshithasrimal256@gmail.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/LakshithaSenavirathna/imergpy
+Keywords: IMERG,GPM,NASA,precipitation,rainfall,Earthdata,GES DISC
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: xarray
+Requires-Dist: netCDF4
+Requires-Dist: pandas
+Requires-Dist: openpyxl
+Requires-Dist: matplotlib
+Requires-Dist: flask
+Requires-Dist: python-dateutil
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# imergpy
+
+`imergpy` is a Python package and local web interface for downloading NASA GPM IMERG precipitation data through NASA Earthdata/GES DISC. It can extract point rainfall time series and compute grid-cell average rainfall for selected countries or square areas.
+
+## Features
+
+- Local web UI launched with the `imergpy` command
+- Python API for scripted workflows
+- Point, country, and square-area selection in the web map
+- Grid-cell average precipitation for country and square-area selections
+- Half-hourly, daily, and monthly IMERG products
+- Early, Late, and Final IMERG run types where available
+- Excel export with separate `Start Time` and `End Time` columns
+- Basic rainfall plotting and statistics utilities
+
+## Installation
+
+Users only need two commands:
+
+```bash
+pip install imergpy
+imergpy
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+The browser should open automatically. If it does not, copy the local URL printed in the terminal.
+
+## Start The Web UI Manually
+
+```bash
+imergpy
+```
+
+If the command is not available on Windows:
+
+```bash
+python -m imergpy.cli
+```
+
+If port `5000` is busy:
+
+```powershell
+$env:IMERGPY_PORT = "5001"
+python -m imergpy.cli
+```
+
+## Python API Example
+
+```python
+import os
+import imergpy
+
+excel_path, records = imergpy.get_precipitation(
+    lat=6.9271,
+    lon=79.8612,
+    start_datetime="2025-01",
+    end_datetime="2025-01",
+    username=os.environ["EARTHDATA_USERNAME"],
+    password=os.environ["EARTHDATA_PASSWORD"],
+    run_type="final",
+    freq="monthly",
+    interp_method="nearest",
+)
+
+print(excel_path)
+```
+
+Accepted date formats:
+
+- `YYYY-MM`
+- `YYYY-MM-DD`
+- `YYYY-MM-DD HH:MM`
+
+## NASA Earthdata Credentials
+
+You need a free NASA Earthdata account. After creating the account, authorize GES DISC under Earthdata authorized applications.
+
+Do not write credentials into scripts. Use environment variables:
+
+```powershell
+$env:EARTHDATA_USERNAME = "your_username"
+$env:EARTHDATA_PASSWORD = "your_password"
+```
+
+## Legal And Data Use Notice
+
+`imergpy` is an independent open-source tool. It is not developed, endorsed, or certified by NASA, GES DISC, or the GPM mission team.
+
+Users are responsible for:
+
+- creating and using their own NASA Earthdata account,
+- accepting and following NASA/GES DISC data access terms,
+- citing NASA GPM IMERG data correctly in reports, papers, and products,
+- checking data quality, latency, and suitability before operational or scientific use,
+- keeping Earthdata usernames, passwords, and tokens private.
+
+This software is provided under the MIT License without warranty.
+
+## Development
+
+Run tests:
+
+```bash
+pytest
+```
+
+Build package files:
+
+```bash
+python -m build
+```
+
+Upload to TestPyPI first:
+
+```bash
+twine upload --repository testpypi dist/*
+```
+
+Upload to PyPI:
+
+```bash
+twine upload dist/*
+```
+
+## License
+
+MIT License. Developed by Lakshitha S. Senavirathna.

imergpy-1.1.0/README.md

@@ -0,0 +1,132 @@
+# imergpy
+
+`imergpy` is a Python package and local web interface for downloading NASA GPM IMERG precipitation data through NASA Earthdata/GES DISC. It can extract point rainfall time series and compute grid-cell average rainfall for selected countries or square areas.
+
+## Features
+
+- Local web UI launched with the `imergpy` command
+- Python API for scripted workflows
+- Point, country, and square-area selection in the web map
+- Grid-cell average precipitation for country and square-area selections
+- Half-hourly, daily, and monthly IMERG products
+- Early, Late, and Final IMERG run types where available
+- Excel export with separate `Start Time` and `End Time` columns
+- Basic rainfall plotting and statistics utilities
+
+## Installation
+
+Users only need two commands:
+
+```bash
+pip install imergpy
+imergpy
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+The browser should open automatically. If it does not, copy the local URL printed in the terminal.
+
+## Start The Web UI Manually
+
+```bash
+imergpy
+```
+
+If the command is not available on Windows:
+
+```bash
+python -m imergpy.cli
+```
+
+If port `5000` is busy:
+
+```powershell
+$env:IMERGPY_PORT = "5001"
+python -m imergpy.cli
+```
+
+## Python API Example
+
+```python
+import os
+import imergpy
+
+excel_path, records = imergpy.get_precipitation(
+    lat=6.9271,
+    lon=79.8612,
+    start_datetime="2025-01",
+    end_datetime="2025-01",
+    username=os.environ["EARTHDATA_USERNAME"],
+    password=os.environ["EARTHDATA_PASSWORD"],
+    run_type="final",
+    freq="monthly",
+    interp_method="nearest",
+)
+
+print(excel_path)
+```
+
+Accepted date formats:
+
+- `YYYY-MM`
+- `YYYY-MM-DD`
+- `YYYY-MM-DD HH:MM`
+
+## NASA Earthdata Credentials
+
+You need a free NASA Earthdata account. After creating the account, authorize GES DISC under Earthdata authorized applications.
+
+Do not write credentials into scripts. Use environment variables:
+
+```powershell
+$env:EARTHDATA_USERNAME = "your_username"
+$env:EARTHDATA_PASSWORD = "your_password"
+```
+
+## Legal And Data Use Notice
+
+`imergpy` is an independent open-source tool. It is not developed, endorsed, or certified by NASA, GES DISC, or the GPM mission team.
+
+Users are responsible for:
+
+- creating and using their own NASA Earthdata account,
+- accepting and following NASA/GES DISC data access terms,
+- citing NASA GPM IMERG data correctly in reports, papers, and products,
+- checking data quality, latency, and suitability before operational or scientific use,
+- keeping Earthdata usernames, passwords, and tokens private.
+
+This software is provided under the MIT License without warranty.
+
+## Development
+
+Run tests:
+
+```bash
+pytest
+```
+
+Build package files:
+
+```bash
+python -m build
+```
+
+Upload to TestPyPI first:
+
+```bash
+twine upload --repository testpypi dist/*
+```
+
+Upload to PyPI:
+
+```bash
+twine upload dist/*
+```
+
+## License
+
+MIT License. Developed by Lakshitha S. Senavirathna.

imergpy-1.1.0/examples/basic_point_download.py

@@ -0,0 +1,18 @@
+import os
+
+import imergpy
+
+
+excel_path, records = imergpy.get_precipitation(
+    lat=6.9271,
+    lon=79.8612,
+    start_datetime="2024-05-20 14:30",
+    end_datetime="2024-05-20 15:00",
+    username=os.environ["EARTHDATA_USERNAME"],
+    password=os.environ["EARTHDATA_PASSWORD"],
+    run_type="final",
+    freq="hhr",
+)
+
+print(excel_path)
+print(records[:1])

imergpy-1.1.0/imergpy/__init__.py

@@ -0,0 +1,12 @@
+# imergpy package
+from .core import get_precipitation
+from .plotter import plot_from_excel
+from .analyzer import add_accumulation, resample_data, calculate_statistics
+
+__all__ = [
+    "get_precipitation", 
+    "plot_from_excel", 
+    "add_accumulation",
+    "resample_data",
+    "calculate_statistics"
+]

imergpy-1.1.0/imergpy/analyzer.py

@@ -0,0 +1,87 @@
+import pandas as pd
+
+
+PRECIP_COLUMNS = [
+    "Precipitation_mm_per_half_hour",
+    "Precipitation_mm_per_day",
+    "Precipitation_mm_per_month",
+    "Precipitation_mm",
+    "Precipitation_mm_hr",
+]
+
+
+def _find_column(df, candidates, label):
+    for column in candidates:
+        if column in df.columns:
+            return column
+    raise ValueError(f"Could not find {label}. Expected one of: {', '.join(candidates)}")
+
+
+def _time_column(df):
+    return _find_column(df, ["Start_Time", "Time"], "time column")
+
+
+def _precip_column(df):
+    return _find_column(df, PRECIP_COLUMNS, "precipitation column")
+
+def add_accumulation(df):
+    """
+    Takes a DataFrame with half-hourly IMERG data and adds:
+    1. 'Absolute_Precip_mm': Total mm fallen in that 30 min interval (Rate * 0.5)
+    2. 'Cumulative_Precip_mm': Running total of rainfall over the period.
+    """
+    df = df.copy()
+    precip_col = _precip_column(df)
+
+    if precip_col == "Precipitation_mm_hr":
+        df['Absolute_Precip_mm'] = df[precip_col] * 0.5
+    else:
+        df['Absolute_Precip_mm'] = df[precip_col]
+    df['Cumulative_Precip_mm'] = df['Absolute_Precip_mm'].cumsum()
+    return df
+
+def resample_data(df, freq='D'):
+    """
+    Resamples the half-hourly data to Daily ('D') or Monthly ('M') totals.
+    Args:
+        df: Pandas DataFrame from IMERG excel
+        freq: 'D' for Daily, 'M' for Monthly
+    Returns:
+        Resampled DataFrame
+    """
+    df = df.copy()
+    if 'Absolute_Precip_mm' not in df.columns:
+        df = add_accumulation(df)
+        
+    time_col = _time_column(df)
+    df[time_col] = pd.to_datetime(df[time_col])
+    df.set_index(time_col, inplace=True)
+    
+    # Resample and sum the absolute precipitation
+    resampled = df[['Absolute_Precip_mm']].resample(freq).sum()
+    resampled.rename(columns={'Absolute_Precip_mm': 'Total_Precip_mm'}, inplace=True)
+    
+    return resampled.reset_index()
+
+def calculate_statistics(df):
+    """
+    Calculates extreme event statistics and thresholds for the given data.
+    """
+    if 'Absolute_Precip_mm' not in df.columns:
+        df = add_accumulation(df)
+        
+    # Get daily totals for threshold analysis
+    daily_df = resample_data(df, freq='D')
+    
+    stats = {
+        "Total_Rainfall_mm": float(df['Absolute_Precip_mm'].sum()),
+        "Max_Interval_Precip_mm": float(df['Absolute_Precip_mm'].max()),
+        "Max_Daily_Rainfall_mm": float(daily_df['Total_Precip_mm'].max()),
+        "Total_Days_Analyzed": int(len(daily_df)),
+        "Dry_Days_(<1mm)": int(len(daily_df[daily_df['Total_Precip_mm'] < 1.0])),
+        "Wet_Days_(>=1mm)": int(len(daily_df[daily_df['Total_Precip_mm'] >= 1.0])),
+        "Heavy_Rain_Days_(>25mm)": int(len(daily_df[daily_df['Total_Precip_mm'] > 25.0])),
+        "Extreme_Rain_Days_(>50mm)": int(len(daily_df[daily_df['Total_Precip_mm'] > 50.0]))
+    }
+    
+    return stats

imergpy-1.1.0/imergpy/cli.py

@@ -0,0 +1,13 @@
+import sys
+from .server import start_server
+
+def main():
+    """Entry point for the imergpy CLI."""
+    try:
+        start_server()
+    except KeyboardInterrupt:
+        print("\nShutting down imergpy interface...")
+        sys.exit(0)
+
+if __name__ == "__main__":
+    main()

imergpy-1.1.0/imergpy/config.py

@@ -0,0 +1,27 @@
+# List of exactly 48 time strings used by GES DISC OTF
+IMERG_TIMES = [
+    "S000000-E002959.0000", "S003000-E005959.0030", "S010000-E012959.0060", "S013000-E015959.0090", 
+    "S020000-E022959.0120", "S023000-E025959.0150", "S030000-E032959.0180", "S033000-E035959.0210", 
+    "S040000-E042959.0240", "S043000-E045959.0270", "S050000-E052959.0300", "S053000-E055959.0330", 
+    "S060000-E062959.0360", "S063000-E065959.0390", "S070000-E072959.0420", "S073000-E075959.0450", 
+    "S080000-E082959.0480", "S083000-E085959.0510", "S090000-E092959.0540", "S093000-E095959.0570", 
+    "S100000-E102959.0600", "S103000-E105959.0630", "S110000-E112959.0660", "S113000-E115959.0690", 
+    "S120000-E122959.0720", "S123000-E125959.0750", "S130000-E132959.0780", "S133000-E135959.0810", 
+    "S140000-E142959.0840", "S143000-E145959.0870", "S150000-E152959.0900", "S153000-E155959.0930", 
+    "S160000-E162959.0960", "S163000-E165959.0990", "S170000-E172959.1020", "S173000-E175959.1050", 
+    "S180000-E182959.1080", "S183000-E185959.1110", "S190000-E192959.1140", "S193000-E195959.1170", 
+    "S200000-E202959.1200", "S203000-E205959.1230", "S210000-E212959.1260", "S213000-E215959.1290", 
+    "S220000-E222959.1320", "S223000-E225959.1350", "S230000-E232959.1380", "S233000-E235959.1410"
+]
+
+def get_time_string(dt_obj):
+    """
+    Given a datetime object, returns the correct IMERG time string interval.
+    IMERG files are 30 min increments starting at top of hour.
+    """
+    hour = dt_obj.hour
+    minute = dt_obj.minute
+    
+    # 0 to 29 mins maps to first half hour, 30 to 59 maps to second
+    idx = hour * 2 + (1 if minute >= 30 else 0)
+    return IMERG_TIMES[idx]

imergpy-1.1.0/imergpy/core.py

@@ -0,0 +1,174 @@
+import os
+import tempfile
+import pandas as pd
+from datetime import datetime, timedelta
+from dateutil.relativedelta import relativedelta
+from .downloader import DownloadError, EarthdataDownloader
+from .processor import extract_area_average, extract_precipitation
+
+
+VALID_RUN_TYPES = {"early", "late", "final"}
+VALID_FREQUENCIES = {"hhr", "daily", "monthly"}
+VALID_INTERPOLATION_METHODS = {"nearest", "linear", "cubic"}
+
+
+def _parse_datetime(value):
+    value = str(value).replace('T', ' ')
+    formats = {
+        7: "%Y-%m",
+        10: "%Y-%m-%d",
+        16: "%Y-%m-%d %H:%M",
+    }
+    try:
+        return datetime.strptime(value, formats[len(value)])
+    except (KeyError, ValueError) as e:
+        raise ValueError(f"Invalid date format: {value}. Use YYYY-MM, YYYY-MM-DD, or YYYY-MM-DD HH:MM.") from e
+
+
+def _validate_inputs(lat, lon, run_type, freq, interp_method):
+    if not -90 <= float(lat) <= 90:
+        raise ValueError("lat must be between -90 and 90.")
+    if not -180 <= float(lon) <= 180:
+        raise ValueError("lon must be between -180 and 180.")
+    if run_type not in VALID_RUN_TYPES:
+        raise ValueError("run_type must be 'early', 'late', or 'final'.")
+    if freq not in VALID_FREQUENCIES:
+        raise ValueError("freq must be 'hhr', 'daily', or 'monthly'.")
+    if interp_method not in VALID_INTERPOLATION_METHODS:
+        raise ValueError("interp_method must be 'nearest', 'linear', or 'cubic'.")
+    if freq == "monthly" and run_type != "final":
+        raise ValueError("monthly frequency only supports run_type='final'.")
+
+
+def _excel_dataframe(results):
+    df = pd.DataFrame(results)
+    preferred_order = [
+        "Start_Time",
+        "End_Time",
+        "Requested_Lat",
+        "Requested_Lon",
+        "Actual_Lat",
+        "Actual_Lon",
+        "Interpolation",
+        "IMERG_Version",
+        "Run_Type",
+        "Region_Type",
+        "Region_Name",
+        "Min_Lat",
+        "Min_Lon",
+        "Max_Lat",
+        "Max_Lon",
+        "Grid_Cells_Averaged",
+    ]
+    precip_cols = [c for c in df.columns if c.startswith("Precipitation_")]
+    ordered_cols = [c for c in preferred_order + precip_cols if c in df.columns]
+    remaining_cols = [c for c in df.columns if c not in ordered_cols]
+    df = df[ordered_cols + remaining_cols]
+    return df.rename(columns={"Start_Time": "Start Time", "End_Time": "End Time"})
+
+def get_precipitation(lat, lon, start_datetime, end_datetime, username, password,
+                      run_type="early", freq="hhr", interp_method="nearest", out_dir=".",
+                      progress_callback=None, selection_mode="point", bbox=None,
+                      geometry=None, region_name=None):
+    """
+    Main function to download IMERG data for a time period and save to Excel.
+    Now includes dual Start_Time and End_Time columns.
+    """
+    if selection_mode == "point":
+        _validate_inputs(lat, lon, run_type, freq, interp_method)
+    else:
+        _validate_inputs(lat, lon, run_type, freq, "nearest")
+        if not bbox:
+            raise ValueError("bbox is required for country and square-area downloads.")
+    dt_start = _parse_datetime(start_datetime)
+    dt_end = _parse_datetime(end_datetime)
+
+    if dt_end < dt_start:
+        raise ValueError("end_datetime must be after start_datetime")
+
+    downloader = EarthdataDownloader(username, password)
+    
+    time_stamp_start = dt_start.strftime("%Y%m%d_%H%M")
+    time_stamp_end = dt_end.strftime("%Y%m%d_%H%M")
+    region_label = region_name or f"{lat}_{lon}"
+    region_label = "".join(c if c.isalnum() or c in "._-" else "_" for c in str(region_label))
+    excel_filename = f"IMERG_{run_type}_{freq}_{selection_mode}_{region_label}_{time_stamp_start}_to_{time_stamp_end}.xlsx"
+    os.makedirs(out_dir, exist_ok=True)
+    excel_path = os.path.join(out_dir, excel_filename)
+    
+    # Snap start time appropriately
+    if freq == "hhr":
+        minute = 0 if dt_start.minute < 30 else 30
+        current_dt = dt_start.replace(minute=minute, second=0, microsecond=0)
+    elif freq == "daily":
+        current_dt = dt_start.replace(hour=0, minute=0, second=0, microsecond=0)
+        dt_end = dt_end.replace(hour=23, minute=59)
+    elif freq == "monthly":
+        current_dt = dt_start.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+    total_steps = 0
+    temp_dt = current_dt
+    while temp_dt <= dt_end:
+        total_steps += 1
+        if freq == "hhr": temp_dt += timedelta(minutes=30)
+        elif freq == "daily": temp_dt += timedelta(days=1)
+        elif freq == "monthly": temp_dt += relativedelta(months=1)
+    
+    results = []
+    failures = []
+    step_count = 0
+    if progress_callback:
+        progress_callback(0)
+
+    while current_dt <= dt_end:
+        step_count += 1
+
+        fd, temp_nc_path = tempfile.mkstemp(suffix=".nc4")
+        os.close(fd)
+        
+        try:
+            _, version_used = downloader.download_granule(lat, lon, current_dt, temp_nc_path, run_type, freq, bbox=bbox)
+            if selection_mode == "point":
+                data_dict = extract_precipitation(temp_nc_path, lat, lon, method=interp_method, freq=freq, current_dt=current_dt)
+            else:
+                data_dict = extract_area_average(
+                    temp_nc_path,
+                    bbox=bbox,
+                    freq=freq,
+                    current_dt=current_dt,
+                    geometry=geometry,
+                    region_name=region_name,
+                    region_type=selection_mode,
+                )
+            data_dict["IMERG_Version"] = version_used
+            data_dict["Run_Type"] = run_type
+            results.append(data_dict)
+        except DownloadError as e:
+            failures.append({"datetime": current_dt.isoformat(), "error": str(e)})
+            print(f"  -> Warning: {e}")
+        finally:
+            if os.path.exists(temp_nc_path):
+                os.remove(temp_nc_path)
+            if progress_callback:
+                progress_callback(int((step_count / total_steps) * 100))
+        
+        if freq == "hhr": current_dt += timedelta(minutes=30)
+        elif freq == "daily": current_dt += timedelta(days=1)
+        elif freq == "monthly": current_dt += relativedelta(months=1)
+    
+    if not results:
+        details = "; ".join(f"{f['datetime']}: {f['error']}" for f in failures[:3])
+        raise RuntimeError(f"No data could be successfully downloaded. {details}")
+        
+    df = _excel_dataframe(results)
+    df.to_excel(excel_path, index=False)
+    
+    # JSON-friendly results
+    serializable_results = []
+    for r in results:
+        entry = r.copy()
+        for k in ["Start_Time", "End_Time"]:
+            if hasattr(entry[k], 'isoformat'): entry[k] = entry[k].isoformat()
+            else: entry[k] = str(entry[k])
+        serializable_results.append(entry)
+
+    return excel_path, serializable_results