Metadata-Version: 2.4
Name: acycle
Version: 0.6.5
Summary: AcyclePy: Advanced cyclostratigraphy toolkit
Author-email: Meng Wang <grampus90@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/mingsongli/AcyclePy
Project-URL: Repository, https://github.com/mingsongli/AcyclePy.git
Project-URL: Issue Tracker, https://github.com/mingsongli/AcyclePy.git/issues
Project-URL: Documentation, https://github.com/mingsongli/AcyclePy/tree/main/doc
Keywords: cyclostratigraphy,time-series,spectral,wavelet,geology
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: PySide6>=6.0.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: scipy>=1.6.0
Requires-Dist: scikit-image>=0.18.0
Requires-Dist: scikit-learn>=0.24.0
Requires-Dist: Pillow>=8.0.0
Requires-Dist: qt-material>=2.0.0
Requires-Dist: astropy>=5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Provides-Extra: full
Requires-Dist: sounddevice>=0.4.0; extra == "full"
Requires-Dist: h5py>=3.0.0; extra == "full"
Requires-Dist: netCDF4>=1.5.0; extra == "full"
Dynamic: license-file

# AcyclePy — Advanced Cyclostratigraphy and Time Series Analysis Toolkit

[![PyPI](https://img.shields.io/pypi/v/acycle)](https://pypi.org/project/acycle/)
[![Python](https://img.shields.io/pypi/pyversions/acycle)](https://pypi.org/project/acycle/)
[![License](https://img.shields.io/pypi/l/acycle)](LICENSE)

AcyclePy is the Python library companion to the **Acycle** desktop application for cyclostratigraphy, time series analysis, and paleoclimate research. It provides both a programmatic API for scripting and batch processing, and the full suite of Acycle desktop GUI tools.

**Reference**: Li, M., Hinnov, L., & Kump, L. (2019). Acycle: Time-series analysis software for paleoclimate research and education. *Computers & Geosciences*, 127, 12-22.

---

## Installation

`ash
pip install acycle
`

Requirements: Python >= 3.8, numpy, scipy, pandas, matplotlib, PySide6, scikit-image, scikit-learn, Pillow, qt-material, astropy.

---

## Quick Start — Programmatic API

`python
import acycle as ac
import numpy as np

# Read time series data
s = ac.read_series("data.txt")                    # auto-detect whitespace/tab/comma
s = ac.read_series("data.csv", delimiter=",")     # explicit delimiter

# Chain operations (fluent API)
s2 = s.clean(sort=True)                           \
      .interpolate(step=0.33)                     \
      .detrend(window=80)                         \
      .standardize()

# Spectral analysis
from acycle import spectral
freq, power = spectral._periodogram(s2.y)
freq, power = spectral._mtm_spectrum(s2.y)        # multitaper
freq, power = spectral._lomb_scargle_spectrum(s2.x, s2.y)  # uneven spacing

# Wavelet analysis
from acycle import wavelet
period, power, coi, significance = wavelet.cwt(s2.y, dt=s2.dt)
coherence = wavelet.wavelet_coherence(s1.y, s2.y, dt=s1.dt)

# Filtering
from acycle import filter as ft
result = ft.apply_filter(y, dt=0.2, kind="bandpass", flow=0.01, fhigh=0.05)

# Age modeling
from acycle import age
model = age.build_age_model(depth, y, cycle_period=405)
depth, age = age.tune(depth, y, model)

# Load built-in datasets
lr04 = ac.load_example("lr04")                     # LR04 benthic stack
cenogrid = ac.load_example("cenogrid_d18o")        # CENOGRID d18O
`

### Result Objects

All analysis functions return structured result objects with a consistent interface:

`python
psd = PSD(frequency=freq, power=power)
psd.to_dataframe()                # export to pandas DataFrame
psd.save("my_spectrum")           # save to CSV (my_spectrum_spectrum.csv)
psd.plot()                        # matplotlib figure

# Same interface for all result types:
# EvolutiveSpectrum, WaveletResult, FilterResult, AgeModel, CocoResult, SedNoiseResult
`

---

## CLI Tools (Acycle Desktop GUI)

These commands launch the original Acycle desktop GUI tools bundled with the package:

`ash
acycle-imageprocessor          # Image digitizing and data extraction
acycle-plot                    # PlotPro — publication-quality plotting
acycle-interpolation           # Advanced interpolation with gap filling
acycle-data-extractor          # Extract data segments by range
acycle-section-remover         # Remove sections from time series
acycle-gap-adder               # Insert gaps into data
acycle-data-clipper            # Clip data by threshold
acycle-image-analyzer          # Advanced image analysis
`

---

## API Reference

### Series Operations

| Method | Description |
|--------|-------------|
| Series.from_file(path) | Read from a delimited text file |
| .clean(sort, duplicate, dropna) | Sort, deduplicate, drop NaN |
| .interpolate(step, method) | Interpolate to uniform grid |
| .interpolate_pro(step, method) | Advanced interpolation with gap filling |
| .detrend(window, method) | Remove trend (lowess, loess, polynomial, savgol, moving_mean) |
| .standardize() | Z-score standardization |
| .log10(handle_nonpositive) | Base-10 logarithm |
| .derivative(order) | Numerical derivative |
| .prewhiten(method) | Prewhitening |
| .select(start, stop) | Sub-range selection |
| .moving_average(n) | Moving average smoothing |
| .gaussian_smooth(n, sigma) | Gaussian smoothing |
| .moving_median(n) | Moving median smoothing |
| .multiply(other_series) | Element-wise multiply with another series |
| .clip_by_threshold(threshold) | Clip or remove data by threshold |
| .to_dataframe() | Export to pandas DataFrame |
| .copy() | Deep copy |

### Spectral Analysis (cycle.spectral)

| Function | Description |
|----------|-------------|
| _periodogram(y, dt) | Classical periodogram |
| _mtm_spectrum(y, dt, nw) | Multitaper method |
| _lomb_scargle_spectrum(x, y) | Lomb-Scargle (uneven spacing) |
| _estimate_ar1_rho(y) | AR(1) lag-1 autocorrelation |
| _estimate_ar1_noise(y, dt) | AR(1) noise background |
| _ftest_mtm(y, dt, nw) | F-test for significant peaks |

### Wavelet Analysis (cycle.wavelet)

| Function | Description |
|----------|-------------|
| cwt(y, dt) | Continuous wavelet transform (Torrence & Compo 1998) |
| wavelet_coherence(y1, y2, dt) | Wavelet coherence and phase |

### Filtering (cycle.filter)

| Function | Description |
|----------|-------------|
| pply_filter(y, dt, kind) | Bandpass/lowpass/highpass (gaussian, butterworth, etc.) |
| dynamic_filter(x, y, window) | Sliding-window dynamic filtering |
| mplitude_modulation(x, y, flow, fhigh) | Envelope extraction |

### Age Modeling (cycle.age)

| Function | Description |
|----------|-------------|
| uild_age_model(x, y, cycle_period) | Age model from cycle counting |
| sedrate_to_age_model(depth, sedrate) | Convert sedimentation rate to age model |
| 	une(depth, y, age_model) | Depth-to-time conversion |
| stratigraphic_correlation(ref, target, tie_points) | Correlate two stratigraphic sections |

### Preprocessing (cycle.preprocess)

| Function | Description |
|----------|-------------|
| detrend(x, y, window, method) | Remove trend |
| clip_by_threshold(x, y, threshold) | Clip by value |
| 
emove_sections(x, y, sections) | Remove data ranges |
| dd_gaps(x, y, gaps) | Insert NaN-filled gaps |
| 
emove_peaks(y, ymin, ymax) | Remove or cap peaks |
| multiply_series(x, y1, y2) | Element-wise multiply two series |
| merge_series(series_list) | Merge multiple series by x grid |
| pca(data, n_components) | Principal component analysis |
| changepoint(y, method) | Changepoint detection |
| 	ransform_xy(x, y, a, b, c, d) | Affine coordinate transform |
| ind_extreme(x, y, kind) | Find max or min in range |

---

## Author

**Meng Wang** — [grampus90@gmail.com](mailto:grampus90@gmail.com)

## Citation

If you use AcyclePy in your research, please cite:

> Li, M., Hinnov, L., & Kump, L. (2019). Acycle: Time-series analysis software for paleoclimate research and education. *Computers & Geosciences*, 127, 12–22. https://doi.org/10.1016/j.cageo.2019.02.011

## License

MIT License — see [LICENSE](LICENSE) file for details.

## Links

- [PyPI](https://pypi.org/project/acycle/)
- [Repository](https://github.com/mingsongli/AcyclePy)
- [Documentation](https://github.com/mingsongli/AcyclePy/tree/main/doc)
- [Issue Tracker](https://github.com/mingsongli/AcyclePy/issues)
