Metadata-Version: 2.4
Name: planttrend
Version: 0.1.0
Summary: Industrial plotting helpers for time-series and process analytics.
Author: planttrend contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/xiezeyu301/planttrend
Project-URL: Repository, https://github.com/xiezeyu301/planttrend
Project-URL: Issues, https://github.com/xiezeyu301/planttrend/issues
Keywords: plotting,matplotlib,pandas,analytics,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# planttrend

planttrend is a lightweight plotting helper library built on top of pandas and matplotlib. It is aimed at industrial process data analysis, time-series trend comparison, correlation inspection, and label/style reuse.

## Features

- Multi-axis trend plotting for process variables
- Correlation heatmaps for numeric columns
- Distribution comparison charts
- Reusable tag metadata for equipment tags, aliases, units, remarks, and industrial variable types
- Built-in style presets for dashboards, reports, and industrial scenes

## Install

```bash
pip install planttrend
```

## Quick start

```python
import pandas as pd
from planttrend import plot_columns, plot_correlation_heatmap, plot_distribution

frame = pd.read_csv("example.csv")

plot_columns(
    frame,
    columns=[["TE301101H.AI1.PV"], ["LT301101H.AI1.PV", "FT301101H.AI1.PV"]],
    x="时间",
    style="industrial",
)

plot_correlation_heatmap(frame)
plot_distribution(frame, columns=["FT301101H.AI1.PV", "FT301103H.AI1.PV"])
```

## Class-based usage

If you want to reuse a default plotting config across multiple charts, use the `PlantTrend` client:

```python
import pandas as pd
from planttrend import PlantTrend

frame = pd.read_csv("example.csv")

plotter = PlantTrend(
    config={
        "style": "industrial",
        "show": False,
        "show_type_badges": True,
        "map_dict": {
            "FT301101H.AI1.PV": {
                "des": "进料流量",
                "unit": "t/h",
                "remark": "主进料流量",
                "type": "观测量",
            },
            "LT301101H.AI1.PV": {
                "des": "液位",
                "unit": "m",
                "remark": "罐液位",
                "type": "控制量",
            },
        },
    }
)

plotter.plot_columns(
    frame,
    columns=[
        ["FT301101H.AI1.PV"],
        [["LT301101H.AI1.PV"], ["FT301103H.AI1.PV"]],
    ],
    x="时间",
)

plotter.plot_distribution(
    frame,
    columns=["FT301101H.AI1.PV", "FT301103H.AI1.PV"],
)

plotter.plot_correlation_heatmap(frame)
```

`PlantTrend` also exposes `get_config()`, `update_config()`, `reset_config()`, `clone()`, and `describe_config()` for managing shared plotting settings.

You can also create a plotter from a tag metadata CSV with columns `tag`, `des`, `unit`, `remark`, and optional `type`:

```csv
tag,des,unit,remark,type
FT301101H.AI1.PV,进料流量,t/h,主进料流量,观测量
LT301101H.AI1.PV,液位,m,罐液位,控制量
```

```python
plotter = PlantTrend.from_tag_meta_csv(
    "tag-meta.csv",
    encoding="utf-8",
    config={"style": "industrial", "show": False},
)
```

For `plot_columns`, metadata labels are rendered as `des(unit)`, for example `进料流量(t/h)`.
If `type` is provided, each subplot draws rounded type badges just outside the upper-right plot border, with the badge bottom attached to the border line. Supported industrial values are commonly `控制量` and `观测量`; if one subplot contains multiple curves, their type badges are laid out horizontally near the right border next to each other and without exceeding the plot frame horizontally.
Set `config={"show_type_badges": False}` to hide these type badges globally for `plot_columns`.

If your metadata CSV uses Chinese column names, pass column mappings explicitly:

```python
plotter = PlantTrend.from_tag_meta_csv(
    "tag_meta.csv",
    encoding="gbk",
    config={"style": "industrial"},
    tag_col="位号",
    des_col="注释",
    unit_col="单位",
    remark_col="备注",
    type_col="类型",
)
```

## Style preview

![planttrend style preview](docs/style-preview.png)

Regenerate the preview image with:

```bash
python tests/render_style_preview.py
```

## Development

```bash
python -m pip install -e .[dev]
python -m unittest discover -s tests -v
python -m ruff check src tests
python -m mypy
python -m build
```

The generated artifacts will be placed in the `dist` directory. Use `python -m twine check dist/*` before publishing packages manually.

## GitHub Actions release

This repository includes an automated publish workflow at .github/workflows/publish.yml.

Before using it:

1. Create a PyPI API token.
2. In GitHub, open Settings > Secrets and variables > Actions.
3. Add a repository secret named PYPI_API_TOKEN.
4. Keep the version in pyproject.toml aligned with the Git tag you plan to push.

### Automatic publish by tag

Update the package version first, then push a tag in the form v0.1.0:

```bash
git tag v0.1.0
git push origin v0.1.0
```

The workflow will run tests, build the package, validate the artifacts, and upload them to PyPI.

### Manual run from GitHub

You can also run the workflow from the Actions tab with workflow_dispatch.
If you leave publish_to_pypi unchecked, it only runs test and build validation.
If you check publish_to_pypi, it will also upload dist artifacts to PyPI.

## License

planttrend is released under the MIT License. See the `LICENSE` file for details.
