Metadata-Version: 2.4
Name: palmwtc
Version: 0.2.7
Summary: Automated whole-tree chamber workflow for oil-palm ecophysiology — QC, flux calculation, science validation.
Project-URL: Homepage, https://github.com/adisapoetro/palmwtc
Project-URL: Documentation, https://adisapoetro.github.io/palmwtc/
Project-URL: Repository, https://github.com/adisapoetro/palmwtc
Project-URL: Issues, https://github.com/adisapoetro/palmwtc/issues
Project-URL: Changelog, https://github.com/adisapoetro/palmwtc/blob/main/CHANGELOG.md
Author-email: Didi Adisaputro <saputrozokovic@gmail.com>
Maintainer-email: Didi Adisaputro <saputrozokovic@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Didi Adisaputro
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: co2-flux,digital-twin,ecophysiology,ecosystem-science,flux-chamber,h2o-flux,li-cor-850,oil-palm,whole-tree-chamber,xpalm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.11
Requires-Dist: ipykernel<7.0,>=6.29
Requires-Dist: jinja2<4.0,>=3.1
Requires-Dist: joblib<2.0,>=1.3
Requires-Dist: matplotlib<4.0,>=3.8
Requires-Dist: nbconvert<8.0,>=7.16
Requires-Dist: nbformat<6.0,>=5.10
Requires-Dist: numpy<3.0,>=1.26
Requires-Dist: openpyxl<4.0,>=3.1
Requires-Dist: pandas<3.0,>=2.1
Requires-Dist: papermill<3.0,>=2.6
Requires-Dist: plotly<7.0,>=5.18
Requires-Dist: pooch<2.0,>=1.8
Requires-Dist: pyarrow<22.0,>=15.0
Requires-Dist: python-dotenv<2.0,>=1.0
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: ruptures<2.0,>=1.1.9
Requires-Dist: scipy<2.0,>=1.11
Requires-Dist: seaborn<1.0,>=0.13
Requires-Dist: tqdm<5.0,>=4.66
Requires-Dist: typer<1.0,>=0.12
Provides-Extra: all
Requires-Dist: anywidget<1.0,>=0.9; extra == 'all'
Requires-Dist: build<2.0,>=1.2; extra == 'all'
Requires-Dist: ipywidgets<9.0,>=8.1; extra == 'all'
Requires-Dist: jupyter-book<2.0,>=1.0; extra == 'all'
Requires-Dist: mypy<2.0,>=1.10; extra == 'all'
Requires-Dist: myst-nb<2.0,>=1.1; extra == 'all'
Requires-Dist: nbstripout<1.0,>=0.7; extra == 'all'
Requires-Dist: pre-commit<5.0,>=3.7; extra == 'all'
Requires-Dist: pytest-cov<7.0,>=5.0; extra == 'all'
Requires-Dist: pytest<9.0,>=8.2; extra == 'all'
Requires-Dist: ruff<1.0,>=0.5; extra == 'all'
Requires-Dist: scikit-learn<2.0,>=1.4; extra == 'all'
Requires-Dist: sphinx-autoapi<4.0,>=3.1; extra == 'all'
Requires-Dist: sphinx-copybutton<1.0,>=0.5; extra == 'all'
Requires-Dist: torch<3.0,>=2.2; extra == 'all'
Requires-Dist: twine<7.0,>=5.0; extra == 'all'
Requires-Dist: types-pyyaml>=6.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: build<2.0,>=1.2; extra == 'dev'
Requires-Dist: mypy<2.0,>=1.10; extra == 'dev'
Requires-Dist: nbstripout<1.0,>=0.7; extra == 'dev'
Requires-Dist: pre-commit<5.0,>=3.7; extra == 'dev'
Requires-Dist: pytest-cov<7.0,>=5.0; extra == 'dev'
Requires-Dist: pytest<9.0,>=8.2; extra == 'dev'
Requires-Dist: ruff<1.0,>=0.5; extra == 'dev'
Requires-Dist: twine<7.0,>=5.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: jupyter-book<2.0,>=1.0; extra == 'docs'
Requires-Dist: myst-nb<2.0,>=1.1; extra == 'docs'
Requires-Dist: sphinx-autoapi<4.0,>=3.1; extra == 'docs'
Requires-Dist: sphinx-copybutton<1.0,>=0.5; extra == 'docs'
Provides-Extra: gpu
Requires-Dist: torch<3.0,>=2.2; extra == 'gpu'
Provides-Extra: interactive
Requires-Dist: anywidget<1.0,>=0.9; extra == 'interactive'
Requires-Dist: ipywidgets<9.0,>=8.1; extra == 'interactive'
Provides-Extra: ml
Requires-Dist: scikit-learn<2.0,>=1.4; extra == 'ml'
Provides-Extra: ml-merlion
Requires-Dist: salesforce-merlion<3.0,>=2.0; extra == 'ml-merlion'
Description-Content-Type: text/markdown

# palmwtc

**Automated whole-tree chamber workflow for oil-palm ecophysiology.**

[![PyPI](https://img.shields.io/pypi/v/palmwtc.svg)](https://pypi.org/project/palmwtc/)
[![Python](https://img.shields.io/pypi/pyversions/palmwtc.svg)](https://pypi.org/project/palmwtc/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![CI](https://github.com/adisapoetro/palmwtc/actions/workflows/ci.yml/badge.svg)](https://github.com/adisapoetro/palmwtc/actions/workflows/ci.yml)
[![DOI](https://zenodo.org/badge/1213667337.svg)](https://doi.org/10.5281/zenodo.19680893)

`palmwtc` is the data-processing and analysis pipeline for the first
automated whole-tree chamber (WTC) sized to enclose individual oil palm trees,
deployed at the LIBZ field site (Riau, Indonesia) and instrumented with
LI-COR LI-850 gas analyzers. It transforms raw sensor cycles into validated
CO₂ and H₂O fluxes, applies multi-stage quality control, and produces inputs
for the XPalm digital-twin calibration pipeline.

## What it does

```
raw chamber cycles  ──►  QC (rules + ML + breakpoints)  ──►  flux calculation  ──►  science validation
        │                                                                                  │
        └── 30-min weather + soil + tree biophysics ──┬───────────────────────────────────►┘
                                                       └── high-confidence calibration windows
```

End-to-end run on the bundled synthetic sample:

```bash
pip install palmwtc
palmwtc run            # uses bundled sample if no PALMWTC_DATA_DIR set
```

For your own data:

```bash
export PALMWTC_DATA_DIR=/path/to/your/chamber/data
palmwtc run --skip 022 025          # mirrors the original notebook-runner CLI
palmwtc run --notebooks             # papermill mode, produces HTML reports
```

## Install

```bash
pip install palmwtc                 # core only
pip install 'palmwtc[ml]'           # + scikit-learn IsolationForest QC
pip install 'palmwtc[interactive]'  # + ipywidgets / anywidget for Jupyter dashboards
pip install 'palmwtc[gpu]'          # + torch (Apple-Silicon MPS / CUDA)
pip install 'palmwtc[all]'          # everything
```

Requires Python 3.11–3.13.

## Library use

```python
from palmwtc.config import DataPaths
from palmwtc.qc import QCProcessor
from palmwtc.flux import calculate_flux_cycles

paths = DataPaths.resolve()                     # layered: CLI → env → yaml → sample
qc_result = QCProcessor(paths).run("CO2_C1")
flux = calculate_flux_cycles(qc_result.data)
```

Full API reference: [adisapoetro.github.io/palmwtc/api/](https://adisapoetro.github.io/palmwtc/api/)

## Citation

If you use `palmwtc` in scientific work, please cite the Zenodo DOI. The
**concept DOI** [10.5281/zenodo.19680893](https://doi.org/10.5281/zenodo.19680893)
always resolves to the latest version; to cite a specific release, use
its own version DOI (visible on the [Zenodo record](https://zenodo.org/records/19680893)
→ *Versions* panel).

```bibtex
@software{adisaputro_palmwtc_2026,
  author  = {Adisaputro, Didi},
  title   = {palmwtc: Automated whole-tree chamber workflow for oil-palm ecophysiology},
  year    = {2026},
  version = {0.2.0},
  doi     = {10.5281/zenodo.19680893},
  url     = {https://github.com/adisapoetro/palmwtc},
}
```

See [`CITATION.cff`](CITATION.cff) for machine-readable metadata.

## Background

Most ecosystem-scale flux measurements over oil-palm plantations use eddy
covariance, which integrates over hectares of canopy and cannot resolve
single-tree behaviour. `palmwtc` is built around a different instrument: an
*automated whole-tree chamber*, sized and ventilated to enclose an individual
mature oil palm, with an LI-COR LI-850 gas analyzer cycling open and closed on
a programmed schedule. This is, to our knowledge, the first WTC deployment for
oil palm — the WTC method was previously applied to temperate broadleaf
species (Medlyn et al. 2016).

### What does an automated whole-tree chamber look like?

The illustration below shows **one concrete example** — the LIBZ chamber from
which `palmwtc` was originally developed (Riau, Indonesia; whole-tree chamber
around an individual mature oil palm; aboveground sensor pole carrying sonic
anemometers, temperature/humidity sensors, and LI-850 air inlets at five
heights; underground TEROS-21 + Watermark sensors at five depths).

![Example whole-tree flux chamber — the LIBZ deployment in Riau, Indonesia. Other implementations may differ in dimensions, tree species, sensor layout, and instrumentation.](https://raw.githubusercontent.com/adisapoetro/palmwtc/main/docs/_static/example_chamber_libz.png)

**This is one possible implementation, not a specification.** `palmwtc` is a
generic toolkit — it does not assume any one chamber design. Other deployments
will differ in:

- **Chamber dimensions** — `palmwtc` takes the chamber volume as a
  configuration input; chambers from a few cubic metres to large enclosures
  all work.
- **Tree species and growth form** — the package is not oil-palm-specific;
  any plant that fits in a closed chamber can be processed.
- **Sensor pole design** — the number of heights and the sensor mix (sonic
  anemometer, T/RH, PAR, gas-analyser inlets) varies per deployment.
- **Soil instrumentation** — depth count and sensor brand (TEROS-21,
  Watermark, TDR, capacitance) varies per deployment.
- **Datalogger choice** — Campbell Scientific is one common option; others
  work as long as the data files can be loaded.

`palmwtc` consumes whatever data your chamber produces and computes flux. The
hardware, materials, and dimensions are out of scope for the package itself —
they belong to your specific field setup.

## Contributing

See [`CONTRIBUTING.md`](CONTRIBUTING.md). Bug reports and feature requests:
[github.com/adisapoetro/palmwtc/issues](https://github.com/adisapoetro/palmwtc/issues).

## License

MIT — see [`LICENSE`](LICENSE).
