File Loader API

User file loaders live in the config/data_importers folder. Each loader exposes title or DISPLAY_NAME and load_data(file_path). Built-in backend loaders live under physplot.loaders.

Package Contract

Data loader modules for PhysPlot.

Each loader module should expose a load_data(file_path) function that returns a 2D array-like object suitable for loading into the table.

Input data structure:

Loader modules receive a file path chosen from the import dialog.

Return type:

Loader modules return a rectangular two-dimensional table-like object, usually a NumPy array.

Optional main/runtime behavior:

Package marker for dynamically discovered loader plugins; not executable by itself.

Built-In Backend Loaders

File and dataframe loaders for PhysPlot.

class AutoLoader

file_format = 'auto'

load(source: Any, dataset_name: str | None = None) → Dataset

loader_id = 'auto'

name = 'Auto Loader'

supported_extensions: tuple[str, ...] = ()

class CSVLoader

file_format = 'csv'

loader_id = 'csv'

name = 'CSV Loader'

read_dataframe(path: Path) → pandas.DataFrame

supported_extensions: tuple[str, ...] = ('.csv',)

class DataFrameLoader

file_format = 'dataframe'

load(source: pandas.DataFrame, dataset_name: str | None = None) → Dataset

loader_id = 'dataframe'

name = 'DataFrame Loader'

supported_extensions: tuple[str, ...] = ()

class ExcelLoader

file_format = 'excel'

loader_id = 'excel'

name = 'Excel Loader'

read_dataframe(path: Path) → pandas.DataFrame

supported_extensions: tuple[str, ...] = ('.xls', '.xlsx')

class NanoindentationLoader

dataset_from_dataframe(df: pandas.DataFrame, dataset_name: str, source_path: Path | None = None) → Dataset

file_format = 'nanoindentation'

loader_id = 'nanoindentation'

name = 'Nanoindentation Loader'

read_dataframe(path: Path) → pandas.DataFrame

supported_extensions: tuple[str, ...] = ('.csv', '.txt', '.dat', '.xls', '.xlsx')

class TXTLoader

file_format = 'txt'

loader_id = 'txt'

name = 'TXT Loader'

read_dataframe(path: Path) → pandas.DataFrame

supported_extensions: tuple[str, ...] = ('.txt', '.dat', '.tsv', '.msa')

get_loader(loader: str | BaseLoader = 'auto') → BaseLoader

list_loaders() → list[BaseLoader]

Loader Base Classes

PhysPlot data loaders.

class AutoLoader

file_format = 'auto'

load(source: Any, dataset_name: str | None = None) → Dataset

loader_id = 'auto'

name = 'Auto Loader'

supported_extensions: tuple[str, ...] = ()

class BaseLoader

dataset_from_dataframe(df: pandas.DataFrame, dataset_name: str, source_path: Path | None = None) → Dataset

file_format = 'manual'

load(source, dataset_name: str | None = None) → Dataset

loader_id = 'base'

name = 'Base Loader'

read_dataframe(path: Path) → pandas.DataFrame

supported_extensions: tuple[str, ...] = ()

class CSVLoader

file_format = 'csv'

loader_id = 'csv'

name = 'CSV Loader'

read_dataframe(path: Path) → pandas.DataFrame

supported_extensions: tuple[str, ...] = ('.csv',)

class DataFrameLoader

file_format = 'dataframe'

load(source: pandas.DataFrame, dataset_name: str | None = None) → Dataset

loader_id = 'dataframe'

name = 'DataFrame Loader'

supported_extensions: tuple[str, ...] = ()

class ExcelLoader

file_format = 'excel'

loader_id = 'excel'

name = 'Excel Loader'

read_dataframe(path: Path) → pandas.DataFrame

supported_extensions: tuple[str, ...] = ('.xls', '.xlsx')

class NanoindentationLoader

dataset_from_dataframe(df: pandas.DataFrame, dataset_name: str, source_path: Path | None = None) → Dataset

file_format = 'nanoindentation'

loader_id = 'nanoindentation'

name = 'Nanoindentation Loader'

read_dataframe(path: Path) → pandas.DataFrame

supported_extensions: tuple[str, ...] = ('.csv', '.txt', '.dat', '.xls', '.xlsx')

class TXTLoader

file_format = 'txt'

loader_id = 'txt'

name = 'TXT Loader'

read_dataframe(path: Path) → pandas.DataFrame

supported_extensions: tuple[str, ...] = ('.txt', '.dat', '.tsv', '.msa')

class XRDMLLoader

dataset_from_dataframe(df: pandas.DataFrame, dataset_name: str, source_path: Path | None = None) → Dataset

file_format = 'xrdml'

loader_id = 'xrdml'

name = 'XRDML Loader (Panalytical XRD)'

read_dataframe(path: Path) → pandas.DataFrame

supported_extensions: tuple[str, ...] = ('.xrdml',)

build_column_metadata(df: pandas.DataFrame) → dict[str, dict]

get_loader(loader: str | BaseLoader = 'auto') → BaseLoader

list_loaders() → list[BaseLoader]

loader_classes() → dict[str, type[BaseLoader]]

loader_for_path(path: Path) → BaseLoader

XRDML Loader

Loader for Malvern Panalytical .xrdml XRD measurement files.

Intensity is the raw counts summed over the file’s scans, which is what the vendor’s CSV export writes for repeated (“reps”) scans; with more than one scan, Intensity 1 … Intensity N hold each scan. Attenuation factors are recorded in metadata but not applied, also matching that export. The scanned axis (normally 2Theta) becomes the first column.

read_xrdml(path: Path) → tuple[pandas.DataFrame, dict]

Return the scan table and measurement metadata of an .xrdml file.

Instrument Text Tables

Tolerant reader for delimited text tables exported by instruments.

Many instrument exports put metadata above the numeric table (Panalytical XRD [Measurement conditions] blocks, EDAX EDS headers), use tabs in a .csv file, or store a spectrum as rows (PHI XPS). read_text_table keeps the plain pandas result when it already gives a usable table and otherwise locates the numeric block itself.

find_numeric_table(text: str) → pd.DataFrame | None

Return the longest block of numeric rows in text as a DataFrame, or None.

read_text_table(path: Path, read_plain: Callable[[Path], pandas.DataFrame]) → pandas.DataFrame

Read path with read_plain, falling back to locating the numeric block.

Skipped metadata lines are kept in DataFrame.attrs["header_lines"].

Loader Plugins

Personal loader plugins from config/data_importers for the backend.

A loader plugin defines load_data(file_path) returning a DataFrame or 2D table, and optionally COLUMN_NAMES, DEFAULT_COLUMN_ROLES and FILE_EXTENSIONS (e.g. [".ras"]). Auto Loader uses the first plugin that declares a file’s extension when no built-in loader handles it, so such files load the same way in the GUI, in replayed sequences and in bulk runs.

class PluginLoader(plugin_path)

Adapter that loads a file through a personal loader plugin.

load_plugin_module(path)

Import a loader plugin module from path.

plugin_column_names(module, column_count: int) → list[str]

Use loader-declared COLUMN_NAMES when available, then pad defaults.

plugin_dataframe(module, loaded) → pandas.DataFrame

Turn a plugin’s load_data result into a DataFrame with its column names.

plugin_extensions() → set[str]

Return every extension declared by an installed loader plugin.

plugin_loader_for_suffix(suffix: str) → PluginLoader | None

Return a loader for the first plugin whose FILE_EXTENSIONS include suffix.