Metadata-Version: 2.5
Name: tpxlab
Version: 0.2.2
Summary: Reproducible analysis of temperature-programmed catalyst characterization data.
Project-URL: Homepage, https://github.com/hdkim99/TPxLab
Project-URL: Documentation, https://github.com/hdkim99/TPxLab/tree/main/docs
Project-URL: Issues, https://github.com/hdkim99/TPxLab/issues
Project-URL: Source, https://github.com/hdkim99/TPxLab
Author: Hyun Dong Kim
License: MIT License
        
        Copyright (c) 2026 Hyun Dong Kim
        
        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: TPD,TPO,TPR,catalysis,deconvolution,peak fitting
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: openpyxl>=3.1
Requires-Dist: pandas>=2.1
Requires-Dist: pint>=0.23
Requires-Dist: scipy>=1.11
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pandas-stubs>=2.1; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

# TPxLab

> Reproducible global deconvolution and quantification of temperature-programmed catalyst data.

[![CI](https://github.com/hdkim99/TPxLab/actions/workflows/ci.yml/badge.svg)](https://github.com/hdkim99/TPxLab/actions/workflows/ci.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/hdkim99/TPxLab/blob/main/LICENSE)

TPxLab turns CSV/XLSX TPR, TPD, and TPO curves into inspectable baseline corrections,
editable peak components, simultaneous mixed-model fits, coordinate-aware integrals,
unit-checked quantities, diagnostics, figures, and reproducible exports. One
`AnalysisService` powers the Python API, CLI, and Tkinter GUI.

![Actual TPxLab global deconvolution of the bundled overlapping example](https://raw.githubusercontent.com/hdkim99/TPxLab/main/docs/tpxlab-global-deconvolution.png)

## Install

Install the current stable release from PyPI:

```bash
python -m pip install tpxlab
```

For development or to run the bundled examples from a source checkout:

```bash
git clone https://github.com/hdkim99/TPxLab.git
cd TPxLab
python -m pip install -e .
```

The repository social-preview candidate is the
[actual bundled-example result](https://raw.githubusercontent.com/hdkim99/TPxLab/main/docs/tpxlab-social-preview.png),
not a mock interface.

## 30-second global quickstart

For the bundled overlapping example in a source checkout:

```bash
tpxlab analyze examples/overlapping_tpr.csv \
  --components-config examples/overlapping_components.json \
  --baseline linear \
  --output examples/output/global-analysis.xlsx \
  --figure examples/output/global-analysis.png

tpxlab-gui
```

The GUI follows: load and map columns/units -> baseline and detect -> add/update/remove
components -> choose model, center/width bounds, fixed/shared width constraints -> fit and
quantify -> inspect components/total/residual -> export. Every edit is passed through the
service to the same scientific core used by the CLI.

## Python API

```python
from tpxlab import AnalysisService, AnalysisSettings, PeakSeed
from tpxlab.io import load_raw_data

raw = load_raw_data("examples/overlapping_tpr.csv")
components = [
    PeakSeed(
        332,
        220,
        540,
        model="gaussian",
        center_lower=310,
        center_upper=350,
        width_lower=5,
        width_upper=35,
    ),
    PeakSeed(
        373,
        220,
        540,
        model="lorentzian",
        center_lower=355,
        center_upper=390,
        width_lower=4,
        width_upper=25,
    ),
    PeakSeed(
        414,
        220,
        540,
        model="voigt",
        center_lower=395,
        center_upper=430,
        width_lower=4,
        width_upper=28,
    ),
]
result = AnalysisService().analyze(
    raw,
    AnalysisSettings(baseline_method="linear", fit_mode="global"),
    components,
)
print(result.global_fit.identifiable, result.global_fit.statistics.r_squared)
```

## Support status in v0.2.x

| Capability | Status | Notes |
|---|---|---|
| CSV and XLSX import | Supported | explicit or conservative automatic 3-column mapping |
| Linear, polynomial, ALS baseline | Supported | raw data is copied and read-only |
| Positive/negative detector peaks | Supported | explicit polarity; raw/baseline stay in detector coordinates |
| Optional Savitzky-Golay smoothing | Supported | parameters exported |
| Peak detection and manual edits | Supported | positive-area peaks after explicit polarity; add/update/remove in GUI |
| Simultaneous global deconvolution | Supported | one summed residual; mixed Gaussian/Lorentzian/Voigt |
| Center/width constraints | Supported | positive areas; validated bounds and fixed parameters |
| Shared width constraint | Supported | named shared `sigma` or `gamma` groups only |
| Identifiability diagnostics | Supported | ordering, dof, rank, condition, active bounds, covariance status |
| Independent bounded fitting | Supported | v0.1-compatible mode; not overlapping deconvolution |
| Trapezoid/Simpson integration | Supported | actual time coordinates, including irregular sampling |
| Calibration + sample-mass quantification | Supported | Pint dimensional validation |
| Explicit reduction degree | Experimental | API only; user supplies stoichiometry |
| Draft interchange metadata | Experimental | `org.tpxlab.analysis/0.2-draft`; no integration adapter yet |
| Asymmetric peaks, automatic model selection | Planned | not implemented |
| TPSR and pulse chemisorption workflows | Planned | not implemented |

## Outputs

XLSX contains Raw, Processed, Peaks, Components, Global_fit, Settings, Metadata, and QC
sheets; a directory destination writes the same layers as CSV. Exports include original
channels, component curves, total curve, residual, exact constraints, parameter ordering,
component parameters/Tmax/area/height/FWHM, local standard errors, component and global
covariance, RSS/RMSE/R²/dof, Jacobian rank, condition number, optimizer status, active
bounds, numerical rank tolerance, integration source, units, source file, and QC issues.
PNG/SVG/PDF figures include raw/baseline, components/total, and residual.

## Scientific scope and limitations

- Global mode minimizes one residual vector between the complete processed signal and the
  sum of all components. It is not a sum of separately fitted curves.
- Nonlinear decomposition can be non-unique. A full-rank local Jacobian is necessary, not
  sufficient, for physical uniqueness. Rank-deficient fits report unavailable covariance;
  boundary solutions report boundary-limited uncertainty.
- Reported covariance is the local linearized least-squares approximation. It does not
  replace replicate experiments, profile likelihood, or domain-informed uncertainty.
- A shared `sigma` or `gamma` should be used only when components have a defensible common
  broadening mechanism. TPxLab never decides that assumption automatically.
- Global component quantification integrates each fitted component against measured time.
  Independent mode integrates the observed bounded region. The export labels this source.
- Peak fit `area` is with respect to temperature; calibrated detector integration is with
  respect to time. Both are labeled separately.
- Baseline and model choices remain analytical assumptions requiring residual review.
  TPxLab orients explicitly declared positive/negative detector responses into positive-area
  models and does not infer polarity, gas identity, chemistry, oxidation state,
  stoichiometry, or expected consumption.
- Non-monotonic temperature programs are flagged; repeated temperature ranges require
  user review.

Definitions, equations, parameter ordering, and validation details are in
[Scientific methods](https://github.com/hdkim99/TPxLab/blob/main/docs/scientific-methods.md).
The reviewed, opt-in actual-research-data source is documented in
[Public data sources](https://github.com/hdkim99/TPxLab/blob/main/docs/public-data-sources.md).
The provisional, explicitly non-stable export contract is in
[Interchange metadata](https://github.com/hdkim99/TPxLab/blob/main/docs/interchange.md).

## Related tools

- [Ordifile](https://github.com/hdkim99/ordifile) — chromatographic data standardization.
- [ReactorCheck](https://github.com/hdkim99/ReactorCheck) — catalytic reactor calculation
  and QC.
- [OperandoMerge](https://github.com/hdkim99/OperandoMerge) — heterogeneous experiment
  timeline alignment.

These are independent repositories. Direct cross-project adapters are planned
interoperability, not a current TPxLab feature.

## Development

```bash
python -m pip install -e '.[dev]'
ruff check .
mypy src
pytest
python -m build
twine check dist/*
```

Runtime dependencies use permissive licenses compatible with MIT: NumPy/SciPy/pandas
(BSD), Pint (BSD), Matplotlib (PSF-based), and openpyxl (MIT). See `pyproject.toml` for
the declared dependency set and [CONTRIBUTING.md](https://github.com/hdkim99/TPxLab/blob/main/CONTRIBUTING.md)
for the scientific contribution policy.
