imergpy 1.1.0__py3-none-any.whl

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/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/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/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/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

imergpy/downloader.py

@@ -0,0 +1,128 @@
+import requests
+from requests.adapters import HTTPAdapter
+from requests.auth import HTTPBasicAuth
+from urllib3.util.retry import Retry
+
+
+class DownloadError(Exception):
+    """Raised when an IMERG granule cannot be downloaded."""
+
+
+class EarthdataDownloader:
+    def __init__(self, username, password, timeout=60, retries=3):
+        if not username or not password:
+            raise ValueError("NASA Earthdata username and password are required.")
+
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.auth = HTTPBasicAuth(username, password)
+        retry = Retry(
+            total=retries,
+            connect=retries,
+            read=retries,
+            status=retries,
+            backoff_factor=0.5,
+            status_forcelist=(429, 500, 502, 503, 504),
+            allowed_methods=("GET",),
+        )
+        adapter = HTTPAdapter(max_retries=retry)
+        self.session.mount("https://", adapter)
+        self.session.mount("http://", adapter)
+
+    def _build_url(self, lat, lon, dt, version, run_type="early", freq="hhr", bbox=None):
+        from .config import get_time_string
+        
+        if bbox:
+            min_lat, min_lon, max_lat, max_lon = bbox
+            min_lat, max_lat = max(-90.0, float(min_lat)), min(90.0, float(max_lat))
+            min_lon, max_lon = max(-180.0, float(min_lon)), min(180.0, float(max_lon))
+        else:
+            min_lat, max_lat = max(-90.0, lat - 0.1), min(90.0, lat + 0.1)
+            min_lon, max_lon = max(-180.0, lon - 0.1), min(180.0, lon + 0.1)
+        bbox = f"{min_lat},{min_lon},{max_lat},{max_lon}".replace(",", "%2C")
+
+        year = dt.strftime("%Y")
+        month = dt.strftime("%m")
+        doy = dt.strftime("%j")
+        date_str = dt.strftime("%Y%m%d")
+        
+        if freq == "hhr":
+            time_str = get_time_string(dt)
+            ext = "HDF5"
+            if run_type == "early":
+                shortname = "GPM_3IMERGHHE"
+                prefix = f"3B-HHR-E.MS.MRG.3IMERG.{date_str}-{time_str}"
+            elif run_type == "late":
+                shortname = "GPM_3IMERGHHL"
+                prefix = f"3B-HHR-L.MS.MRG.3IMERG.{date_str}-{time_str}"
+            elif run_type == "final":
+                shortname = "GPM_3IMERGHH"
+                prefix = f"3B-HHR.MS.MRG.3IMERG.{date_str}-{time_str}"
+            else:
+                raise ValueError("run_type must be 'early', 'late', or 'final'.")
+        elif freq == "daily":
+            time_str = "S000000-E235959"
+            ext = "nc4"
+            if run_type == "early":
+                shortname = "GPM_3IMERGDE"
+                prefix = f"3B-DAY-E.MS.MRG.3IMERG.{date_str}-{time_str}"
+            elif run_type == "late":
+                shortname = "GPM_3IMERGDL"
+                prefix = f"3B-DAY-L.MS.MRG.3IMERG.{date_str}-{time_str}"
+            elif run_type == "final":
+                shortname = "GPM_3IMERGDF"
+                prefix = f"3B-DAY.MS.MRG.3IMERG.{date_str}-{time_str}"
+            else:
+                raise ValueError("run_type must be 'early', 'late', or 'final'.")
+        elif freq == "monthly":
+            time_str = f"S000000-E235959.{month}"
+            ext = "HDF5"
+            date_str = dt.strftime("%Y%m01") # Monthlies start on 1st
+            if run_type == "final":
+                shortname = "GPM_3IMERGM"
+                prefix = f"3B-MO.MS.MRG.3IMERG.{date_str}-{time_str}"
+            else:
+                raise ValueError("Monthly frequency usually only supports 'final' run_type.")
+        else:
+            raise ValueError(f"Unsupported frequency: {freq}")
+
+        filename = f"/data/GPM_L3/{shortname}.07/{year}/{doy}/{prefix}.{version}.{ext}"
+        if freq == "daily":
+             filename = f"/data/GPM_L3/{shortname}.07/{year}/{month}/{prefix}.{version}.{ext}"
+        elif freq == "monthly":
+             filename = f"/data/GPM_L3/{shortname}.07/{year}/{prefix}.{version}.{ext}"
+
+        filename_encoded = filename.replace("/", "%2F")
+        label = f"{prefix}.{version}.{ext}.SUB.nc4"
+
+        return (
+            f"https://gpm1.gesdisc.eosdis.nasa.gov/daac-bin/OTF/HTTP_services.cgi?"
+            f"FILENAME={filename_encoded}&SERVICE=L34RS_GPM&LABEL={label}&BBOX={bbox}"
+            f"&VERSION=1.02&VARIABLES=precipitation&SHORTNAME={shortname}&DATASET_VERSION=07&FORMAT=nc4%2F"
+        )
+
+    def download_granule(self, lat, lon, dt, out_path, run_type="early", freq="hhr", bbox=None):
+        """Tries to download V07C first. If 404, falls back to V07B."""
+        for version in ["V07C", "V07B", "V07A"]:
+            try:
+                url = self._build_url(lat, lon, dt, version, run_type, freq, bbox=bbox)
+            except ValueError as e:
+                raise e
+                
+            try:
+                response = self.session.get(url, stream=True, timeout=self.timeout)
+            except requests.RequestException as e:
+                raise DownloadError(f"Network error while downloading {dt}: {e}") from e
+            
+            if response.status_code == 200:
+                with open(out_path, 'wb') as f:
+                    for chunk in response.iter_content(chunk_size=8192):
+                        if chunk:
+                            f.write(chunk)
+                return True, version
+            elif response.status_code == 404:
+                continue
+            else:
+                raise DownloadError(f"Failed to download data. Status: {response.status_code}. Response: {response.text}")
+        
+        raise DownloadError(f"File not available (tried V07C, V07B, V07A) for {dt} | Run: {run_type} | Freq: {freq}")

imergpy/plotter.py

@@ -0,0 +1,49 @@
+import pandas as pd
+import matplotlib.pyplot as plt
+import os
+from .analyzer import _precip_column, _time_column
+
+def plot_from_excel(excel_path, save_png=True):
+    """
+    Reads the IMERG data from an Excel file and plots a time series.
+    
+    Args:
+        excel_path (str): Path to the generated Excel file.
+        save_png (bool): If True, saves the plot as a PNG image alongside the Excel file.
+    """
+    try:
+        # Read the Excel file
+        df = pd.read_excel(excel_path)
+        
+        time_col = _time_column(df)
+        precip_col = _precip_column(df)
+        df[time_col] = pd.to_datetime(df[time_col])
+        
+        df = df.sort_values(time_col)
+        ylabel = precip_col.replace("Precipitation_", "").replace("_", " ")
+        
+        plt.figure(figsize=(10, 6))
+        plt.plot(df[time_col], df[precip_col], marker='o', linestyle='-', color='b', label='Precipitation')
+        
+        lat = df['Requested_Lat'].iloc[0]
+        lon = df['Requested_Lon'].iloc[0]
+        plt.title(f'IMERG Precipitation\nLat: {lat}, Lon: {lon}')
+        plt.xlabel('Time (UTC)')
+        plt.ylabel(f'Precipitation ({ylabel})')
+        plt.grid(True, linestyle='--', alpha=0.7)
+        plt.xticks(rotation=45)
+        plt.tight_layout()
+        
+        # Save or display
+        if save_png:
+            png_path = os.path.splitext(excel_path)[0] + '.png'
+            plt.savefig(png_path, dpi=300)
+            print(f"Plot saved successfully to: {png_path}")
+        else:
+            plt.show()
+            
+        # Close plot to free memory
+        plt.close()
+        
+    except Exception as e:
+        raise Exception(f"Failed to plot time series: {str(e)}")

imergpy/processor.py

@@ -0,0 +1,157 @@
+import xarray as xr
+import pandas as pd
+import calendar
+import numpy as np
+from datetime import timedelta
+from dateutil.relativedelta import relativedelta
+from matplotlib.path import Path
+
+
+VALID_INTERPOLATION_METHODS = {"nearest", "linear", "cubic"}
+
+
+def _time_bounds(time_val, freq, current_dt):
+    t_start = time_val[0] if getattr(time_val, 'ndim', 0) > 0 else time_val
+    if hasattr(t_start, 'tolist'):
+        t_start = pd.to_datetime(t_start)
+
+    if freq == "hhr":
+        return t_start, t_start + timedelta(minutes=30), "Precipitation_mm_per_half_hour", 0.5
+    if freq == "daily":
+        return t_start, t_start + timedelta(days=1), "Precipitation_mm_per_day", 1.0
+    if freq == "monthly":
+        days_in_month = calendar.monthrange(current_dt.year, current_dt.month)[1]
+        return t_start, t_start + relativedelta(months=1), "Precipitation_mm_per_month", 24 * days_in_month
+    raise ValueError("freq must be 'hhr', 'daily', or 'monthly'.")
+
+
+def _iter_polygons(geometry):
+    if not geometry:
+        return []
+    if geometry.get("type") == "Polygon":
+        return [geometry["coordinates"]]
+    if geometry.get("type") == "MultiPolygon":
+        return geometry["coordinates"]
+    return []
+
+
+def _geometry_mask(lats, lons, geometry):
+    lon_grid, lat_grid = np.meshgrid(lons, lats)
+    points = np.column_stack([lon_grid.ravel(), lat_grid.ravel()])
+    mask = np.zeros(points.shape[0], dtype=bool)
+
+    for polygon in _iter_polygons(geometry):
+        if not polygon:
+            continue
+        exterior = Path(polygon[0])
+        poly_mask = exterior.contains_points(points)
+        for hole in polygon[1:]:
+            poly_mask &= ~Path(hole).contains_points(points)
+        mask |= poly_mask
+
+    return mask.reshape(lat_grid.shape)
+
+def extract_precipitation(nc_path, target_lat, target_lon, method="nearest", freq="hhr", current_dt=None):
+    """
+    Reads the downloaded NetCDF file, extracts precipitation at the specified point,
+    and returns a dictionary with the extracted data and proper units.
+    Now includes Start_Time and End_Time.
+    """
+    if method not in VALID_INTERPOLATION_METHODS:
+        raise ValueError("method must be 'nearest', 'linear', or 'cubic'.")
+    if freq not in {"hhr", "daily", "monthly"}:
+        raise ValueError("freq must be 'hhr', 'daily', or 'monthly'.")
+    if freq == "monthly" and current_dt is None:
+        raise ValueError("current_dt is required when freq='monthly'.")
+
+    try:
+        ds = xr.open_dataset(nc_path)
+        
+        if method == "nearest":
+            point_data = ds.sel(lat=target_lat, lon=target_lon, method="nearest")
+            actual_lat = float(point_data['lat'].values.item())
+            actual_lon = float(point_data['lon'].values.item())
+        else:
+            point_data = ds.interp(lat=target_lat, lon=target_lon, method=method)
+            actual_lat = target_lat
+            actual_lon = target_lon
+            
+        precip_value = point_data['precipitation'].values
+        time_val = point_data['time'].values
+        
+        t_start, t_end, col_name, scale = _time_bounds(time_val, freq, current_dt)
+        val = float(precip_value.item() if hasattr(precip_value, 'item') else precip_value) * scale
+        return {
+            "Requested_Lat": target_lat,
+            "Requested_Lon": target_lon,
+            "Actual_Lat": actual_lat,
+            "Actual_Lon": actual_lon,
+            "Interpolation": method,
+            "Start_Time": t_start,
+            "End_Time": t_end,
+            col_name: val
+        }
+    except Exception as e:
+        raise Exception(f"Failed to process NetCDF: {str(e)}")
+    finally:
+        if 'ds' in locals():
+            ds.close()
+
+
+def extract_area_average(nc_path, bbox, freq="hhr", current_dt=None, geometry=None, region_name=None, region_type="area"):
+    if freq not in {"hhr", "daily", "monthly"}:
+        raise ValueError("freq must be 'hhr', 'daily', or 'monthly'.")
+    if freq == "monthly" and current_dt is None:
+        raise ValueError("current_dt is required when freq='monthly'.")
+
+    try:
+        ds = xr.open_dataset(nc_path)
+        da = ds["precipitation"]
+        if "time" in da.dims:
+            da = da.isel(time=0)
+        if "lat" in da.dims and "lon" in da.dims:
+            da = da.transpose("lat", "lon")
+
+        lats = ds["lat"].values
+        lons = ds["lon"].values
+        values = np.asarray(da.values, dtype=float)
+        while values.ndim > 2:
+            values = values[0]
+        if values.shape != (len(lats), len(lons)):
+            if values.T.shape == (len(lats), len(lons)):
+                values = values.T
+            else:
+                raise ValueError(
+                    f"Unexpected precipitation grid shape {values.shape}; expected {(len(lats), len(lons))}."
+                )
+
+        mask = np.isfinite(values)
+        if geometry:
+            geom_mask = _geometry_mask(lats, lons, geometry)
+            if geom_mask.any():
+                mask &= geom_mask
+
+        if not mask.any():
+            raise ValueError("No IMERG grid cells found inside the selected region.")
+
+        mean_rate = float(np.nanmean(np.where(mask, values, np.nan)))
+        t_start, t_end, col_name, scale = _time_bounds(ds["time"].values, freq, current_dt)
+        min_lat, min_lon, max_lat, max_lon = bbox
+
+        return {
+            "Region_Type": region_type,
+            "Region_Name": region_name or region_type,
+            "Min_Lat": min_lat,
+            "Min_Lon": min_lon,
+            "Max_Lat": max_lat,
+            "Max_Lon": max_lon,
+            "Grid_Cells_Averaged": int(mask.sum()),
+            "Start_Time": t_start,
+            "End_Time": t_end,
+            col_name: mean_rate * scale,
+        }
+    except Exception as e:
+        raise Exception(f"Failed to process area NetCDF: {str(e)}")
+    finally:
+        if 'ds' in locals():
+            ds.close()