PhenoPhyto 0.2.7

PhenoPhyto: A python package for detecting and visualizing phytoplankton bloom phenology events

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:

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:

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:

# 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.txt file for details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub. For guidelines, see CONTRIBUTING.md.