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:

pipx install qplot-cli

Alternatively, install it into the current Python environment:

python -m pip install qplot-cli

Until the first PyPI release, install directly from GitHub:

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

Confirm the command is available:

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:

qplot data.csv --columns
qplot data.csv --info

Infer columns and open an interactive plot:

qplot data.csv

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

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

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

qplot measurements.tsv -x time -y voltage -y temperature
qplot measurements.tsv -x 0 -y 1 -y 2

Apply plotting and loading overrides:

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:

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