File-Loader Plugins

What File Loaders Do

File-loader plugins convert external data files into a two-dimensional table that PhysPlot can display. A loader receives a file path and returns a rectangular data array.

Layman Example

If your instrument saves data in a special format, a loader teaches PhysPlot how to skip the header text and keep only the useful numeric columns. For example, the OES HRF loader skips metadata and returns wavelength and intensity columns.

Required File Location

Put new file-loader files in:

fileloader/

Use a clear filename:

fileloader/my_instrument_loader.py

Required Structure

Every loader should define:

title

Text shown in the Data Loader dropdown.

load_data(file_path)

Function that receives a file path and returns a two-dimensional table-like object.

Optional:

DEFAULT_COLUMN_ROLES

A list of default role labels such as ["X-axis", "Y-axis"]. PhysPlot applies these roles automatically after import.

Minimal CSV-Like Template

"""Loader for a custom instrument text file."""

from pathlib import Path
import numpy as np

title = "My Instrument Loader"
DEFAULT_COLUMN_ROLES = ["X-axis", "Y-axis"]


def load_data(file_path):
    """load_data(file_path) -> numpy.ndarray

    Load two numeric columns from a custom instrument file.

    Parameters:
        file_path (str | pathlib.Path): Path selected in the import dialog.

    Returns:
        numpy.ndarray: Two-column array ready for the PhysPlot table.
    """
    rows = []
    for line in Path(file_path).read_text().splitlines():
        if line.startswith("#"):
            continue
        parts = line.split(",")
        if len(parts) < 2:
            continue
        rows.append((float(parts[0]), float(parts[1])))
    return np.asarray(rows, dtype=float)

OES HRF Pattern

The OES HRF loader demonstrates a common pattern:

  1. Read the whole file as text.

  2. Ignore metadata until a marker line.

  3. Parse numeric rows.

  4. Drop unnecessary index columns.

  5. Return only the columns PhysPlot should show.

Practical Rules

  • Always return a rectangular two-dimensional array.

  • Convert values to floats when possible.

  • Raise a helpful ValueError if the file contains no usable rows.

  • Use DEFAULT_COLUMN_ROLES when a loader knows which columns are X and Y.

  • Keep loader code independent from the GUI. Do not modify the table directly.

Existing Examples

See:

  • fileloader/default_loader.py

  • fileloader/oes_hrf_loader.py