Resources
Fetch data from Rune APIs.
By default, globally-initialized clients are used for all API requests (see
initialize
). Functions that make API requests
also accept optional client(s), which can be used in lieu of the global
initialization.
Metadata is fetched from Rune’s GraphQL API
(https://graph.runelabs.io/graphql), using a
GraphClient
. Timeseries data is fetched
from the V2 Stream API,
using a StreamClient
.
For example usage patterns, see Quickstart.
API Clients
Clients for Rune’s GraphQL API and V2 Stream API.
- runeq.resources.client.initialize(*args, **kwargs)
Initializes the library with specified configuration options. Sets global clients for requests to the GraphQL API and the V2 Stream API.
- Parameters
*args – Accepts at most 1; a filename. If provided, values will be loaded from the file. It is invalid to provide both a filename and keyword arguments.
**kwargs – Initialize client with keyword arguments. If using client keys, specify the client_key_id & client_access_key. If using access tokens, specify access_token_id & access_token_secret.
Examples
There are several valid ways to use this function:
>>> initialize() # Load the default config file (~/.rune/config)
>>> initialize('./example_config.yaml') # Load values from a YAML file at a specified path
>>> initialize(access_token_id='foo', access_token_secret='bar') >>> initialize(client_key_id='foo', client_access_key='bar') # Set configuration values using keyword arguments (instead # of a file). This can be used with any valid combination of # config options (e.g. with an access token OR a client key).
- runeq.resources.client.global_graph_client() GraphClient
Returns the globally configured GraphQL client. Use
initialize
to configure the client.- Raises
errors.InitializationError – if the library was not initialized.
- runeq.resources.client.global_stream_client() StreamClient
Returns the globally configured Stream API client. Use
initialize
to configure the client.- Raises
errors.InitializationError – if the library was not initialized.
- class runeq.resources.client.GraphClient(config: BaseConfig)
Rune GraphQL Client to query stream metadata.
- __init__(config: BaseConfig)
Initialize the Graph API Client.
- execute(statement: str, **variables) Dict
Execute a GraphQL query against the API.
- class runeq.resources.client.StreamClient(config: BaseConfig)
Client to query the V2 Stream API.
- __init__(config: BaseConfig)
Initialize the Stream API Client.
- get_data(path: str, **params) Iterator[Union[str, dict]]
Makes request(s) to an endpoint of the V2 Stream API. Iterates over responses, following pagination headers until all data has been fetched.
- Parameters
path – Path for an endpoint of the V2 Stream API.
**params – Query parameters. If the format parameter is “json”, responses are parsed as JSON. Otherwise, the response is returned as text.
- Returns
Iterator over the API responses. If the format parameter is “json”, each value is a dictionary. Otherwise, each value is a CSV-formatted string (the default for the V2 API).
- Raises
Patient Metadata
Fetch metadata about patients, including their devices.
Patients
- runeq.resources.patient.get_patient(patient_id: str, client: Optional[GraphClient] = None) Patient
Get the patient with the specified patient ID.
- Parameters
patient_id – Patient ID
client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- runeq.resources.patient.get_all_patients(client: Optional[GraphClient] = None) PatientSet
Get a set of all patients the user has access to.
- Parameters
client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- class runeq.resources.patient.Patient(id: str, name: str, created_at: float, devices: DeviceSet, **attributes)
A patient.
A patient represents a person about whom data was measured. This may include a StrivePD user, a person with a neural implant, etc. Each patient has a unique identifier (“patient ID”).
- __init__(id: str, name: str, created_at: float, devices: DeviceSet, **attributes)
Initialize with metadata.
- Parameters
id – ID of the patient
name – Human-readable display name for the patient
created_at – When the patient’s record was created (unix timestamp)
devices – Devices that belong to the patient
**attributes – Other attributes associated with the patient
- static denormalize_id(patient_id: str) str
Add resource prefix to a patient ID (if it doesn’t exist).
This constructs the form of the ID that is used for requests to the GraphQL API.
- Parameters
patient_id – Patient ID
- device(device_id: str) Device
Return the patient’s device with the specified device ID.
- Parameters
device_id – Device ID
- Raises
ValueError – if the patient does not have a device with the ID
- get(attr: str, default: Any = None)
Get the value of any attribute in self.attributes.
- property id: str
ID of the item.
- static normalize_id(patient_id: str) str
Strip resource prefix from a patient ID (if it exists).
- Parameters
patient_id – Patient ID
- to_dict() dict
Dictionary representation of the Patient attributes.
- class runeq.resources.patient.PatientSet(items: Iterable[Patient] = ())
A collection of Patients.
- add(item: ItemBase)
Add a single item to the set. Must be the same type as other members of the collection
- get(id: str) ItemBase
Get an item by id.
- Raises
ValueError – if the set does not contain an item with the ID.
- ids() Iterator[str]
Iterator over the IDs of the items in this set.
- remove(*items: Union[str, ItemBase])
Remove item(s) from this set.
- to_dataframe() DataFrame
Convert items to a dataframe (wraps to_list())
- to_list() List[dict]
List of all the items in the set. Each item is formatted as a dictionary, using the item’s to_dict() method.
- update(items: Iterable[ItemBase])
Add an iterable of item(s) to this set. All items must be the same class as members of this collection.
Devices
- runeq.resources.patient.get_device(patient: Union[Patient, str], device_id: str, client: Optional[GraphClient] = None) Device
Get a patient’s device, by the device ID.
Note that if a Patient object is provided, this function serves as a wrapper around Patient.device(). If a patient ID is provided, metadata is fetched from the API.
- Parameters
patient – a patient ID or Patient object
device_id – Device ID
client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- runeq.resources.patient.get_all_devices(patients: Union[PatientSet, List[str]] = None, client: Optional[GraphClient] = None) DeviceSet
Get a set of all devices belonging to a set of patients. If a specific set is not specified, returns all devices belonging to all patients in the user’s active organization.
- Parameters
patients – a list of patient IDs or a PatientSet
client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- class runeq.resources.patient.Device(id: str, patient_id: str, name: str, created_at: float, device_type_id: str, **attributes)
A patient device.
A device is a sensor serving as the datasource, such as a neural implant, phone, or wearable. Each device belongs to a patient. A patient may have multiple devices: each one has a unique identifier (“device ID”).
- __init__(id: str, patient_id: str, name: str, created_at: float, device_type_id: str, **attributes)
Initialize with metadata.
- Parameters
id – ID of the device
patient_id – ID of the patient
name – Human-readable name for the device
created_at – When the device was created (unix timestamp)
**attributes – Other attributes associated with the device
- static denormalize_id(patient_id: str, device_id: str) str
Add resource prefix and suffix to a patient/device ID.
This constructs the form of the ID that is used for requests to the GraphQL API.
- Parameters
patient_id – ID of the patient who owns the device
device_id – Device ID
- get(attr: str, default: Any = None)
Get the value of any attribute in self.attributes.
- property id: str
ID of the item.
- static normalize_id(device_id: str) str
Strip resource prefix and suffix from a device ID (if they exist).
- Parameters
device_id – Device ID
- to_dict() dict
Dictionary representation of the item’s attributes.
- class runeq.resources.patient.DeviceSet(items: Iterable[Device] = ())
A collection of Devices.
- add(item: ItemBase)
Add a single item to the set. Must be the same type as other members of the collection
- get(id: str) ItemBase
Get an item by id.
- Raises
ValueError – if the set does not contain an item with the ID.
- ids() Iterator[str]
Iterator over the IDs of the items in this set.
- remove(*items: Union[str, ItemBase])
Remove item(s) from this set.
- to_dataframe() DataFrame
Convert items to a dataframe (wraps to_list())
- to_list() List[dict]
List of all the items in the set. Each item is formatted as a dictionary, using the item’s to_dict() method.
- update(items: Iterable[ItemBase])
Add an iterable of item(s) to this set. All items must be the same class as members of this collection.
Organization Metadata
Fetch metadata about organizations. A research lab or clinical site is typically represented as an organization.
- runeq.resources.org.get_org(org_id: str, client: Optional[GraphClient] = None) Org
Get the org with the specified ID.
- Parameters
org_id – Organization ID
client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- runeq.resources.org.get_orgs(client: Optional[GraphClient] = None) OrgSet
Get all the organizations that the current user is a member of.
- Parameters
client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- runeq.resources.org.set_active_org(org: Union[str, Org], client: Optional[GraphClient] = None) Org
Set the active organization for the current user.
- Parameters
org – an org ID or Org
client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- Returns
The active organization
- class runeq.resources.org.Org(id: str, name: str, created_at: float, tags: Iterable = (), **attributes)
Metadata for an organization.
- __init__(id: str, name: str, created_at: float, tags: Iterable = (), **attributes)
Initialize with metadata.
- Parameters
id – ID of the organization
name – Human-readable name
created_at – When the organization was created (unix timestamp)
tags – Organization tags
**attributes – Other attributes associated with the organization
- static denormalize_id(org_id: str) str
Add resource prefix and suffix to an org ID (if they don’t exist).
This constructs the form of the ID that is used for requests to the GraphQL API.
- Parameters
org_id – Organization ID
- get(attr: str, default: Any = None)
Get the value of any attribute in self.attributes.
- property id: str
ID of the item.
- static normalize_id(org_id: str) str
Strip resource prefix and suffix from an org ID (if they exist).
- Parameters
org_id – Organization ID
- to_dict() dict
Dictionary representation of the item’s attributes.
- class runeq.resources.org.OrgSet(items: Iterable[Org] = ())
A collection of Organizations.
- add(item: ItemBase)
Add a single item to the set. Must be the same type as other members of the collection
- get(id: str) ItemBase
Get an item by id.
- Raises
ValueError – if the set does not contain an item with the ID.
- ids() Iterator[str]
Iterator over the IDs of the items in this set.
- remove(*items: Union[str, ItemBase])
Remove item(s) from this set.
- to_dataframe() DataFrame
Convert items to a dataframe (wraps to_list())
- to_list() List[dict]
List of all the items in the set. Each item is formatted as a dictionary, using the item’s to_dict() method.
- update(items: Iterable[ItemBase])
Add an iterable of item(s) to this set. All items must be the same class as members of this collection.
Stream Metadata
Fetch metadata about streams, including stream types.
- runeq.resources.stream_metadata.get_all_stream_types(client: Optional[GraphClient] = None) StreamTypeSet
Get all stream types.
- Parameters
client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- runeq.resources.stream_metadata.get_patient_stream_metadata(patient_id: str, device_id: Optional[str] = None, stream_type_id: Optional[str] = None, algorithm: Optional[str] = None, category: Optional[str] = None, measurement: Optional[str] = None, client: Optional[GraphClient] = None, **parameters) StreamMetadataSet
Get stream metadata for a patient’s streams, matching ALL filter parameters. Only the patient ID is required.
- Parameters
patient_id – Patient ID
device_id – Device ID
stream_type_id – Stream type ID
algorithm – A versioned label that describes the process that was used to derive this timeseries.
category – A broad categorization of the data type (e.g. neural, vitals, etc)
measurement – A specific label for what is being measured (e.g. heart_rate, step_count, etc).
client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
**parameters – Key/value pairs that label the stream.
- runeq.resources.stream_metadata.get_stream_availability_dataframe(stream_ids: Union[str, Iterable[str]], start_time: Union[float, date], end_time: Union[float, date], resolution: int, batch_operation: Optional[str] = None, limit: Optional[int] = None, page_token: Optional[str] = None, timestamp: Optional[str] = 'iso', timezone: Optional[int] = None, stream_client: Optional[StreamClient] = None, graph_client: Optional[GraphClient] = None) DataFrame
Get stream availability data as a dataframe. If a single stream_id is passed in, the dataframe will be enriched with the stream’s metadata. Otherwise it will contain just the availability data.
Note that this is different from the get_stream_availability_dataframe method on the
StreamMetadataSet
. This dataframe contains the availability of each individual stream.- Parameters
stream_ids – 1 or multiple stream IDs
start_time – Start time for the query, provided as a unix timestamp (in seconds) or a datetime.date.
end_time – End time for the query, provided as a unix timestamp (in seconds) or a datetime.date.
resolution – Interval between returned timestamps, in seconds.
batch_operation – Either “any” or “all”, which determines what type of batch calculation will determine availability for the batch of streams. Availability values will equal 1 when data is available for “all” or “any” of the requested streams in the given interval.
limit – Maximum number of timestamps to return, across all pages of the response. A limit of 0 (default) will fetch all available data.
page_token – Token to fetch the subsequent page of results. The value is obtained from the ‘X-Rune-Next-Page-Token’ response header field.
timestamp – Optional enum “unix”, “unixns”, or “iso”, which determines how timestamps are formatted in the response
timezone – Optional timezone offset, in seconds, used to calculate string-based timestamp formats such as datetime and iso. For example, PST (UTC-0800) is represented as -28800. If omitted, the timezone is UTC.
stream_client – If specified, this client is used to fetch data from the API. Otherwise, the global StreamClient is used.
graph_client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- runeq.resources.stream_metadata.get_stream_dataframe(stream_ids: Union[str, Iterable[str]], start_time: Optional[Union[float, date]] = None, start_time_ns: Optional[int] = None, end_time: Optional[Union[float, date]] = None, end_time_ns: Optional[int] = None, limit: Optional[int] = None, page_token: Optional[str] = None, timestamp: Optional[str] = 'iso', timezone: Optional[int] = None, translate_enums: Optional[bool] = True, stream_client: Optional[StreamClient] = None, graph_client: Optional[GraphClient] = None) DataFrame
Get stream(s) as enriched dataframe with stream data and metadata.
- Parameters
stream_ids – 1 or multiple stream IDs
start_time – Start time for the query, provided as a unix timestamp (in seconds) or a datetime.date.
start_time_ns – Start time for the query, provided as a unix timestamp (in nanoseconds).
end_time – End time for the query, provided as a unix timestamp (in seconds) or a datetime.date.
end_time_ns – End time for the query, provided as a unix timestamp (in nanoseconds).format: Optional enum “json” or “csv”, which determines the content type of the response
limit – Maximum number of timestamps to return, across all pages of the response. A limit of 0 (default) will fetch all available data.
page_token – Token to fetch the subsequent page of results. The value is obtained from the ‘X-Rune-Next-Page-Token’ response header field.
timestamp – Optional enum “unix”, “unixns”, or “iso”, which determines how timestamps are formatted in the response
timezone – Optional timezone offset, in seconds, used to calculate string-based timestamp formats such as datetime and iso. For example, PST (UTC-0800) is represented as -28800. If omitted, the timezone is UTC.
translate_enums – If True, enum values are returned as their string representation. Otherwise, enums are returned as integer values.
stream_client – If specified, this client is used to fetch data from the API. Otherwise, the global StreamClient is used.
graph_client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- Raises
RuneError – if any of the stream IDs is not found.
- runeq.resources.stream_metadata.get_stream_metadata(stream_ids: Union[str, Iterable[str]], client: Optional[GraphClient] = None) Union[StreamMetadata, StreamMetadataSet]
Get stream metadata for the specified stream_id(s).
- Parameters
stream_ids – ID of the stream or list of IDs
client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- Returns
if a single stream ID is specified StreamMetadataSet: if multiple stream IDs are specified
- Return type
- Raises
RuneError – if any of the stream IDs are not found
- class runeq.resources.stream_metadata.Dimension(id: str, data_type: str, quantity_name: str, unit_name: str, **attributes)
A dimension of a stream type. This is akin to a column in a table, where each value in the timeseries is a row.
- __init__(id: str, data_type: str, quantity_name: str, unit_name: str, **attributes)
Initialize with metadata.
- Parameters
id – Dimension ID
data_type – Data type (e.g. sfloat, timestamp, etc…)
quantity_name – Name of the quantity measured
unit_name – Name of the unit measurement
- get(attr: str, default: Any = None)
Get the value of any attribute in self.attributes.
- property id: str
ID of the item.
- to_dict() dict
Dictionary representation of the item’s attributes.
- class runeq.resources.stream_metadata.StreamMetadata(id: str, created_at: float, algorithm: str, device_id: str, patient_id: str, stream_type: StreamType, min_time: float, max_time: float, parameters: dict, **attributes)
Metadata for a stream (i.e. timeseries data). This class also has methods that fetch data for the stream.
- __init__(id: str, created_at: float, algorithm: str, device_id: str, patient_id: str, stream_type: StreamType, min_time: float, max_time: float, parameters: dict, **attributes)
Initialize with metadata.
- Parameters
id – Stream ID
created_at – When the stream was created, as a Unix timestamp, as a Unix timestamp (in seconds).
algorithm – A versioned label that describes the process that was used to derive this timeseries.
device_id – Device ID
patient_id – Patient ID
stream_type – Stream type, which categorizes the stream data.
min_time – The earliest timestamp in the stream, as a Unix timestamp (in seconds).
max_time – The latest timestamp in the stream, as a Unix timestamp (in seconds).
parameters – Key/value pairs that label the stream.
- get(attr: str, default: Any = None)
Get the value of any attribute in self.attributes.
- get_stream_availability_dataframe(start_time: Union[float, date], end_time: Union[float, date], resolution: int, limit: Optional[int] = None, page_token: Optional[str] = None, timestamp: Optional[str] = 'iso', timezone: Optional[int] = None, stream_client: Optional[StreamClient] = None) DataFrame
Get stream availability as an enriched Pandas dataframe. The dataframe includes columns with metadata for this stream. This allows for the concatenation of dataframes with availability for multiple streams.
- Parameters
start_time – Start time for the query, provided as a unix timestamp (in seconds) or a datetime.date.
end_time – End time for the query, provided as a unix timestamp (in seconds) or a datetime.date.
resolution – Interval between returned timestamps, in seconds.
limit – Maximum number of timestamps to return, across all pages of the response. A limit of 0 (default) will fetch all available data.
page_token – Token to fetch the subsequent page of results. The value is obtained from the ‘X-Rune-Next-Page-Token’ response header field.
timestamp – Optional enum “unix”, “unixns”, or “iso”, which determines how timestamps are formatted in the response
timezone – Optional timezone offset, in seconds, used to calculate string-based timestamp formats such as datetime and iso. For example, PST (UTC-0800) is represented as -28800. If omitted, the timezone is UTC.
stream_client – If specified, this client is used to fetch data from the API. Otherwise, the global StreamClient is used.
- get_stream_dataframe(start_time: Optional[Union[float, date]] = None, start_time_ns: Optional[int] = None, end_time: Optional[Union[float, date]] = None, end_time_ns: Optional[int] = None, limit: Optional[int] = None, page_token: Optional[str] = None, timestamp: Optional[str] = 'iso', timezone: Optional[int] = None, translate_enums: Optional[bool] = True, stream_client: Optional[StreamClient] = None) DataFrame
Get stream data as an enriched Pandas dataframe. In addition to the raw stream data, the dataframe also includes columns with stream metadata. This allows for the concatenation of dataframes with data from multiple streams.
- Parameters
start_time – Start time for the query, provided as a unix timestamp (in seconds) or a datetime.date.
start_time_ns – Start time for the query, provided as a unix timestamp (in nanoseconds).
end_time – End time for the query, provided as a unix timestamp (in seconds) or a datetime.date.
end_time_ns – End time for the query, provided as a unix timestamp (in nanoseconds).format: Optional enum “json” or “csv”, which determines the content type of the response
limit – Maximum number of timestamps to return, across all pages of the response. A limit of 0 (default) will fetch all available data.
page_token – Token to fetch the subsequent page of results. The value is obtained from the ‘X-Rune-Next-Page-Token’ response header field.
timestamp – Optional enum “unix”, “unixns”, or “iso”, which determines how timestamps are formatted in the response
timezone – Optional timezone offset, in seconds, used to calculate string-based timestamp formats such as datetime and iso. For example, PST (UTC-0800) is represented as -28800. If omitted, the timezone is UTC.
translate_enums – If True, enum values are returned as their string representation. Otherwise, enums are returned as integer values.
stream_client – If specified, this client is used to fetch data from the API. Otherwise, the global StreamClient is used.
- property id: str
ID of the item.
- iter_stream_data(start_time: Optional[Union[int, float, date, datetime]] = None, start_time_ns: Optional[int] = None, end_time: Optional[Union[int, float, date, datetime]] = None, end_time_ns: Optional[int] = None, format: Optional[str] = 'csv', limit: Optional[int] = None, page_token: Optional[str] = None, timestamp: Optional[str] = 'iso', timezone: Optional[int] = None, translate_enums: Optional[bool] = True, client: Optional[StreamClient] = None) Iterator[Union[str, dict]]
Iterate over CSV-formatted data for this stream.
- Parameters
start_time – Start time for the query, provided as a unix timestamp (in seconds), a datetime.datetime, or a datetime.date.
start_time_ns – Start time for the query, provided as a unix timestamp (in nanoseconds).
end_time – End time for the query, provided as a unix timestamp (in seconds), a datetime.datetime, or a datetime.date.
end_time_ns – End time for the query, provided as a unix timestamp (in nanoseconds).
format – Either “csv” (default) or “json”. Determines the content type of the API response, as well as the type that is returned from this function.
limit – Maximum number of timestamps to return, across all pages of the response. A limit of 0 (default) will fetch all available data.
page_token – Token to fetch the subsequent page of results. The value is obtained from the “X-Rune-Next-Page-Token” response header field.
timestamp – One of “unix”, “unixns”, or “iso”, which determines how timestamps are formatted in the response
timezone – Timezone offset, in seconds, used to calculate string-based timestamp formats such as datetime and iso. For example, PST (UTC-0800) is represented as -28800. If omitted, the timezone is UTC.
translate_enums – If True, enum values are returned as their string representation. Otherwise, enums are returned as integer values.
client – If specified, this client is used to fetch data from the API. Otherwise, the global
StreamClient
is used.
- Returns
An iterator over paginated API responses. If format is “json”, each response is a dict. If format is “csv”, each response is a CSV-formatted string.
- to_dict() dict
Dictionary representation of the StreamMetadata attributes.
- class runeq.resources.stream_metadata.StreamMetadataSet(items: Iterable[StreamMetadata] = ())
A collection of StreamMetadata.
- __init__(items: Iterable[StreamMetadata] = ())
Initialize with StreamMetadatas
- add(item: ItemBase)
Add a single item to the set. Must be the same type as other members of the collection
- filter(stream_id: Optional[str] = None, patient_id: Optional[str] = None, device_id: Optional[str] = None, stream_type_id: Optional[str] = None, algorithm: Optional[str] = None, category: Optional[str] = None, measurement: Optional[str] = None, filter_function: Optional[Callable[[StreamMetadata], bool]] = None, **parameters) StreamMetadataSet
Filters streams for those that match ALL optional filter parameters. Returns a new StreamMetadataSet.
- Parameters
stream_id – Stream ID
patient_id – Patient ID
device_id – Device ID
stream_type_id – Stream type ID
algorithm – A versioned label that describes the process that was used to derive this timeseries.
category – A broad categorization of the data type (e.g. neural, vitals, etc)
measurement – A specific label for what is being measured (e.g. heart_rate, step_count, etc).
filter_function – User-defined filter function which accepts a Stream as a single argument and returns a boolean indicating whether to keep that stream.
- get(id: str) ItemBase
Get an item by id.
- Raises
ValueError – if the set does not contain an item with the ID.
- get_batch_availability_dataframe(start_time: Union[float, date], end_time: Union[float, date], resolution: int, batch_operation: Optional[str] = None, limit: Optional[int] = None, page_token: Optional[str] = None, timestamp: Optional[str] = 'iso', timezone: Optional[int] = None, stream_client: Optional[StreamClient] = None) DataFrame
Get stream availability data as a Pandas dataframe. Depending on the specified batch_operation, this fetches the availability of all or any of the streams in the collection.
If you want to gather the availability of each individual stream in a dataframe, see get_stream_availability_dataframe()
- Parameters
start_time – Start time for the query, provided as a unix timestamp (in seconds) or a datetime.date.
end_time – End time for the query, provided as a unix timestamp (in seconds) or a datetime.date.
resolution – Interval between returned timestamps, in seconds.
batch_operation – Either “any” or “all”, which determines what type of batch calculation will determine availability for the batch of streams. Availability values will equal 1 when data is available for “all” or “any” of the requested streams in the given interval.
limit – Maximum number of timestamps to return, across all pages of the response. A limit of 0 (default) will fetch all available data.
page_token – Token to fetch the subsequent page of results. The value is obtained from the ‘X-Rune-Next-Page-Token’ response header field.
timestamp – Optional enum “unix”, “unixns”, or “iso”, which determines how timestamps are formatted in the response
timezone – Optional timezone offset, in seconds, used to calculate string-based timestamp formats such as datetime and iso. For example, PST (UTC-0800) is represented as -28800. If omitted, the timezone is UTC.
stream_client – If specified, this client is used to fetch data from the API. Otherwise, the global StreamClient is used.
- get_stream_dataframe(start_time: Optional[Union[float, date]] = None, start_time_ns: Optional[int] = None, end_time: Optional[Union[float, date]] = None, end_time_ns: Optional[int] = None, limit: Optional[int] = None, page_token: Optional[str] = None, timestamp: Optional[str] = 'iso', timezone: Optional[int] = None, translate_enums: Optional[bool] = True, stream_client: Optional[StreamClient] = None) DataFrame
Get raw data for all streams in the collection, as an enriched Pandas dataframe. The dataframe includes columns with metadata for each stream.
- Parameters
start_time – Start time for the query, provided as a unix timestamp (in seconds) or a datetime.date.
start_time_ns – Start time for the query, provided as a unix timestamp (in nanoseconds).
end_time – End time for the query, provided as a unix timestamp (in seconds) or a datetime.date.
end_time_ns – End time for the query, provided as a unix timestamp (in nanoseconds).format: Optional enum “json” or “csv”, which determines the content type of the response
limit – Maximum number of timestamps to return, across all pages of the response. A limit of 0 (default) will fetch all available data.
page_token – Token to fetch the subsequent page of results. The value is obtained from the ‘X-Rune-Next-Page-Token’ response header field.
timestamp – Optional enum “unix”, “unixns”, or “iso”, which determines how timestamps are formatted in the response
timezone – Optional timezone offset, in seconds, used to calculate string-based timestamp formats such as datetime and iso. For example, PST (UTC-0800) is represented as -28800. If omitted, the timezone is UTC.
translate_enums – If True, enum values are returned as their string representation. Otherwise, enums are returned as integer values.
stream_client – If specified, this client is used to fetch data from the API. Otherwise, the global StreamClient is used.
- ids() Iterator[str]
Iterator over the IDs of the items in this set.
- remove(*items: Union[str, ItemBase])
Remove item(s) from this set.
- to_dataframe() DataFrame
Convert items to a dataframe (wraps to_list())
- to_list() List[dict]
List of all the items in the set. Each item is formatted as a dictionary, using the item’s to_dict() method.
- update(items: Iterable[ItemBase])
Add an iterable of item(s) to this set. All items must be the same class as members of this collection.
- class runeq.resources.stream_metadata.StreamType(id: str, name: str, description: str, dimensions: List[Dimension], **attributes)
A stream type to categorize streams.
It represents the physical quantity being measured (voltage, acceleration, etc), including the unit of measurement. It also describes the shape of the stream’s data, as one or more dimensions.
- __init__(id: str, name: str, description: str, dimensions: List[Dimension], **attributes)
Initialize with metadata.
- Parameters
id – StreamType ID
name – Human-readable name of the stream type
description – Human-readable description of the stream type
dimensions – List of Dimensions in this stream type
- get(attr: str, default: Any = None)
Get the value of any attribute in self.attributes.
- property id: str
ID of the item.
- to_dict() dict
Dictionary representation of the Stream Type attributes.
- class runeq.resources.stream_metadata.StreamTypeSet(items: Iterable[StreamType] = ())
A collection of StreamTypes.
- __init__(items: Iterable[StreamType] = ())
Initialize with StreamTypes.
- add(item: ItemBase)
Add a single item to the set. Must be the same type as other members of the collection
- get(id: str) ItemBase
Get an item by id.
- Raises
ValueError – if the set does not contain an item with the ID.
- ids() Iterator[str]
Iterator over the IDs of the items in this set.
- remove(*items: Union[str, ItemBase])
Remove item(s) from this set.
- to_dataframe() DataFrame
Convert items to a dataframe (wraps to_list())
- to_list() List[dict]
List of all the items in the set. Each item is formatted as a dictionary, using the item’s to_dict() method.
- update(items: Iterable[ItemBase])
Add an iterable of item(s) to this set. All items must be the same class as members of this collection.
Stream Data
Query data directly from the V2 Stream API.
- runeq.resources.stream.get_stream_availability(stream_ids: Union[str, Iterable[str]], start_time: Union[int, float, date, datetime], end_time: Union[int, float, date, datetime], resolution: int, batch_operation: Optional[str] = None, format: Optional[str] = 'csv', limit: Optional[int] = None, page_token: Optional[str] = None, timestamp: Optional[str] = 'iso', timezone: Optional[int] = None, timezone_name: Optional[str] = None, client: Optional[StreamClient] = None) Iterator[Union[str, dict]]
Fetch the availability of 1 or multiple streams. When multiple stream IDs are specified, this fetches the availability of all or any of the streams (depending on the batch_operation).
- Parameters
stream_ids – 1 or multiple stream IDs. If multiple stream IDs are specified, batch_operation is also required.
start_time – Start time for the query, provided as a unix timestamp (in seconds), a datetime.datetime, or a datetime.date.
end_time – End time for the query, provided as a unix timestamp (in seconds), a datetime.datetime, or a datetime.date.
resolution – Interval between returned timestamps, in seconds.
batch_operation – Either “any” or “all”, which determines what type of batch calculation will determine availability for multiple streams. Availability values will equal 1 when data is available for “all” or “any” of the requested streams in the given interval. This argument is required when multiple stream_ids are specified.
format – Either “csv” (default) or “json”. Determines the content type of the API response.
limit – Maximum number of timestamps to return, across all pages of the response. A limit of 0 (default) will fetch all available data.
page_token – Token to fetch the subsequent page of results. The value is obtained from the “X-Rune-Next-Page-Token” response header field.
timestamp – One of “unix”, “unixns”, or “iso”, which determines how timestamps are formatted in the response
timezone – Timezone offset, in seconds, used to calculate string-based timestamp formats such as datetime and iso. For example, PST (UTC-0800) is represented as -28800. If omitted, the timezone is UTC.
timezone_name – The name from the IANA timezone database used to calculate string-based timestamp formats such as datetime and iso. Returns the correct UTC offset for a given date/time in order to account for daylight savings time.
client – If specified, this client is used to fetch data from the API. Otherwise, the global
StreamClient
is used.
- Returns
An iterator over paginated API responses. If format is “json”, each response is a dict. If format is “csv”, each response is a CSV-formatted string.
- Raises
ValueError – if batch_operation is not specified and querying for more than 1 stream_id
- runeq.resources.stream.get_stream_data(stream_id: str, start_time: Optional[Union[int, float, date, datetime]] = None, start_time_ns: Optional[int] = None, end_time: Optional[Union[int, float, date, datetime]] = None, end_time_ns: Optional[int] = None, format: Optional[str] = 'csv', limit: Optional[int] = None, page_token: Optional[str] = None, timestamp: Optional[str] = 'iso', timezone: Optional[int] = None, timezone_name: Optional[str] = None, translate_enums: Optional[bool] = True, client: Optional[StreamClient] = None) Iterator[Union[str, dict]]
Fetch raw data for a stream.
- Parameters
stream_id – ID of the stream
start_time – Start time for the query, provided as a unix timestamp (in seconds), a datetime.datetime, or a datetime.date.
start_time_ns – Start time for the query, provided as a unix timestamp (in nanoseconds).
end_time – End time for the query, provided as a unix timestamp (in seconds), a datetime.datetime, or a datetime.date.
end_time_ns – End time for the query, provided as a unix timestamp (in nanoseconds).
format – Either “csv” (default) or “json”. Determines the content type of the API response.
limit – Maximum number of timestamps to return, across all pages of the response. A limit of 0 (default) will fetch all available data.
page_token – Token to fetch the subsequent page of results. The value is obtained from the “X-Rune-Next-Page-Token” response header field.
timestamp – One of “unix”, “unixns”, or “iso”, which determines how timestamps are formatted in the response
timezone – Timezone offset, in seconds, used to calculate string-based timestamp formats such as datetime and iso. For example, PST (UTC-0800) is represented as -28800. If omitted, the timezone is UTC.
timezone_name – The name from the IANA timezone database used to calculate string-based timestamp formats such as datetime and iso. Returns the correct UTC offset for a given date/time in order to account for daylight savings time.
translate_enums – If True, enum values are returned as their string representation. Otherwise, enums are returned as integer values.
client – If specified, this client is used to fetch data from the API. Otherwise, the global
StreamClient
is used.
- Returns
An iterator over paginated API responses. If format is “json”, each response is a dict. If format is “csv”, each response is a CSV-formatted string.
User Metadata
Fetch metadata about Rune platform users.
- runeq.resources.user.get_current_user(client: Optional[GraphClient] = None) User
Get information about the current user (based on the API credentials).
- Parameters
client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- class runeq.resources.user.User(id: str, name: str, created_at: float, active_org_id: str, active_org_name: str, **attributes)
A user of the Rune platform.
- __init__(id: str, name: str, created_at: float, active_org_id: str, active_org_name: str, **attributes)
Initialize with metadata.
- Parameters
id – User ID
name – Human-readable display name for the user
created_at – When the user was created (unix timestamp)
active_org_id – ID of the user’s currently active organization
active_org_name – Display name of the user’s currently active organization
- get(attr: str, default: Any = None)
Get the value of any attribute in self.attributes.
- property id: str
ID of the item.
- static normalize_id(user_id: str) str
Strip resource prefix and suffix from the user ID (if they exist).
- Parameters
user_id – User ID
- to_dict() dict
Dictionary representation of the item’s attributes.
Project Metadata
Fetch metadata about projects.
Projects
- runeq.resources.project.get_projects(client: Optional[GraphClient] = None) ProjectSet
Get all the projects that the current user has access to.
- Parameters
client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- runeq.resources.project.get_project(project_id: str, client: Optional[GraphClient] = None) Project
Get the project with the specified ID.
- Parameters
project_id – Project ID
client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- runeq.resources.project.get_project_patients(project_id: str, client: Optional[GraphClient] = None) ProjectPatientMetadataSet
Get all patients in a project and their associated project data metrics.
- Parameters
project_id – ID of the project
client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- Project(id: str, title: str, status: str, type: str, started_at: float, updated_at: float, created_at: float, created_by: str, updated_by: str, cohorts: CohortSet {
- Project}, **attributes)
Metadata for a project.
A project is a generic container for a group of patients with workflow-related metadata: status, project type, description, milestones dates, etc. Data availability QC metrics are computed on a regular basis for all patients in a project.
- Project.__init__(id: str, title: str, status: str, type: str, started_at: float, updated_at: float, created_at: float, created_by: str, updated_by: str, cohorts: CohortSet {
- Project.__init__}, **attributes)
Initialize with data.
- Parameters
id – ID of the project
title – Human-readable name
status – Status of the project
type – Type of project. Possible types include: EXPLORATORY, CLINICAL_TRIAL,RETROSPECTIVE_STUDY, PROSPECTIVE_STUDY, SANDBOX
started_at – Time the project started (unix timestamp)
created_at – Time the project was created (unix timestamp)
created_by – Display name of who created the project
updated_at – Time the project was last updated (unix timestamp)
updated_by – Display name of who updated the project
cohorts – Sub-containers of patients in a project
**attributes – Other attributes associated with the project
- Project.get(attr: str, default: Any = None)
Get the value of any attribute in self.attributes.
- property Project.id: str
ID of the item.
- Project.to_dict() dict
Dictionary representation of the Project attributes.
- class runeq.resources.project.ProjectSet(items: Iterable[Project] = ())
A collection of Projects.
- __init__(items: Iterable[Project] = ())
Initialize with Projects.
- add(item: ItemBase)
Add a single item to the set. Must be the same type as other members of the collection
- get(id: str) ItemBase
Get an item by id.
- Raises
ValueError – if the set does not contain an item with the ID.
- ids() Iterator[str]
Iterator over the IDs of the items in this set.
- remove(*items: Union[str, ItemBase])
Remove item(s) from this set.
- to_dataframe() DataFrame
Convert items to a dataframe (wraps to_list())
- to_list() List[dict]
List of all the items in the set. Each item is formatted as a dictionary, using the item’s to_dict() method.
- update(items: Iterable[ItemBase])
Add an iterable of item(s) to this set. All items must be the same class as members of this collection.
- class runeq.resources.project.ProjectPatientMetadata(id: str, updated_at: float, created_at: float, created_by: str, updated_by: str, metrics: MetricSet, **attributes)
A patient who has been placed within a project and is now associated with the project.
- __init__(id: str, updated_at: float, created_at: float, created_by: str, updated_by: str, metrics: MetricSet, **attributes)
Initialize with data.
- Parameters
id – Patient ID of the patient in the cohort
created_at – Time patient was added to the project (unix timestamp)
created_by – Display name of who added the patient to the project
updated_at – Time project patient was last updated (unix timestamp)
updated_by – Display name of who updated the project patient record
metrics – Project data metrics related to the patient’s data
**attributes – Other attributes associated with the project
- get(attr: str, default: Any = None)
Get the value of any attribute in self.attributes.
- get_patient_metadata_dataframe() DataFrame
Returns a new dataframe displaying the patient’s metadata.
- property id: str
ID of the item.
- to_dict() dict
Dictionary representation of the Project Patient attributes.
- class runeq.resources.project.ProjectPatientMetadataSet(items: Iterable[ProjectPatientMetadata] = ())
A collection of ProjectPatientMetadata.
- __init__(items: Iterable[ProjectPatientMetadata] = ())
Initialize with ProjectPatientMetadata.
- add(item: ItemBase)
Add a single item to the set. Must be the same type as other members of the collection
- get(id: str) ItemBase
Get an item by id.
- Raises
ValueError – if the set does not contain an item with the ID.
- ids() Iterator[str]
Iterator over the IDs of the items in this set.
- remove(*items: Union[str, ItemBase])
Remove item(s) from this set.
- to_dataframe() DataFrame
Convert items to a dataframe (wraps to_list())
- to_list() List[dict]
List of all the items in the set. Each item is formatted as a dictionary, using the item’s to_dict() method.
- update(items: Iterable[ItemBase])
Add an iterable of item(s) to this set. All items must be the same class as members of this collection.
Cohorts
- runeq.resources.project.get_cohort_patients(cohort_id: str, client: Optional[GraphClient] = None) CohortPatientMetadataSet
Get all patients in a cohort.
- Parameters
cohort_id – ID of the cohort
client – If specified, this client is used to fetch metadata from the API. Otherwise, the global GraphClient is used.
- class runeq.resources.project.Cohort(id: str, title: str, updated_at: float, created_at: float, created_by: str, updated_by: str, **attributes)
A generic sub-container for a group of patients within a project.
A cohort is a generic container within a project for a group of patients with workflow-related metadata: description, milestones dates, metrics, etc.
A single project can have multiple cohorts.
- __init__(id: str, title: str, updated_at: float, created_at: float, created_by: str, updated_by: str, **attributes)
Initialize with data.
- Parameters
id – ID of the project
title – Human-readable name
created_at – Time the cohort was created (unix timestamp)
created_by – Display name of who created the cohort
updated_at – Time the cohort was last updated (unix timestamp)
updated_by – Display name of who updated the cohort
**attributes – Other attributes associated with the cohort
- get(attr: str, default: Any = None)
Get the value of any attribute in self.attributes.
- property id: str
ID of the item.
- to_dict() dict
Dictionary representation of the item’s attributes.
- class runeq.resources.project.CohortSet(items: Iterable[Cohort] = ())
A collection of Cohorts.
- add(item: ItemBase)
Add a single item to the set. Must be the same type as other members of the collection
- get(id: str) ItemBase
Get an item by id.
- Raises
ValueError – if the set does not contain an item with the ID.
- ids() Iterator[str]
Iterator over the IDs of the items in this set.
- remove(*items: Union[str, ItemBase])
Remove item(s) from this set.
- to_dataframe() DataFrame
Convert items to a dataframe (wraps to_list())
- to_list() List[dict]
List of all the items in the set. Each item is formatted as a dictionary, using the item’s to_dict() method.
- update(items: Iterable[ItemBase])
Add an iterable of item(s) to this set. All items must be the same class as members of this collection.
- class runeq.resources.project.CohortPatientMetadata(id: str, updated_at: float, created_at: float, created_by: str, updated_by: str, metrics: MetricSet, **attributes)
Cohort related information about a patient contained in a cohort.
- __init__(id: str, updated_at: float, created_at: float, created_by: str, updated_by: str, metrics: MetricSet, **attributes)
Initialize with data.
- Parameters
id – Patient ID of the patient in the cohort
created_at – Time patient was added to the cohort (unix timestamp)
created_by – Display name of who added the patient to the cohort
updated_at – Time cohort patient was last updated (unix timestamp)
updated_by – Display name of who updated the cohort patient record
metrics – Project data metrics related to the patient’s data
**attributes – Other attributes associated with the cohort
- get(attr: str, default: Any = None)
Get the value of any attribute in self.attributes.
- get_patient_metadata_dataframe() DataFrame
Returns a new dataframe displaying the patient’s metadata.
- property id: str
ID of the item.
- to_dict() dict
Dictionary representation of the Project Patient attributes.
- class runeq.resources.project.CohortPatientMetadataSet(items: Iterable[CohortPatientMetadata] = ())
A collection of CohortPatientMetadata.
- __init__(items: Iterable[CohortPatientMetadata] = ())
Initialize with CohortPatientMetadata.
- add(item: ItemBase)
Add a single item to the set. Must be the same type as other members of the collection
- get(id: str) ItemBase
Get an item by id.
- Raises
ValueError – if the set does not contain an item with the ID.
- ids() Iterator[str]
Iterator over the IDs of the items in this set.
- remove(*items: Union[str, ItemBase])
Remove item(s) from this set.
- to_dataframe() DataFrame
Convert items to a dataframe (wraps to_list())
- to_list() List[dict]
List of all the items in the set. Each item is formatted as a dictionary, using the item’s to_dict() method.
- update(items: Iterable[ItemBase])
Add an iterable of item(s) to this set. All items must be the same class as members of this collection.
Metrics
- class runeq.resources.project.Metric(id: str, type: str, data_type: str, time_interval: str, updated_at: float, created_at: float, value: Optional[float] = None)
A measurement related to processed patient data. Each metric is related to a single processed data type, project, and time interval. These metrics are calculated periodically and updated.
- __init__(id: str, type: str, data_type: str, time_interval: str, updated_at: float, created_at: float, value: Optional[float] = None)
Initialize with data.
- Parameters
id – Unique identifier of the patient
type – Type of measurement/metric. Possible types include: TOTAL_HOURS, LATEST_DATA, LAST_UPLOAD
data_type – Processed stream data type that is being measured. Possible data types include: APPLEWATCH_SYMPTOM, APPLEWATCH_TREMOR, APPLEWATCH_DYSKINESIA, APPLEWATCH_HEART_RATE, PERCEPT_TREND_LOG_LFP
value – Value of the metric (float)
time_interval – Period over which the metric was calculated. Possible time intervals include: FOURTEEN_DAYS, NINETY_DAYS, PROJECT_ALL
created_at – Time patient was added to the cohort (unix timestamp)
updated_at – Time cohort patient was last updated (unix timestamp)
- get(attr: str, default: Any = None)
Get the value of any attribute in self.attributes.
- property id: str
ID of the item.
- to_dict() dict
Dictionary representation of the item’s attributes.
- class runeq.resources.project.MetricSet(items: Iterable[Metric] = ())
A collection of Metrics.
- add(item: ItemBase)
Add a single item to the set. Must be the same type as other members of the collection
- get(id: str) ItemBase
Get an item by id.
- Raises
ValueError – if the set does not contain an item with the ID.
- ids() Iterator[str]
Iterator over the IDs of the items in this set.
- remove(*items: Union[str, ItemBase])
Remove item(s) from this set.
- to_dataframe() DataFrame
Convert items to a dataframe (wraps to_list())
- to_list() List[dict]
List of all the items in the set. Each item is formatted as a dictionary, using the item’s to_dict() method.
- update(items: Iterable[ItemBase])
Add an iterable of item(s) to this set. All items must be the same class as members of this collection.