Metadata-Version: 2.4
Name: facpy
Version: 0.1.1
Summary: Field-Aligned Current Python toolkit for SWARM satellite analysis
Author-email: Edwin Ayabie <edwinayabie@example.com>
Project-URL: Homepage, https://github.com/madvirus-ops/facpy
Project-URL: Bug Tracker, https://github.com/madvirus-ops/facpy/issues
Project-URL: Documentation, https://github.com/madvirus-ops/facpy#readme
Project-URL: Source Code, https://github.com/madvirus-ops/facpy
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: polars
Requires-Dist: xarray
Requires-Dist: netCDF4
Requires-Dist: cdflib
Requires-Dist: cartopy
Requires-Dist: matplotlib
Requires-Dist: scipy
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"

# facpy: Field-Aligned Current Python Toolkit

[![PyPI version](https://badge.fury.io/py/facpy.svg)](https://badge.fury.io/py/facpy)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**facpy** is a research-grade Python package designed for standardized, fast, and reproducible analysis of Swarm satellite Field-Aligned Currents (FAC). It is optimized for quiet-time studies, regional analysis (e.g., Africa), and interhemispheric comparisons.

## 🚀 Key Features

*   **Data Loading**: Efficient loading of Swarm Level 2 FAC data (CDF and NetCDF formats) into Polars DataFrames.
*   **Quiet Time Selection**: Automatic selection of quietest days based on Kp (sum/max) or Dst (min) geomagnetic indices.
*   **Geospacial Tools**:
    *   Region-based filtering (presets for Africa, Europe, Polar Caps, etc.).
    *   Solar Local Time (SLT) calculation.
    *   Hemisphere separation.
*   **Gridding**: Fast aggregation of point data into regular 2D (Lat/Lon) or 3D (Lat/Lon/LT) grids using vectorization.
*   **Interhemispheric Analysis (IHFAC)**: Tools to compare Northern and Southern hemisphere currents (Difference, Ratio) with automatic coordinate alignment.
*   **Visualization**: Publication-ready map generation using `cartopy`.

## 📦 Installation

**facpy** requires Python 3.9+.

```bash
# Install from PyPI
pip install facpy

# Or install from source
git clone https://github.com/madvirus-ops/facpy
cd facpy
pip install .

# Install with development dependencies
pip install ".[dev]"
```

## ⚡ Quick Start

Here is a complete workflow example demonstrating loading, filtering, gridding, and mapping.

```python
import facpy
from facpy import io, quiet, geo, grid, plot
import polars as pl

# 1. Load Data
# Supports single file or list of files (CDF/NetCDF)
df = io.load_swarm_fac("SW_OPER_FAC_A_20210101.cdf")

# 2. Select Quiet Days
# Get the 5 quietest days in Jan 2021 based on Kp index
quiet_dates = quiet.quiet_days(
    start_date="2021-01-01", 
    end_date="2021-01-31", 
    method="kp", 
    top_n=5,
    index_file="kp_index.txt" # Path to your index file
)

# Filter dataframe
df = df.filter(pl.col("timestamp").dt.date().is_in(quiet_dates))

# 3. Filter Region & Add Local Time
# Focus on Africa and calculate Solar Local Time
df_africa = geo.filter_region(df, region="africa")
df_africa = geo.add_local_time(df_africa)

# 4. Grid the Data
# Create a 2°x2° grid of Mean FAC values
ds_grid = grid.grid_fac(
    df_africa, 
    resolution=(2.0, 2.0), 
    statistic="mean"
)

# 5. Plot
# Generate a map using built-in Cartopy plotter
plot.fac_map(
    ds_grid, 
    title="Quiet Time Mean FAC - Africa", 
    projection="platecarree"
)
```

## 📚 Module Overview

### `facpy.io`
Handles file I/O.
*   `load_swarm_fac()`: Reads data, handles fill values, and normalizes column names.

### `facpy.quiet`
Geomagnetic activity selection.
*   `quiet_days()`: Returns dates of low activity defined by Kp or Dst.

### `facpy.geo`
Coordinate and spatial tools.
*   `filter_region()`: Spatial subsetting.
*   `add_local_time()`: Computes SLT from UTC and Longitude.

### `facpy.grid`
Aggregation logic.
*   `grid_fac()`: Converts track data to `xarray.Dataset` grids. Supports multiple statistics (mean, median, std, count).

### `facpy.ihfac`
Interhemispheric analysis.
*   `compare()`: Aligns South hemisphere data to North coordinates and computes difference or ratio maps.

### `facpy.plot`
Visualization.
*   `fac_map()`: Wrapper around Cartopy for quick, consistent FAC maps.

## 🧪 Testing

Run the test suite to ensure everything is working correctly:

```bash
pytest tests/
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
