arcat 0.1.0__tar.gz

arcat-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: arcat
+Version: 0.1.0
+Summary: Atmospheric River Categorization Toolkit
+Author: Kwesi Twentwewa Quagraine
+Author-email: Kwesi Twentwewa Quagraine <kwsquagraine@gmail.com>
+License: MIT
+Keywords: atmospheric rivers,ivt,weather,extremes,python
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: xarray
+Requires-Dist: dask
+Requires-Dist: numba
+Requires-Dist: tqdm
+
+# ARCat: Atmospheric River Categorization Toolkit
+
+**ARCat** is a Python package for **categorizing Atmospheric River (AR) events** based on Integrated Vapor Transport (IVT) data. It provides:
+
+- **Event-based AR categorization**: Collapses each AR event to its peak intensity.
+- **Evolution-based AR categorization**: Preserves the intensity evolution within AR events.
+
+Additionally, ARCat computes:
+
+- **Cumulative IVT** per AR event.
+- **IVT-only values** for each AR event.
+- **Duration-only values** (number of timesteps per event).
+
+It is fully compatible with **NumPy arrays**, **xarray**, and **Dask**, allowing analysis of large datasets efficiently.
+
+---
+
+## Features
+
+- Event-based and evolution-based AR categorization.
+- Automatic handling of duration rules:
+  - Events < 1 day → downgrade category
+  - Events 1–2 days → unchanged
+  - Events ≥ 2 days → upgrade category
+- Maximum category enforcement.
+- Option to extract IVT-only and duration-only arrays.
+- Easy integration with **xarray/Dask** for large datasets.
+- Fully documented and tested, with CI support.
+
+---
+
+## Installation
+
+Clone the repository and install locally:
+
+```bash
+git clone https://github.com/yourusername/arcat.git
+cd arcat
+pip install -e .
+````
+## Quick Start
+
+### Import the package
+
+```python
+import numpy as np
+from arcat.core import AR_categorization_scheme, AR_categorization_evolution_scheme
+```
+
+### Prepare your IVT array
+
+```python
+# Example: random IVT values for demonstration
+ivt = np.random.rand(20) * 1500  # IVT in kg/m/s
+```
+
+### Event-based AR categorization
+
+```python
+# Run the event-based AR scheme
+final_cat, cum_ivt, ivt_event, duration_event = AR_categorization_scheme(
+    ivt,
+    time_resolution_hours=6,  # Data resolution in hours
+    bin_width=250.0,           # IVT bin size
+    max_category=6             # Maximum AR category
+)
+
+print("Categorized AR events:", final_cat)
+print("Cumulative IVT:", cum_ivt)
+print("IVT-only values:", ivt_event)
+print("Duration per timestep:", duration_event)
+```
+
+### Evolution-based AR categorization
+
+```python
+# Run the evolution-based AR scheme
+final_cat, cum_ivt, ivt_event, duration_event = AR_categorization_evolution_scheme(
+    ivt,
+    time_resolution_hours=6,  # Data resolution in hours
+    bin_width=250.0,           # IVT bin size
+    max_category=6             # Maximum AR category
+)
+
+print("Evolution categories:", final_cat)
+print("Cumulative IVT:", cum_ivt)
+print("IVT-only values:", ivt_event)
+print("Duration per timestep:", duration_event)
+```
+
+---
+
+## Parameters
+
+| Parameter               | Description                                             |
+| ----------------------- | ------------------------------------------------------- |
+| `ivt_array`             | 1D NumPy array of IVT values (kg/m/s)                   |
+| `time_resolution_hours` | Temporal resolution of your data in hours (default: 6)  |
+| `bin_width`             | Width of each IVT bin for categorization (default: 250) |
+| `max_category`          | Maximum AR category (default: 6)                        |
+
+---
+
+## Returns
+
+1. `final_categories`: Array of AR categories (1–6) after duration adjustments.
+2. `cumulative_ivt`: Cumulative IVT during AR events.
+3. `ivt_event`: Original IVT values during AR events (0 elsewhere).
+4. `duration_event`: Number of timesteps per AR event (0 elsewhere).
+
+---
+
+## Usage Notes
+
+* Event-based scheme collapses each AR event to its maximum intensity (`max_bounded_replace`).
+* Evolution-based scheme preserves temporal evolution of IVT within AR events.
+* Duration rules are applied **per continuous AR segment**.
+* Works with any **NumPy array**, and can be integrated with **xarray or Dask arrays** for large datasets.
+
+---
+## Adopting for xarray data
+```python
+final_cat, cum_ivt, ivt_event, duration_event = xr.apply_ufunc(AR_categorization_scheme, 
+                             Ivt_ds['IVT'].as_numpy(),
+                             input_core_dims = [['time']],
+                             output_core_dims = [['time'],['time'],['time'],['time']],
+                             vectorize=True,  # Auto-vectorize over lat/lon
+                             dask='parallelized',  # Enable parallelization using Dask
+                             output_dtypes=[np.int8,np.float32,np.float32, np.int8])
+
+```
+
+## Contributing
+
+We welcome contributions! Please follow these steps:
+
+1. Fork the repository
+2. Create a new branch: `git checkout -b feature-name`
+3. Make your changes
+4. Run tests
+5. Submit a pull request
+
+---
+
+## License
+
+This project is licensed under the [Creative Commons License](https://web.archive.org/web/20230202010104/https://creativecommons.org/licenses/by/4.0/).
+
+---
+
+## References
+
+* Ralph, F. M., Rutz, J. J., Cordeira, J. M., Dettinger, M., Anderson, M., Reynolds, D., ... & Smallcomb, C. (2019). A scale to characterize the strength and impacts of atmospheric rivers. Bulletin of the American Meteorological Society, 100(2), 269-289.
+* Visit the [Atmospheric River Tracking Model Intercomparison Project (ARTMIP)](https://ncar.github.io/ARTMIP/intro.html) to follow Atmospheric River community research and publications.

arcat-0.1.0/README.md

@@ -0,0 +1,154 @@
+# ARCat: Atmospheric River Categorization Toolkit
+
+**ARCat** is a Python package for **categorizing Atmospheric River (AR) events** based on Integrated Vapor Transport (IVT) data. It provides:
+
+- **Event-based AR categorization**: Collapses each AR event to its peak intensity.
+- **Evolution-based AR categorization**: Preserves the intensity evolution within AR events.
+
+Additionally, ARCat computes:
+
+- **Cumulative IVT** per AR event.
+- **IVT-only values** for each AR event.
+- **Duration-only values** (number of timesteps per event).
+
+It is fully compatible with **NumPy arrays**, **xarray**, and **Dask**, allowing analysis of large datasets efficiently.
+
+---
+
+## Features
+
+- Event-based and evolution-based AR categorization.
+- Automatic handling of duration rules:
+  - Events < 1 day → downgrade category
+  - Events 1–2 days → unchanged
+  - Events ≥ 2 days → upgrade category
+- Maximum category enforcement.
+- Option to extract IVT-only and duration-only arrays.
+- Easy integration with **xarray/Dask** for large datasets.
+- Fully documented and tested, with CI support.
+
+---
+
+## Installation
+
+Clone the repository and install locally:
+
+```bash
+git clone https://github.com/yourusername/arcat.git
+cd arcat
+pip install -e .
+````
+## Quick Start
+
+### Import the package
+
+```python
+import numpy as np
+from arcat.core import AR_categorization_scheme, AR_categorization_evolution_scheme
+```
+
+### Prepare your IVT array
+
+```python
+# Example: random IVT values for demonstration
+ivt = np.random.rand(20) * 1500  # IVT in kg/m/s
+```
+
+### Event-based AR categorization
+
+```python
+# Run the event-based AR scheme
+final_cat, cum_ivt, ivt_event, duration_event = AR_categorization_scheme(
+    ivt,
+    time_resolution_hours=6,  # Data resolution in hours
+    bin_width=250.0,           # IVT bin size
+    max_category=6             # Maximum AR category
+)
+
+print("Categorized AR events:", final_cat)
+print("Cumulative IVT:", cum_ivt)
+print("IVT-only values:", ivt_event)
+print("Duration per timestep:", duration_event)
+```
+
+### Evolution-based AR categorization
+
+```python
+# Run the evolution-based AR scheme
+final_cat, cum_ivt, ivt_event, duration_event = AR_categorization_evolution_scheme(
+    ivt,
+    time_resolution_hours=6,  # Data resolution in hours
+    bin_width=250.0,           # IVT bin size
+    max_category=6             # Maximum AR category
+)
+
+print("Evolution categories:", final_cat)
+print("Cumulative IVT:", cum_ivt)
+print("IVT-only values:", ivt_event)
+print("Duration per timestep:", duration_event)
+```
+
+---
+
+## Parameters
+
+| Parameter               | Description                                             |
+| ----------------------- | ------------------------------------------------------- |
+| `ivt_array`             | 1D NumPy array of IVT values (kg/m/s)                   |
+| `time_resolution_hours` | Temporal resolution of your data in hours (default: 6)  |
+| `bin_width`             | Width of each IVT bin for categorization (default: 250) |
+| `max_category`          | Maximum AR category (default: 6)                        |
+
+---
+
+## Returns
+
+1. `final_categories`: Array of AR categories (1–6) after duration adjustments.
+2. `cumulative_ivt`: Cumulative IVT during AR events.
+3. `ivt_event`: Original IVT values during AR events (0 elsewhere).
+4. `duration_event`: Number of timesteps per AR event (0 elsewhere).
+
+---
+
+## Usage Notes
+
+* Event-based scheme collapses each AR event to its maximum intensity (`max_bounded_replace`).
+* Evolution-based scheme preserves temporal evolution of IVT within AR events.
+* Duration rules are applied **per continuous AR segment**.
+* Works with any **NumPy array**, and can be integrated with **xarray or Dask arrays** for large datasets.
+
+---
+## Adopting for xarray data
+```python
+final_cat, cum_ivt, ivt_event, duration_event = xr.apply_ufunc(AR_categorization_scheme, 
+                             Ivt_ds['IVT'].as_numpy(),
+                             input_core_dims = [['time']],
+                             output_core_dims = [['time'],['time'],['time'],['time']],
+                             vectorize=True,  # Auto-vectorize over lat/lon
+                             dask='parallelized',  # Enable parallelization using Dask
+                             output_dtypes=[np.int8,np.float32,np.float32, np.int8])
+
+```
+
+## Contributing
+
+We welcome contributions! Please follow these steps:
+
+1. Fork the repository
+2. Create a new branch: `git checkout -b feature-name`
+3. Make your changes
+4. Run tests
+5. Submit a pull request
+
+---
+
+## License
+
+This project is licensed under the [Creative Commons License](https://web.archive.org/web/20230202010104/https://creativecommons.org/licenses/by/4.0/).
+
+---
+
+## References
+
+* Ralph, F. M., Rutz, J. J., Cordeira, J. M., Dettinger, M., Anderson, M., Reynolds, D., ... & Smallcomb, C. (2019). A scale to characterize the strength and impacts of atmospheric rivers. Bulletin of the American Meteorological Society, 100(2), 269-289.
+* Visit the [Atmospheric River Tracking Model Intercomparison Project (ARTMIP)](https://ncar.github.io/ARTMIP/intro.html) to follow Atmospheric River community research and publications.

arcat-0.1.0/arcat/__init__.py

@@ -0,0 +1,14 @@
+"""
+arcat: Atmospheric River Categorization Toolkit
+
+Provides:
+- Event-based AR categorization
+- Evolution-based AR categorization
+- xarray + Dask support
+"""
+
+from .version import __version__
+from .core import (
+    AR_categorization_scheme,
+    AR_categorization_evolution_scheme,
+)

arcat-0.1.0/arcat/core.py

@@ -0,0 +1,190 @@
+"""
+Core AR categorization algorithms for the arcat package.
+
+This module contains:
+- Event-based AR categorization (collapses to peak intensity)
+- Evolution-based AR categorization (keeps intensity evolution)
+- IVT-only and duration-only outputs for detailed analysis
+"""
+
+import numpy as np  # Import NumPy for array operations
+from .utils import (  # Import helper functions from utils
+    compute_steps_per_day,  # Converts time resolution (hours) to timesteps per day
+    bin_ivt,                # Converts IVT values into AR categories
+    cumulative_reset,       # Computes cumulative IVT resetting at zeros
+    max_bounded_replace     # Collapses nonzero segments to their maximum value
+)
+
+# ------------------------
+# Internal helper functions
+# ------------------------
+
+def _adjust_segment(arr, start, end, duration, steps_per_day):
+    """
+    Apply duration adjustment rule to a segment (in-place modification).
+
+    Parameters
+    ----------
+    arr : np.ndarray
+        Array of AR categories to modify.
+    start : int
+        Start index of the event segment.
+    end : int
+        End index of the event segment.
+    duration : int
+        Duration of the segment in timesteps.
+    steps_per_day : int
+        Number of timesteps that correspond to 1 day.
+    """
+
+    # If duration is shorter than 1 day, downgrade the category by 1
+    if duration < steps_per_day:
+        arr[start:end] -= 1  # Subtract 1 from all elements in the segment
+
+    # If duration is longer than or equal to 2 days, upgrade the category by 1
+    elif duration >= 2 * steps_per_day:
+        arr[start:end] += 1  # Add 1 to all elements in the segment
+
+    # Otherwise (duration 1–2 days), do nothing (leave category unchanged)
+
+# ------------------------
+def _apply_duration_rule(categories, steps_per_day, max_category):
+    """
+    Apply the duration adjustment to continuous AR events.
+
+    Parameters
+    ----------
+    categories : np.ndarray
+        Array of initial AR categories per timestep.
+    steps_per_day : int
+        Number of timesteps corresponding to 1 day.
+    max_category : int
+        Maximum AR category allowed.
+
+    Returns
+    -------
+    final : np.ndarray
+        Array of AR categories after duration adjustment.
+    duration_arr : np.ndarray
+        Array of duration (in timesteps) for each AR event at each index.
+    """
+
+    final = categories.copy()  # Copy categories to avoid modifying input
+    n = len(categories)  # Total number of timesteps
+    start = None  # Initialize start index of current event
+    duration_arr = np.zeros_like(categories, dtype=float)  # Store duration per timestep
+
+    # Loop over each timestep to find AR events
+    for i in range(n):
+        if categories[i] == 0:  # Found a zero → end of AR event
+            if start is not None:  # There was an ongoing event
+                end = i  # End index of the event
+                duration = end - start  # Compute duration in timesteps
+                _adjust_segment(final, start, end, duration, steps_per_day)  # Apply duration rule
+                duration_arr[start:end] = duration  # Store duration for all timesteps in event
+                start = None  # Reset start for next event
+        else:
+            if start is None:  # Found start of a new AR event
+                start = i  # Mark start index
+
+    # Handle event that goes until the last timestep
+    if start is not None:
+        end = n  # End index is last timestep
+        duration = end - start  # Duration of the event
+        _adjust_segment(final, start, end, duration, steps_per_day)  # Apply duration rule
+        duration_arr[start:end] = duration  # Store duration
+
+    # Ensure all categories are within allowed bounds
+    return np.clip(final, 0, max_category), duration_arr  # Return adjusted categories and duration array
+
+# ------------------------
+# Event-based AR categorization
+# ------------------------
+
+def AR_categorization_scheme(
+    ivt_array: np.ndarray,  # Input IVT values
+    time_resolution_hours: int = 6,  # Time resolution of data in hours
+    bin_width: float = 250.0,  # Width of each IVT bin for categorization
+    max_category: int = 6  # Maximum AR category
+):
+    """
+    Event-based AR categorization (collapses each event to peak intensity).
+
+    Returns:
+        final_categories : np.ndarray -> categorized AR values
+        cumulative_ivt : np.ndarray -> cumulative IVT over AR events
+        ivt_event : np.ndarray -> IVT values only during AR events
+        duration_event : np.ndarray -> duration in timesteps for each AR event
+    """
+
+    # Compute how many timesteps correspond to 1 day
+    steps_per_day = compute_steps_per_day(time_resolution_hours)
+
+    # Copy IVT array to preserve original
+    original_ivt = ivt_array.copy()
+
+    # Bin IVT values into categories
+    categories = bin_ivt(ivt_array, bin_width, max_category)
+
+    # Collapse each nonzero event segment to its maximum value
+    categories = max_bounded_replace(categories)
+
+    # Apply duration rule to event segments and get duration per timestep
+    final_categories, duration_event = _apply_duration_rule(categories, steps_per_day, max_category)
+
+    # Create mask of where AR events occur (category > 0)
+    mask = final_categories > 0
+
+    # Compute cumulative IVT over AR events
+    cumulative_ivt = cumulative_reset(original_ivt, mask)
+
+    # Extract IVT values only during AR events, zero elsewhere
+    ivt_event = np.where(mask, original_ivt, 0)
+
+    # Return final categories, cumulative IVT, IVT-only, duration-only arrays
+    return final_categories, cumulative_ivt, ivt_event, duration_event
+
+# ------------------------
+# Evolution-based AR categorization
+# ------------------------
+
+def AR_categorization_evolution_scheme(
+    ivt_array: np.ndarray,  # Input IVT values
+    time_resolution_hours: int = 6,  # Time resolution of data in hours
+    bin_width: float = 250.0,  # IVT bin width
+    max_category: int = 6  # Maximum AR category
+):
+    """
+    Evolution-based AR categorization (keeps intensity evolution inside each event).
+
+    Returns:
+        final_categories : np.ndarray -> categorized AR values
+        cumulative_ivt : np.ndarray -> cumulative IVT over AR events
+        ivt_event : np.ndarray -> IVT values only during AR events
+        duration_event : np.ndarray -> duration in timesteps for each AR event
+    """
+
+    # Compute timesteps per day
+    steps_per_day = compute_steps_per_day(time_resolution_hours)
+
+    # Copy IVT array to preserve original
+    original_ivt = ivt_array.copy()
+
+    # Bin IVT values into categories
+    categories = bin_ivt(ivt_array, bin_width, max_category)
+
+    # No collapsing for evolution scheme
+    # Apply duration rule to event segments and get duration per timestep
+    final_categories, duration_event = _apply_duration_rule(categories, steps_per_day, max_category)
+
+    # Mask of AR events
+    mask = final_categories > 0
+
+    # Compute cumulative IVT over AR events
+    cumulative_ivt = cumulative_reset(original_ivt, mask)
+
+    # Extract IVT values only during AR events, zero elsewhere
+    ivt_event = np.where(mask, original_ivt, 0)
+
+    # Return final categories, cumulative IVT, IVT-only, duration-only arrays
+    return final_categories, cumulative_ivt, ivt_event, duration_event

arcat-0.1.0/arcat/core_v1.py

@@ -0,0 +1,131 @@
+"""
+Core AR categorization algorithms.
+
+Contains:
+- Event-based scheme
+- Evolution-based scheme
+"""
+
+import numpy as np
+from .utils import (
+    compute_steps_per_day,
+    bin_ivt,
+    cumulative_reset,
+    max_bounded_replace,
+)
+
+
+def _adjust_segment(arr, start, end, duration, steps_per_day):
+    """
+    Apply duration adjustment rule to a segment.
+
+    Rules:
+    - < 1 day  -> downgrade
+    - 1–2 days -> unchanged
+    - >= 2 days -> upgrade
+    """
+    if duration < steps_per_day:
+        arr[start:end] -= 1
+    elif duration >= 2 * steps_per_day:
+        arr[start:end] += 1
+
+
+def _apply_duration_rule(categories, steps_per_day, max_category):
+    """
+    Apply duration adjustment to continuous AR events.
+
+    Events are defined as consecutive timesteps
+    where category > 0.
+    """
+    final = categories.copy()
+    n = len(categories)
+    start = None
+
+    for i in range(n):
+        if categories[i] == 0:
+            if start is not None:
+                end = i
+                duration = end - start
+                _adjust_segment(final, start, end, duration, steps_per_day)
+                start = None
+        else:
+            if start is None:
+                start = i
+
+    if start is not None:
+        end = n
+        duration = end - start
+        _adjust_segment(final, start, end, duration, steps_per_day)
+
+    return np.clip(final, 0, max_category)
+
+
+# ============================================================
+# EVENT-BASED SCHEME
+# ============================================================
+
+def AR_categorization_scheme(
+    ivt_array: np.ndarray,
+    time_resolution_hours: int = 6,
+    bin_width: float = 250.0,
+    max_category: int = 6,
+):
+    """
+    Event-based AR categorization.
+
+    Steps:
+    1. Bin IVT into categories
+    2. Collapse each AR event to peak intensity
+    3. Apply duration rule to event
+    4. Compute cumulative IVT
+    """
+
+    steps_per_day = compute_steps_per_day(time_resolution_hours)
+
+    original_ivt = ivt_array.copy()
+
+    categories = bin_ivt(ivt_array, bin_width, max_category)
+    categories = max_bounded_replace(categories)
+
+    final_categories = _apply_duration_rule(
+        categories, steps_per_day, max_category
+    )
+
+    mask = final_categories > 0
+    cumulative_ivt = cumulative_reset(original_ivt, mask)
+
+    return final_categories, cumulative_ivt
+
+
+# ============================================================
+# EVOLUTION-BASED SCHEME
+# ============================================================
+
+def AR_categorization_evolution_scheme(
+    ivt_array: np.ndarray,
+    time_resolution_hours: int = 6,
+    bin_width: float = 250.0,
+    max_category: int = 6,
+):
+    """
+    Evolution-based AR categorization.
+
+    Same as event-based scheme except:
+    - Does NOT collapse event to peak intensity.
+    - Duration rule still applied event-wise.
+    """
+
+    steps_per_day = compute_steps_per_day(time_resolution_hours)
+
+    original_ivt = ivt_array.copy()
+
+    categories = bin_ivt(ivt_array, bin_width, max_category)
+
+    final_categories = _apply_duration_rule(
+        categories, steps_per_day, max_category
+    )
+
+    mask = final_categories > 0
+    cumulative_ivt = cumulative_reset(original_ivt, mask)
+
+    return final_categories, cumulative_ivt

arcat-0.1.0/arcat/utils.py

@@ -0,0 +1,86 @@
+"""
+Utility functions for AR categorization.
+"""
+
+import numpy as np
+
+
+def compute_steps_per_day(time_resolution_hours: int) -> int:
+    """
+    Compute number of timesteps per day.
+
+    Parameters
+    ----------
+    time_resolution_hours : int
+        Temporal resolution of input data in hours.
+
+    Returns
+    -------
+    int
+        Number of timesteps corresponding to 1 day.
+    """
+    return int(24 / time_resolution_hours)
+
+
+def bin_ivt(ivt_array: np.ndarray, bin_width: float, max_category: int):
+    """
+    Convert IVT values to AR categories.
+
+    IVT is divided into bins of size `bin_width`.
+
+    Example:
+        0–249   -> 0
+        250–499 -> 1
+        etc.
+    """
+    bins = np.floor(ivt_array / bin_width)
+    bins = np.clip(bins, 0, max_category)
+    return bins.astype(int)
+
+
+def cumulative_reset(values: np.ndarray, mask: np.ndarray):
+    """
+    Compute cumulative sum that resets when mask == 0.
+
+    Used to compute cumulative IVT per AR event.
+    """
+    result = np.zeros_like(values, dtype=float)
+    running_sum = 0.0
+
+    for i in range(len(values)):
+        if mask[i] == 0:
+            running_sum = 0.0
+        else:
+            running_sum += values[i]
+        result[i] = running_sum
+
+    return result
+
+
+def max_bounded_replace(arr: np.ndarray):
+    """
+    Replace each nonzero segment by its maximum value.
+
+    Example:
+        [1,2,3,0,2,1] -> [3,3,3,0,2,2]
+
+    Used in event-based scheme to collapse AR event
+    to peak intensity.
+    """
+    arr = arr.copy()
+    n = len(arr)
+    start = None
+
+    for i in range(n):
+        if arr[i] == 0:
+            if start is not None:
+                arr[start:i] = np.max(arr[start:i])
+                start = None
+        else:
+            if start is None:
+                start = i
+
+    if start is not None:
+        arr[start:n] = np.max(arr[start:n])
+
+    return arr

arcat-0.1.0/arcat/version.py

@@ -0,0 +1,8 @@
+"""
+Version file for arcat package.
+
+Version follows Semantic Versioning:
+MAJOR.MINOR.PATCH
+"""
+
+__version__ = "0.1.0"

arcat-0.1.0/arcat.egg-info/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: arcat
+Version: 0.1.0
+Summary: Atmospheric River Categorization Toolkit
+Author: Kwesi Twentwewa Quagraine
+Author-email: Kwesi Twentwewa Quagraine <kwsquagraine@gmail.com>
+License: MIT
+Keywords: atmospheric rivers,ivt,weather,extremes,python
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: xarray
+Requires-Dist: dask
+Requires-Dist: numba
+Requires-Dist: tqdm
+
+# ARCat: Atmospheric River Categorization Toolkit
+
+**ARCat** is a Python package for **categorizing Atmospheric River (AR) events** based on Integrated Vapor Transport (IVT) data. It provides:
+
+- **Event-based AR categorization**: Collapses each AR event to its peak intensity.
+- **Evolution-based AR categorization**: Preserves the intensity evolution within AR events.
+
+Additionally, ARCat computes:
+
+- **Cumulative IVT** per AR event.
+- **IVT-only values** for each AR event.
+- **Duration-only values** (number of timesteps per event).
+
+It is fully compatible with **NumPy arrays**, **xarray**, and **Dask**, allowing analysis of large datasets efficiently.
+
+---
+
+## Features
+
+- Event-based and evolution-based AR categorization.
+- Automatic handling of duration rules:
+  - Events < 1 day → downgrade category
+  - Events 1–2 days → unchanged
+  - Events ≥ 2 days → upgrade category
+- Maximum category enforcement.
+- Option to extract IVT-only and duration-only arrays.
+- Easy integration with **xarray/Dask** for large datasets.
+- Fully documented and tested, with CI support.
+
+---
+
+## Installation
+
+Clone the repository and install locally:
+
+```bash
+git clone https://github.com/yourusername/arcat.git
+cd arcat
+pip install -e .
+````
+## Quick Start
+
+### Import the package
+
+```python
+import numpy as np
+from arcat.core import AR_categorization_scheme, AR_categorization_evolution_scheme
+```
+
+### Prepare your IVT array
+
+```python
+# Example: random IVT values for demonstration
+ivt = np.random.rand(20) * 1500  # IVT in kg/m/s
+```
+
+### Event-based AR categorization
+
+```python
+# Run the event-based AR scheme
+final_cat, cum_ivt, ivt_event, duration_event = AR_categorization_scheme(
+    ivt,
+    time_resolution_hours=6,  # Data resolution in hours
+    bin_width=250.0,           # IVT bin size
+    max_category=6             # Maximum AR category
+)
+
+print("Categorized AR events:", final_cat)
+print("Cumulative IVT:", cum_ivt)
+print("IVT-only values:", ivt_event)
+print("Duration per timestep:", duration_event)
+```
+
+### Evolution-based AR categorization
+
+```python
+# Run the evolution-based AR scheme
+final_cat, cum_ivt, ivt_event, duration_event = AR_categorization_evolution_scheme(
+    ivt,
+    time_resolution_hours=6,  # Data resolution in hours
+    bin_width=250.0,           # IVT bin size
+    max_category=6             # Maximum AR category
+)
+
+print("Evolution categories:", final_cat)
+print("Cumulative IVT:", cum_ivt)
+print("IVT-only values:", ivt_event)
+print("Duration per timestep:", duration_event)
+```
+
+---
+
+## Parameters
+
+| Parameter               | Description                                             |
+| ----------------------- | ------------------------------------------------------- |
+| `ivt_array`             | 1D NumPy array of IVT values (kg/m/s)                   |
+| `time_resolution_hours` | Temporal resolution of your data in hours (default: 6)  |
+| `bin_width`             | Width of each IVT bin for categorization (default: 250) |
+| `max_category`          | Maximum AR category (default: 6)                        |
+
+---
+
+## Returns
+
+1. `final_categories`: Array of AR categories (1–6) after duration adjustments.
+2. `cumulative_ivt`: Cumulative IVT during AR events.
+3. `ivt_event`: Original IVT values during AR events (0 elsewhere).
+4. `duration_event`: Number of timesteps per AR event (0 elsewhere).
+
+---
+
+## Usage Notes
+
+* Event-based scheme collapses each AR event to its maximum intensity (`max_bounded_replace`).
+* Evolution-based scheme preserves temporal evolution of IVT within AR events.
+* Duration rules are applied **per continuous AR segment**.
+* Works with any **NumPy array**, and can be integrated with **xarray or Dask arrays** for large datasets.
+
+---
+## Adopting for xarray data
+```python
+final_cat, cum_ivt, ivt_event, duration_event = xr.apply_ufunc(AR_categorization_scheme, 
+                             Ivt_ds['IVT'].as_numpy(),
+                             input_core_dims = [['time']],
+                             output_core_dims = [['time'],['time'],['time'],['time']],
+                             vectorize=True,  # Auto-vectorize over lat/lon
+                             dask='parallelized',  # Enable parallelization using Dask
+                             output_dtypes=[np.int8,np.float32,np.float32, np.int8])
+
+```
+
+## Contributing
+
+We welcome contributions! Please follow these steps:
+
+1. Fork the repository
+2. Create a new branch: `git checkout -b feature-name`
+3. Make your changes
+4. Run tests
+5. Submit a pull request
+
+---
+
+## License
+
+This project is licensed under the [Creative Commons License](https://web.archive.org/web/20230202010104/https://creativecommons.org/licenses/by/4.0/).
+
+---
+
+## References
+
+* Ralph, F. M., Rutz, J. J., Cordeira, J. M., Dettinger, M., Anderson, M., Reynolds, D., ... & Smallcomb, C. (2019). A scale to characterize the strength and impacts of atmospheric rivers. Bulletin of the American Meteorological Society, 100(2), 269-289.
+* Visit the [Atmospheric River Tracking Model Intercomparison Project (ARTMIP)](https://ncar.github.io/ARTMIP/intro.html) to follow Atmospheric River community research and publications.

arcat-0.1.0/arcat.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+setup.cfg
+arcat/__init__.py
+arcat/core.py
+arcat/core_v1.py
+arcat/utils.py
+arcat/version.py
+arcat.egg-info/PKG-INFO
+arcat.egg-info/SOURCES.txt
+arcat.egg-info/dependency_links.txt
+arcat.egg-info/requires.txt
+arcat.egg-info/top_level.txt
+tests/test_core.py

arcat-0.1.0/arcat.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

arcat-0.1.0/arcat.egg-info/requires.txt

@@ -0,0 +1,5 @@
+numpy
+xarray
+dask
+numba
+tqdm

arcat-0.1.0/arcat.egg-info/top_level.txt

@@ -0,0 +1 @@
+arcat

arcat-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "arcat"
+version = "0.1.0"
+description = "Atmospheric River Categorization Toolkit"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+    { name = "Kwesi Twentwewa Quagraine", email = "kwsquagraine@gmail.com" }
+]
+keywords = ["atmospheric rivers", "ivt", "weather","extremes", "python"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent"
+]
+
+dependencies = [
+    "numpy",
+    "xarray",
+    "dask",
+    "numba",
+    "tqdm"
+]

arcat-0.1.0/setup.cfg

@@ -0,0 +1,28 @@
+[metadata]
+name = arcat
+version = 0.1.0
+description = Atmospheric River Categorization Toolkit
+long_description = file: README.md
+long_description_content_type = text/markdown
+author = Kwesi Twentwewa Quagraine
+license = MIT
+keywords = atmospheric rivers, ivt, climate
+classifiers = 
+	Programming Language :: Python :: 3
+	License :: OSI Approved :: MIT License
+	Operating System:: OS Independent
+
+[options]
+packages = find:
+python_requires = >=3.8
+install_requires = 
+	numpy
+	xarray
+	dask
+	numba
+	tqdm
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

arcat-0.1.0/tests/test_core.py

@@ -0,0 +1,28 @@
+import numpy as np
+from arcat.core import AR_categorization_scheme, AR_categorization_evolution_scheme
+
+
+def test_short_event_downgrade():
+    ivt = np.array([300, 300, 0])
+    final_cat, cum_ivt, ivt_event, duration_event = AR_categorization_scheme(
+        
+        ivt,
+        time_resolution_hours=6,  # Data resolution in hours
+        bin_width=250.0,           # IVT bin size
+        max_category=6             # Maximum AR category
+    )
+    
+    assert np.all(final_cat[:2] == 0)
+
+# Run the event-based AR scheme
+def test_long_event_upgrade():
+    ivt = np.array([800] * 12)
+    # Run the evolution-based AR scheme
+    final_cat, cum_ivt, ivt_event, duration_event = AR_categorization_evolution_scheme(
+        ivt,
+        time_resolution_hours=6,  # Data resolution in hours
+        bin_width=250.0,           # IVT bin size
+        max_category=6             # Maximum AR category
+    )
+
+    assert np.all(final_cat >= 3)