Metadata-Version: 2.4
Name: qplot-cli
Version: 0.5.0
Summary: Quick inspection and plotting of scientific tabular data
License-Expression: MIT
Project-URL: Homepage, https://github.com/Al3xPhys/qplot-cli
Project-URL: Repository, https://github.com/Al3xPhys/qplot-cli
Project-URL: Issues, https://github.com/Al3xPhys/qplot-cli/issues
Keywords: cli,plotting,scientific-data,csv,matplotlib
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
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.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: matplotlib>=3.7
Requires-Dist: openpyxl>=3.1
Requires-Dist: textual>=1.0
Requires-Dist: textual-image[textual]<0.13,>=0.8.5
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Dynamic: license-file

# qplot

[![PyPI version](https://img.shields.io/pypi/v/qplot-cli.svg)](https://pypi.org/project/qplot-cli/)
[![Python versions](https://img.shields.io/pypi/pyversions/qplot-cli.svg)](https://pypi.org/project/qplot-cli/)
[![CI](https://github.com/Al3xPhys/qplot-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Al3xPhys/qplot-cli/actions/workflows/ci.yml)

`qplot` is a command-line tool for quickly inspecting and plotting scientific
data from CSV, TSV, TXT, DAT, NumPy, and Excel files. It detects tabular
structure, chooses useful datasets and x/y columns, explains its inference,
and can show a plot interactively or save it without a GUI.

> **Alpha status:** qplot is usable, but its interface and automatic inference
> may change before the first stable release.

## Installation

Python 3.10 or newer is required. The distribution is named `qplot-cli`, while
the command it installs is `qplot`.

The recommended installation for command-line use is
[pipx](https://pipx.pypa.io/):

```bash
pipx install qplot-cli
```

Alternatively, install it into the current Python environment:

```bash
python -m pip install qplot-cli
```

Confirm the command is available:

```bash
qplot --version
qplot --help
```

Launch the terminal file browser:

```bash
qplot tui
```

The TUI shows folders and qplot-compatible files from the current directory.
Highlighting a file displays its format, selected dataset, dimensions, columns,
loader warnings, and automatic plot suggestion. Multi-sheet workbooks and
multi-array archives expose a dataset chooser that marks qplot's automatic
choice; select another dataset to refresh its columns and inference without
reloading the file. A plot-controls pane starts from automatic x/y/z inference,
allows visual column overrides, and shows a live embedded Matplotlib preview.
The preview keeps the last valid plot visible while a selection is incomplete.
Preview rendering runs in the background at an adaptive resolution, so changing
columns remains responsive while producing a sharper terminal image.
The Plot button opens the resulting 2D or 3D figure in Matplotlib for its full
interactive controls. Preview quality depends on terminal graphics support;
qplot falls back to a Unicode rendering when necessary.

If Windows cannot find `qplot` after installation, use `python -m qplot` or
ensure the Python Scripts directory reported by `python -m site --user-base` is
on `PATH`.

## Quick start

Inspect a file without plotting:

```bash
qplot data.csv --columns
qplot data.csv --info
```

Infer columns and open an interactive plot:

```bash
qplot data.csv
qplot experiment.npy
qplot results.npz
qplot workbook.xlsx
qplot coordinates.csv
```

Save a plot on a desktop, server, or CI runner without opening a window:

```bash
qplot data.csv --no-gui --save plot.png
```

Select columns by exact case-insensitive name or zero-based index:

```bash
qplot measurements.tsv -x time -y voltage -y temperature
qplot measurements.tsv -x 0 -y 1 -y 2
qplot coordinates.csv -x horizontal -y vertical -z depth
```

Apply plotting and loading overrides:

```bash
qplot data.csv --scatter --logx --logy --title "Field sweep"
qplot data.txt --delimiter ";" --header 2 --rows 100:500
qplot headerless.dat --no-header --all
qplot legacy-export.csv --encoding cp1252 --info
qplot data.csv --missing-y error
qplot instrument.csv --invalid-y error
```

`--rows START:STOP` uses zero-based, stop-exclusive slicing. `--all` plots all
numeric y columns remaining after x selection. Run `qplot --help` for every
option.

Text input defaults to `utf-8-sig`, which supports ordinary UTF-8 and UTF-8
files with a byte-order mark. Use `--encoding` for files produced with another
encoding, such as `cp1252` or `latin-1`.

Empty cells and the case-insensitive markers `NA`, `N/A`, `NaN`, and `null`
are interpreted as missing values. By default, missing y values produce visible
gaps in line plots and omitted markers in scatter plots, and qplot prints a
warning for every affected y column. Use `--missing-y drop` to connect across
missing points or `--missing-y error` to reject them. Missing x values are
always rejected because they affect every plotted series. Unrecognised tokens
such as `ERROR` are not silently treated as missing data. A mixed column is
eligible for automatic y inference when at least half of its non-missing values
are numeric; it is never considered as an automatic x column. Invalid y values
produce gaps by default, with warnings that identify their row positions and
tokens. Line plots containing gaps show point markers so isolated valid
measurements remain visible at their true x positions. Use `--invalid-y drop`
to remove those points or `--invalid-y error` for strict validation. Mixed
columns below the 50% threshold remain excluded and are explained by `--info`;
they can still be selected explicitly with `-y`.

## Supported files and automatic behaviour

- CSV, TSV, TXT, and DAT files use automatic delimiter and header detection.
- One- and two-dimensional `.npy` arrays become tabular datasets.
- Each usable array in an `.npz` archive becomes a dataset.
- Each non-empty worksheet in an `.xlsx` workbook becomes a dataset.

For sources containing multiple datasets, qplot skips unplottable candidates,
then prefers an inferred x column, more inferred y columns, and more rows. Ties
preserve the source order. Empty or unsupported archive members and worksheets
are skipped with visible warnings when usable data remains.

Inference deterministically scores x candidates using recognised names,
monotonicity, uniqueness, and spacing. Y candidates use recognised response
names and variation. Automatic plots include at most three y traces; `--all`
removes that limit.

Exactly three numeric columns named `x`, `y`, and `z` (case-insensitively) are
treated as strong evidence for an automatic 3D scatter plot. Ambiguous
three-column data remains a normal 2D plot. A user can explicitly request a 3D
scatter for differently named columns with `-x X -y Y -z Z`; names and
zero-based indices are both accepted.

## Platform notes

Headless plotting uses Matplotlib's `Agg` backend and does not require a display
server. Interactive plotting uses a GUI backend available on the host system.
Windows Python installations commonly include Tk support; some Linux systems
need an additional package such as `python3-tk`. If interactive plotting is not
available, use `--no-gui --save OUTPUT.png`.

Windows and Ubuntu are tested in continuous integration on Python 3.10, 3.12,
and 3.14. Other Python versions from 3.10 onward are expected to work but are
not included in the current CI matrix.

## Development

Clone the repository and install it in editable mode with development tools:

```bash
python -m pip install -e ".[dev]"
python -m pytest
```

CI runs the test suite on Windows and Ubuntu and builds both a wheel and source
distribution. See [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a larger
change.

## Current limitations

- One input file is supported per invocation.
- Files are loaded eagerly into memory; text encoding defaults to `utf-8-sig`
  and can be overridden explicitly.
- Detection supports ordinary delimited tables and leading blank or comment
  lines; arbitrary instrument metadata and concatenated tables are not yet
  interpreted.
- NumPy arrays with three or more dimensions are reported and skipped. Current
  3D scatter support applies to tabular x/y/z point data, not volume arrays,
  surfaces, or coordinate grids.
- Legacy `.xls`, HDF5, and Parquet files are not yet supported.
- Interactive plotting depends on a working local Matplotlib GUI backend.
- Qt, fitting, smoothing, presets, arbitrary expressions, and plugins are not
  currently included.

## Licence

qplot is released under the [MIT License](LICENSE).
