Data Loading

FiLark separates data access from the GUI. The viewer expects a Tape-like source; loaders and dialogs are only ways to create one.

Built-In Sources

Source	Class	Notes
HDF5	H5Tape	Reads HDF5 datasets and metadata when keys are known.
NPY	NpyTape	File-backed or ndarray-backed data; requires dims.
Raw binary	BinTape	Requires nt, nc, dtype, dims, and metadata.
In-memory array	ArrayTape	Useful for scripts and generated data.
Folder	TapeFileSet	Stitches compatible files into one logical time stream.

All of these live under filark.io.

Layout

FiLark supports two storage layouts:

• nt_nc: array shape is (time, channel)

• nc_nt: array shape is (channel, time)

Viewer coordinates, annotations, and monitor outputs are always semantic (t, c) coordinates even if the file is stored as nc_nt.

Launch With A Tape

from filark.gui.app import run_app
from filark.io.tapeio import H5Tape

source = H5Tape(
    "data/example.h5",
    datakey="Acquisition/Raw[0]/RawData",
)

run_app(source=source)

Load A Folder

from filark.gui.app import run_app
from filark.io.fileset import TapeFileSet

source = TapeFileSet("data/DS", suffixes=(".h5", ".hdf5"))
run_app(source=source)

For NPY folders and binary folders, pass the metadata FiLark cannot infer from the file itself:

import numpy as np
from filark.io.fileset import BinFolderOpts, TapeFileSet

source = TapeFileSet(
    "data/bin_folder",
    suffixes=(".dat", ".bin"),
    bin_opts=BinFolderOpts(
        nt=93000,
        nc=6455,
        dtype=np.float32,
        dims="nt_nc",
        fs=1550,
        dx=5,
        dx_unit="m",
    ),
)

Custom Loaders

Use custom loaders when your filenames or proprietary metadata encode enough information to build a Tape without asking the user.

from pathlib import Path
import numpy as np

from filark.gui.app import run_app
from filark.gui.config import GuiConfig
from filark.io.tapeio import BinTape

class MyBinLoader:
    suffixes = (".dat", ".bin")

    def load(self, path):
        path = Path(path)
        if path.is_dir():
            raise IsADirectoryError
        nt, nc = 93000, 6455
        return BinTape(path, nt, nc, np.float32, "nt_nc", fs=1550, dx=5)

cfg = GuiConfig(loaders=[MyBinLoader()])
run_app(cfg=cfg)

Loader order is:

1. GuiConfig.loaders

2. GuiConfig.builtins

3. GUI fallback dialogs

If a loader fails on a folder, FiLark can apply it to individual files and then stitch compatible children with TapeFileSet.

Metadata Checklist

For robust browsing, annotation export, and ROI extraction, provide:

• layout: dims

• sample rate: fs

• channel spacing: dx

• spacing unit: dx_unit

• optional gauge length: gauge_length

• optional absolute start time: start_time

These fields are also written into annotation exports when available.