Metadata-Version: 2.4
Name: qplot-cli
Version: 0.1.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
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

`qplot` is a command-line tool for quickly inspecting and plotting ordinary
scientific CSV, TSV, TXT, and DAT files. It detects delimiters and headers,
explains its x/y inference, supports explicit column overrides, 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`.

Once a release is available on PyPI, the recommended installation for command-
line use will be [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
```

Until the first PyPI release, install directly from GitHub:

```bash
python -m pip install "git+https://github.com/Al3xPhys/qplot-cli.git"
```

Confirm the command is available:

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

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
```

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
```

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
```

`--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.

## Automatic behaviour

The loader samples the file to detect comma, tab, semicolon, or space
separators and whether a header is present. 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.

## 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 and decoded as UTF-8.
- Detection supports ordinary delimited tables and leading blank or comment
  lines; arbitrary instrument metadata and concatenated tables are not yet
  interpreted.
- Interactive plotting depends on a working local Matplotlib GUI backend.
- HDF5, Excel, NumPy, Qt, fitting, smoothing, presets, arbitrary expressions,
  and plugins are intentionally outside this alpha.

## Licence

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