Metadata-Version: 2.4
Name: atmolidarpy
Version: 0.2.0
Summary: Standalone atmospheric lidar data processing package
Project-URL: Homepage, https://github.com/jabravoaranda/lidarpy
Project-URL: Repository, https://github.com/jabravoaranda/lidarpy
Project-URL: Documentation, https://jabravoaranda.github.io/lidarpy/
Project-URL: Issues, https://github.com/jabravoaranda/lidarpy/issues
Author-email: Juan Diego De la Rosa <jdidelarc@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: <3.12,>=3.11.11
Requires-Dist: cloudnet-api-client>=0.12.9
Requires-Dist: dask<2025,>=2024.11.2
Requires-Dist: linc==3.0.6
Requires-Dist: loguru<1,>=0.7.0
Requires-Dist: matplotlib>=3.10.0
Requires-Dist: netcdf4<2,>=1.7.2
Requires-Dist: numba<1,>=0.60.0
Requires-Dist: numpy<2.1,>=2.0.2
Requires-Dist: pandas>=2.1.2
Requires-Dist: psutil<7,>=6.1.1
Requires-Dist: pytz>=2024.2
Requires-Dist: pyyaml<7,>=6.0.2
Requires-Dist: requests<3,>=2.32.3
Requires-Dist: scipy<2,>=1.13.1
Requires-Dist: statsmodels<0.15,>=0.14.4
Requires-Dist: typing-extensions<5,>=4.12.0
Requires-Dist: xarray<2026,>=2025.1.2
Provides-Extra: docs
Requires-Dist: pdoc<16,>=15.0.1; extra == 'docs'
Provides-Extra: jupyter
Description-Content-Type: text/markdown

# atmolidarpy

`atmolidarpy` is the PyPI distribution for the standalone atmospheric lidar
processing package imported as `lidarpy`.

The project was migrated out of the former `gfatpy.lidar` submodule so that the
lidar processing code can be installed, tested, documented and released on its
own. It includes RAW Licel conversion, preprocessing, quicklooks, synthetic
signal generation, retrieval routines, SCC support modules and package data for
known lidar systems.

Current public documentation:

- [Documentation site](https://jabravoaranda.github.io/lidarpy/)
- [Module reference index](https://jabravoaranda.github.io/lidarpy/references.html)

## Documentation Map

- [Overview](docs/index.html): package scope and repository map.
- [Getting started](docs/getting-started.html): install, first import, first
  validation and expected results.
- [Processing workflow](docs/processing-workflow.html): operational data flow
  from RAW files to NetCDF, preprocessing, quicklooks and retrieval checks.
- [Examples](docs/examples.html): runnable snippets for synthetic signals,
  preprocessing and SCC client contracts.
- [Operational guide](docs/operations.html): local, CI, release, rollback,
  troubleshooting and runtime boundaries.
- [References](docs/references.html): scientific references and public module
  index.
- [Contributing](docs/contributing.html): development workflow and documentation
  maintenance.

## Install

For users:

```powershell
python -m pip install atmolidarpy
python -c "import lidarpy; print(lidarpy.__version__)"
```

Expected result: Python imports `lidarpy` without needing the old `gfatpy`
package. The distribution name and import name are intentionally different:
install `atmolidarpy`, import `lidarpy`.

For local development:

```powershell
uv sync --group dev
$env:PYTHONPATH = "src"
$env:MPLBACKEND = "Agg"
.\.venv\Scripts\python -m pytest tests -q -m "not slow"
```

The full suite includes RAW fixture conversion and can create large temporary
NetCDF files. On Windows, run large groups in chunks and keep pytest temporary
directories inside the repository.

## Repository Shape

- `src/lidarpy/nc_convert`: RAW/Licel discovery and NetCDF conversion.
- `src/lidarpy/preprocessing`: correction pipeline, overlap and gluing support.
- `src/lidarpy/plot`: quicklook plotting.
- `src/lidarpy/retrieval`: Klett, Raman, overlap, calibration, ABLH detection
  and synthetic validation helpers.
- `src/lidarpy/atmo`: molecular atmosphere and Rayleigh utilities.
- `src/lidarpy/depolarization`: calibration and retrieval helpers.
- `src/lidarpy/scc`: SCC conversion, client, resources and plotting helpers.
- `tests`: focused unit, integration, packaging, SCC, docs and synthetic tests.
- `docs`: static GitHub Pages source.
- `scripts`: documentation build and figure generation.

## Release

Current package version: `0.2.0`.

The package is published as `atmolidarpy` on PyPI through GitHub Actions Trusted
Publishing. Releases are tag-driven:

```powershell
git tag v0.2.0
git push origin v0.2.0
```

The `Publish Package` workflow builds sdist and wheel artifacts, checks them
with Twine and publishes to PyPI from the GitHub environment named `pypi`.

Versioning policy while the project remains alpha:

- Bug fixes that keep the public API compatible use patch releases within the
  current minor series, for example `0.2.1`.
- Public API additions or behavior changes use `0.2.0`, `0.3.0`, etc.
- `1.0.0` is reserved for the first stable API intended for production
  dependants such as `gfat-worker`.

## What is New in 0.2.0

- Added `lidarpy.retrieval.ablh` with ABLH detection on common
  `time, range` products from lidarpy datasets and Cloudnet ceilometer
  backscatter products.
- Added WCT and temporal-variance ABLH methods with synthetic 2D tests against
  known simulated layer height.
- Added a Cloudnet CHM15k Granada workbench that writes ABLH NetCDF products
  and a quicklook overlaying detected layer heights.

Rollback is normally operational rather than destructive: publish a corrected
new version, or pin downstream environments to the last known good version. Do
not delete release tags or PyPI files unless there is a severe security or
legal reason.
