Metadata-Version: 2.4
Name: csiio-py
Version: 0.1.0
Summary: Reader, converter, and CSV tooling for Campbell Scientific data files
Author-email: Robert Spirig <spirrobe@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/spirrobe/csiio
Project-URL: Repository, https://github.com/spirrobe/csiio.git
Project-URL: Issues, https://github.com/spirrobe/csiio/issues
Project-URL: Documentation, https://github.com/spirrobe/csiio#documentation
Keywords: campbell scientific,TOA5,TOB1,TOB3,CSIXML,timeseries
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
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 :: Only
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: sphinx>=7.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.3; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Dynamic: license-file

# csiio

Python reader and converter for Campbell Scientific Inc data files.

This package focuses on practical ingestion and conversion workflows for CSI formats (including TOA5, TOACI1, TOB1, TOB3, and CSIXML), with DataFrame-native handling for downstream analysis pipelines.

Citation: If you use csiio in published work and want to cite it, see the citation guidance in [How To Cite](README.md#how-to-cite).

## Install

```bash
pip install -e .
```

## Core Functionality

- Read CSI files into pandas DataFrames.
- Auto-detect file type during reads.
- Convert between supported CSI formats.
- Export single CSV outputs or time-window-split CSVs.
- Use either CLI workflows or Python API workflows.

## Documentation

- Use Cases and Functionality: [docs/use-cases-and-functionality.md](docs/use-cases-and-functionality.md)
- Citation Guidance: [How To Cite](README.md#how-to-cite)

## CLI Usage

```bash
csiio --help

# Read and print DataFrame summary
csiio read /path/to/file.dat

# Read metadata only
csiio read /path/to/file.dat --metaonly

# Stream CSV to stdout (good for shell pipelines)
csiio read /path/to/file.dat --as-csv

# Convert to another CSI format
csiio convert /path/to/in.dat --output-format TOB3 --output /tmp/TOB3_out.dat

# Export CSV and split by time window
csiio to-csv /path/to/in.dat --output /tmp/out.csv --split-window 1H
```

## Python API Usage

```python
from csiio import CSIDataFile, read_csi_files, convert_csi_file

# High-level object workflow
reader = CSIDataFile(["a.dat", "b.dat"])
df = reader.read()
csv_files = reader.to_csv("/tmp/out.csv", split_window="1D")

# Functional workflow
df2, meta = read_csi_files("/path/to/file.dat")
converted = convert_csi_file("/path/to/in.dat", "/tmp/TOA5_out.dat", "TOA5")
```

## How To Cite

If csiio supports published work, and you have the opportunity to cite it you may cite the software repository and version you used.

Suggested BibTeX entry:

```bibtex
@software{csiio,
	title = {csiio: Reader and Converter for Campbell Scientific Data Files},
	author = {Spirig, Robert},
	year = {2026},
	url = {https://github.com/spirrobe/csiio},
	version = {0.1.0}
}
```

If relevant/available for your workflow, include a commit hash or release tag for exact reproducibility.

## Conversion Audit Reports

Generate dual-status conversion audits (strict plus tolerance) with reason codes:

```bash
python tests/generate_conversion_audit.py
```

Outputs are written to:

- `tests/reports/conversion_audit_dual.csv`
- `tests/reports/conversion_audit_dual_summary.csv`
