photonscore.vault

Read and write Photonscore .photons / D7 files.

A .photons file is a structured store of photon-level data (timestamps, coordinates, side streams) plus metadata. The Vault class is a thin Pythonic wrapper around the native backend that mounts a file as a tree of named datasets accessible by dotted path or slicing.

Read a file:

from photonscore import Vault
v = Vault("measurement.photons")
print(v)                     # tree summary
x = v.data.photons.x[:]      # all photon x-coordinates
t = v.data.photons.ms[0:10]  # first ten millisecond markers

Create a new file:

v = Vault("out.photons", create_if_missing=True, read_only=False)
v.create_dataset("photons/x", dtype="i2", shape=(0,))
v.data.photons.x.append([1, 2, 3])
v.close()

DataGroup

class DataGroup()

A named group of datasets and sub-groups.

Groups are built automatically by Vault so that paths such as "photons/x" become attribute access like v.data.photons.x.

Dataset

class Dataset(vault, name)

A single dataset inside a Vault.

Supports NumPy-style slicing — ds[0:100], ds[::2], ds[(0, 1, 2)] — and an append operation for files opened in read/write mode.

name

property

name

dtype

property

dtype

shape

property

shape

append

def append(data)

Vault

class Vault(
    path: str,
    fail_if_exists: bool = False,
    create_if_missing: bool = False,
    read_only: bool = True,
    backend: str = '',
    backend_options: str = '',
)

Open or create a Photonscore data file.

A Vault is the entry point for .photons (D7) files: it exposes the file's datasets as a tree under data, allows reading attributes, and supports creating new datasets when opened in read/write mode.

Attributes

data (Any): Tree of DataGroup / Dataset mirroring the on-disk layout. v.data.photons.x[:] returns the full photons/x dataset as a NumPy array.

attributes

property

attributes

set_attribute

def set_attribute(name: str, value: str)

create_dataset

def create_dataset(name: str, dtype: dtype, shape = ())

close

def close()

Close the underlying file. Subsequent reads raise.

read

def read(dataset: str, start: int, count: int)

Read count elements from dataset starting at start.

Prefer slicing through data (v.data.photons.x[0:100]); this method is the low-level primitive used by Dataset.