MonthlyDustAnalyzer Module
==========================

Overview
--------

The ``MonthlyDustAnalyzer`` module is a key component of the **Dusty Pipeline** that performs monthly aggregation and statistical analysis of dust storm events. It consumes raw storm detections from modules like ``StormDetector`` or ``FusionStormDetector`` and transforms them into a structured, high-level summary suitable for climatological research, operational reporting, and validation.

The primary objective of this module is to **condense multi-day dust storm detections into monthly summaries**, capturing key metrics such as frequency, intensity, spatial distribution, and proximity to critical infrastructure like airports.

Functionality
-------------

1. **Storm Grouping by Month**:
   - Processes per-storm detections across multiple days.
   - Groups entries by month and storm identifier.
   - Supports merging or splitting storms that persist across months based on user-defined logic.

2. **Statistical Aggregation**:
   - Calculates storm-wise statistics for each month:
     - Number of storms detected
     - Maximum and average dust mass
     - Geographical spread (min/max lat/lon)
     - Most affected airports (if proximity data is available)

3. **Airport Association**:
   - If airport proximity data is included in input CSV, it identifies which airports were affected each month.
   - Computes airport-specific statistics like number of events and intensity of nearby storms.

4. **Output Generation**:
   - Produces a clean monthly CSV file summarizing:
     - Each storm’s lifecycle
     - Storm metrics (mass, location, days active)
     - Airport interactions
   - Output is saved to the configured `csv_output_path` as `monthly_storm_summary.csv`.

Input Requirements
------------------

The module expects storm-level CSVs as generated by:

- ``StormDetector`` (dust-only)
- ``FusionStormDetector`` (dust + AODANA)

Each input file must include:

- `storm_id`
- `date`
- `center_lat`, `center_lon`
- `avg_dust_mass`
- `nearest_airport_icao` (optional)

Configuration Options
---------------------

- ``merge_cross_month_storms``: Boolean to track storms across months or split per month.
- ``min_storm_duration``: Filter out short-lived storms (e.g., < 1 day).
- ``min_avg_mass_threshold``: Ignore low-intensity storms from aggregation.
- ``airport_focus_list``: Optional list of ICAOs to prioritize in reporting.

Integration in Dusty Pipeline
-----------------------------

This module is typically called at the end of each processing cycle after all storm detections have been logged. It serves as the **final summary layer** before optional METAR matching or visualization tools.

Dependencies
------------

- `Pandas`
- `Datetime`
- `Geopy` (optional, for distance/airport metrics)
- `OS` and `Glob` (for multi-file reading)

Output Format
-------------

Example fields in `monthly_storm_summary.csv`:

- ``month``
- ``storm_id``
- ``total_days_active``
- ``max_dust_mass``
- ``avg_dust_mass``
- ``geographical_extent``
- ``affected_airports``
- ``peak_intensity_day``

Use Cases
---------

- Monthly monitoring of regional dust activity
- Infrastructure vulnerability reporting (e.g., airports)
- Scientific validation of seasonal trends
- Baseline statistics for thresholding or alerting models

The ``MonthlyDustAnalyzer`` module ensures traceability, transparency, and long-term usability of the raw dust storm detection outputs, forming a bridge between data science and operational insights.