Skip to content

Getting Started

This tutorial walks through the core features of arrakis step by step. By the end you will know how to fetch historical data, inspect the results, discover channels, and stream live data.

Fetch Historical Data

The simplest way to get data is arrakis.api.fetch. Provide a list of channel names and a GPS time range:

import arrakis

start = 1187000000
end = 1187001000
channels = [
    "H1:CAL-DELTAL_EXTERNAL_DQ",
    "H1:LSC-POP_A_LF_OUT_DQ",
]

block = arrakis.fetch(channels, start, end)

block is a arrakis.block.SeriesBlock -- a dictionary-like container holding timeseries data for every channel you requested.

Inspect the Result

A SeriesBlock behaves like a dictionary. Iterate over it to access individual channel data:

for channel, series in block.items():
    print(channel, series)

Each value is a arrakis.block.Series object. It carries the data array, the channel metadata, and timing information:

series = block["H1:CAL-DELTAL_EXTERNAL_DQ"]

print(series.data)         # numpy array of samples
print(series.sample_rate)  # samples per second
print(series.time)         # start time in GPS seconds
print(series.duration)     # duration in seconds
print(series.dt)           # time between samples
print(series.times)        # array of GPS timestamps for each sample

You can also check the block-level properties:

print(block.time)      # block start time (GPS seconds)
print(block.duration)  # block duration (seconds)
print(len(block))      # number of channels
print(list(block.keys()))  # channel names

Describe Channel Metadata

Use arrakis.api.describe to retrieve metadata for specific channels without fetching any timeseries data:

metadata = arrakis.describe([
    "H1:CAL-DELTAL_EXTERNAL_DQ",
    "H1:LSC-POP_A_LF_OUT_DQ",
])

for name, channel in metadata.items():
    print(f"{name}: {channel.sample_rate} Hz, dtype={channel.data_type}")

The result is a dictionary mapping channel names to arrakis.channel.Channel objects. Each Channel carries the channel's name, data type, sample rate, and optional fields like the associated publisher and stride.

Find Channels

Use arrakis.api.find to search for channels by pattern. The pattern uses regular expressions:

for channel in arrakis.find("H1:LSC-.*"):
    print(channel)

You can filter by data type, sample rate range, or publisher:

import numpy

# find all float64 channels between 256 and 4096 Hz
for channel in arrakis.find(
    "H1:.*",
    data_type=numpy.float64,
    min_rate=256,
    max_rate=4096,
):
    print(f"{channel.name}: {channel.sample_rate} Hz")

To just get a count without iterating:

count = arrakis.count("H1:LSC-.*")
print(f"Found {count} channels")

Stream Data

arrakis.api.stream yields arrakis.block.SeriesBlock objects as they become available, rather than waiting for the full time range to be fetched.

Live streaming

Omit the start and end times to stream live data starting from now:

for block in arrakis.stream(channels):
    print(f"t={block.time:.1f}  duration={block.duration}s")
    # process each block as it arrives...

Note

Live streaming runs indefinitely. Use Ctrl+C to stop, or break out of the loop when you have enough data.

Historical streaming

Provide start and end times to stream historical data in chunks:

for block in arrakis.stream(channels, start=1187000000, end=1187001000):
    print(f"t={block.time:.1f}  duration={block.duration}s")

This is useful when working with large time ranges where loading everything into memory at once with fetch() would be impractical.

Using the Client Directly

The convenience functions above (fetch, stream, find, etc.) create a new arrakis.client.Client for each call. If you are making multiple requests, it is best to create and reuse a client:

client = arrakis.Client()

metadata = client.describe(channels)
block = client.fetch(channels, start, end)

for block in client.stream(channels, start, end):
    print(block)

You can also specify a server URL explicitly:

client = arrakis.Client(url="grpc://my-server:31206")

See Connecting to Servers for more on server configuration.

Querying Server Metadata

You can query information about the server itself:

info = arrakis.server_info()  # server version, capabilities
domains = arrakis.domains()   # available domains, e.g. ["H1", "L1"]

See Server Information for details.

Next Steps