# PhenoPhyto

A Python package for detecting and visualizing phytoplankton bloom phenology from chlorophyll time series data.

`PhenoPhyto` is designed for researchers and scientists in oceanography and environmental science. It provides tools to identify phytoplankton bloom events (initiation, peak, and termination) using threshold-based methods and to visualize these events with clear, customizable plots. The package supports both spatially explicit (with latitude and longitude) and non-spatial chlorophyll data, making it versatile for various datasets.

## Installation

Install `PhenoPhyto` via pip:

```bash
pip install PhenoPhyto
```

This will automatically install required dependencies: `pandas`, `numpy`, `scipy`, `matplotlib`, and `seaborn`.

## Quick Start

To get started, you need a pandas DataFrame with chlorophyll time series data. Below is an example using non-spatial data:

```python
import pandas as pd
import numpy as np

# Sample data
df = pd.DataFrame({
    'day_of_year': np.arange(1, 366),
    'CHL': np.random.rand(365) * 10  # Simulated chlorophyll values
})

# Detect bloom events
from phenophy.detection import detect_phyto_pheno_3
bloom_data = detect_phyto_pheno_3(df, time_col='day_of_year', chl_col='CHL', threshold_percent=10)

# Visualize bloom events
from phenophy.plotting import plot_bloom_events
plot_bloom_events(df, bloom_data, region_name='Sample Region')
```

This code generates a plot showing the chlorophyll concentration over time with highlighted bloom periods.

For spatially explicit data (e.g., with latitude and longitude), use `detect_phyto_pheno_1` (daily data) or `detect_phyto_pheno_2` (weekly data). Example:

```python
# Sample spatial data
df_spatial = pd.DataFrame({
    'latitude': [40.0, 40.0, 41.0, 41.0],
    'longitude': [-70.0, -70.0, -71.0, -71.0],
    'day': [1, 2, 1, 2],
    'CHL': [1.5, 2.0, 1.8, 2.2]
})

from phenophy.detection import detect_phyto_pheno_1
result = detect_phyto_pheno_1(df_spatial, lat_col='latitude', lon_col='longitude', time_col='day', chl_col='CHL')
print(result)
```

## API Reference

### `detection` Module
| Function | Description |
|----------|-------------|
| `find_peaks_from_chl_data(data, time_col, chl_col, threshold)` | Detects peaks in chlorophyll data above a specified threshold using `scipy.signal.find_peaks`. |
| `detect_phyto_pheno_1(df, lat_col='latitude', lon_col='longitude', time_col='day', chl_col='CHL', ...)` | Detects bloom phenology from daily climatology data with spatial grouping by latitude and longitude. Returns a DataFrame with bloom indices (initiation, peak, termination, duration, and corresponding months). |
| `detect_phyto_pheno_2(df, lat_col='latitude', lon_col='longitude', time_col='week', chl_col='CHL', ...)` | Detects bloom phenology from weekly climatology data with spatial grouping. Similar to `detect_phyto_pheno_1` but for weekly data. |
| `detect_phyto_pheno_3(df, time_col='day_of_year', chl_col='CHL', ...)` | Detects bloom events from time series data without spatial information. Returns a dictionary with median chlorophyll, threshold, and bloom event details. |

### `plotting` Module
| Function | Description |
|----------|-------------|
| `plot_bloom_events(df, bloom_data, region_name='Region', ...)` | Creates a plot of chlorophyll time series with highlighted bloom periods, using a rainbow color scheme for each bloom event. Requires output from `detect_phyto_pheno_3`. |

For detailed parameter descriptions and return values, refer to the docstrings of each function.

## Data Requirements
- **Non-spatial data** (`detect_phyto_pheno_3`): A pandas DataFrame with at least two columns: a time column (e.g., `day_of_year`) and a chlorophyll column (e.g., `CHL`).
- **Spatial data** (`detect_phyto_pheno_1` or `detect_phyto_pheno_2`): A pandas DataFrame with columns for latitude, longitude, time (e.g., `day` or `week`), and chlorophyll values.
- Ensure chlorophyll values are numeric and the DataFrame is not empty to avoid errors.

## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing
Contributions are welcome! Please open an issue or submit a pull request on GitHub. For guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).

