TraDatabase

class vallenae.io.TraDatabase(filename, mode='ro', *, compression=False)

IO wrapper for tradb database file.

__init__(filename, mode='ro', *, compression=False)

Open tradb database file.

Parameters:

• filename (str) – Path to tradb database file

• mode (str) – Define database access: “ro” (read-only), “rw” (read-write), “rwc” (read-write and create empty database if it does not exist)

• compression (bool) – Enable/disable FLAC compression data BLOBs for writing

Methods

__init__(filename[, mode, compression])	Open tradb database file.
channel()	Get list of channels.
close()	Close database connection.
columns()	Columns of data table.
connection()	Get SQLite connection object.
create(filename)	Create empty tradb.
fieldinfo()	Read fieldinfo table.
globalinfo()	Read globalinfo table.
iread(*[, channel, time_start, time_stop, ...])	Stream transient data with returned Iterable.
listen([existing, wait, query_filter, raw])	Listen to database changes and return new records.
read(**kwargs)	Read transient data to Pandas DataFrame.
read_continuous_wave(channel[, time_start, ...])	Read transient signal of specified channel to a single, continuous array.
read_wave(trai[, time_axis, raw])	Read transient signal for a given TRAI (transient recorder index).
rows()	Number of rows in data table.
tables()	Get table names.
write(tra)	Write transient data to pridb.
write_fieldinfo(field, info)	Write to fieldinfo table.

Attributes

connected	Check if connected to SQLite database.
filename	Filename of database.

static create(filename)

Create empty tradb.

Parameters:

filename (str) – Path to new tradb database file

channel()

Get list of channels.

Return type:

set[int]

read(**kwargs)

Read transient data to Pandas DataFrame.

Parameters:

**kwargs – Arguments passed to iread

Return type:

DataFrame

Returns:

Pandas DataFrame with transient data

iread(*, channel=None, time_start=None, time_stop=None, trai=None, query_filter=None, raw=False)

Stream transient data with returned Iterable.

Parameters:

• channel (Union[int, Sequence[int], None]) – None if all channels should be read. Otherwise specify the channel number or a list of channel numbers

• time_start (float | None) – Start reading at relative time (in seconds). Start at beginning if None

• time_stop (float | None) – Stop reading at relative time (in seconds). Read until end if None

• trai (Union[int, Sequence[int], None]) – Read data by TRAI (transient recorder index)

• query_filter (str | None) – Optional query filter provided as SQL clause, e.g. “Pretrigger == 500 AND Samples >= 1024”

• raw (bool) – Return data as ADC values (int16). Default: False

Return type:

SizedIterable[TraRecord]

Returns:

Sized iterable to sequential read transient data

read_wave(trai, time_axis=True, *, raw=False)

Read transient signal for a given TRAI (transient recorder index).

This method is useful in combination with PriDatabase.read_hits, that will store the TRAI in a DataFrame.

Parameters:

• trai (int) – Transient recorder index (unique key between pridb and tradb)

• time_axis (bool) – Create the correspondig time axis. Default: True

• raw (bool) – Return data as ADC values (int16). Default: False

Return type:

tuple[ndarray, ndarray] | tuple[ndarray, int]

Returns:

If time_axis is True

• Array with transient signal

• Time axis

If time_axis is False

• Array with transient signal

• Samplerate

read_continuous_wave(channel, time_start=None, time_stop=None, *, time_axis=True, show_progress=True, raw=False)

Read transient signal of specified channel to a single, continuous array.

The signal is exactly cropped to the given time range. Time gaps are filled with 0’s.

Parameters:

• channel (int) – Channel number to read

• time_start (float | None) – Start reading at relative time (in seconds). Start at beginning if None

• time_stop (float | None) – Stop reading at relative time (in seconds). Read until end if None

• time_axis (bool) – Create the correspondig time axis. Default: True

• show_progress (bool) – Show progress bar. Default: True

• raw (bool) – Return data as ADC values (int16). Default: False

Return type:

tuple[ndarray, ndarray] | tuple[ndarray, int]

Returns:

If time_axis is True

• Array with transient signal

• Time axis

If time_axis is False

• Array with transient signal

• Samplerate

listen(existing=False, wait=False, query_filter=None, raw=False)

Listen to database changes and return new records.

Parameters:

• existing (bool) – Return already existing records

• wait (bool) – Wait for new records even if no acquisition (writer) is active. Otherwise the function returns after all records are read.

• query_filter (str | None) – Optional query filter provided as SQL clause, e.g. “TRAI >= 100 AND Samples >= 1024”

• raw (bool) – Return data as ADC values (int16). Default: False

Yields:

New transient data records

Return type:

Iterable[TraRecord]

write(tra)

Write transient data to pridb.

Parameters:

tra (TraRecord) – Transient data set

Return type:

int

Returns:

Index (SetID) of inserted row

close()

Close database connection.

columns()

Columns of data table.

Return type:

tuple[str, ...]

property connected: bool

Check if connected to SQLite database.

connection()

Get SQLite connection object.

Raises:

RuntimeError – If connection is closed

Return type:

Connection

fieldinfo()

Read fieldinfo table.

The fieldinfo table stores informations about columns of the data table (like units).

Return type:

dict[str, dict[str, Any]]

Returns:

Dict of column names and informations (again a dict)

property filename: str

Filename of database.

globalinfo()

Read globalinfo table.

Return type:

dict[str, Any]

rows()

Number of rows in data table.

Return type:

int

tables()

Get table names.

Return type:

set[str]

write_fieldinfo(field, info)

Write to fieldinfo table.

Parameters:

• field (str) – Column name of data table

• info (dict[str, Any]) – Dict of properties and values, e.g. {“Unit”: “[Hz]”}

Raises:

ValueError – If field is not a column of data table