Fetching Data

Use arrakis.api.fetch to retrieve historical timeseries data for a GPS time range. This loads all requested data into memory as a single arrakis.block.SeriesBlock.

Basic Usage

import arrakis

block = arrakis.fetch(
    ["H1:CAL-DELTAL_EXTERNAL_DQ", "H1:LSC-POP_A_LF_OUT_DQ"],
    start=1187000000,
    end=1187001000,
)

The start and end parameters are GPS times in seconds. The returned SeriesBlock contains data for all requested channels spanning the full time range.

Working with the Result

A SeriesBlock behaves like a dictionary keyed by channel name:

# access a single channel
series = block["H1:CAL-DELTAL_EXTERNAL_DQ"]
print(series.data)         # numpy.ndarray
print(series.sample_rate)  # Hz
print(series.time)         # GPS start time in seconds
print(series.duration)     # seconds

Iterate over all channels:

for channel, series in block.items():
    print(f"{channel}: {len(series)} samples at {series.sample_rate} Hz")

See Working with Series Blocks for more on inspecting and manipulating the data.

Using a Client

The top-level arrakis.fetch() creates a new arrakis.client.Client for each call. For multiple requests, reuse a client:

client = arrakis.Client()

block_a = client.fetch(channels, start=1187000000, end=1187000500)
block_b = client.fetch(channels, start=1187000500, end=1187001000)

Fetching Replay Data

Fetch data from a replay window by providing replay parameters.

Use replay_id to fetch from a named replay. This also gives access to derived channels published under that replay context (see Finding Channels):

# fetch using a registered replay ID
block = arrakis.fetch(channels, start=0, end=100, replay_id="O4a")

For opportunistic replays without a named ID, use explicit window bounds:

# fetch using explicit replay window bounds (GPS seconds)
block = arrakis.fetch(
    channels,
    start=0,
    end=100,
    replay_start=1369224018,
    replay_end=1385193618,
)

The server translates the requested start/end range through the replay window and retimestamps the archival data before returning it.

Fetch vs Stream

fetch() loads the entire time range into memory. Under the hood, it streams the data and concatenates the blocks:

# these are equivalent
block = client.fetch(channels, start, end)

# manual equivalent
from arrakis.block import concatenate_blocks
block = concatenate_blocks(*client.stream(channels, start, end))

For large time ranges where loading everything at once is impractical, use streaming to process data incrementally.