rtCommon.bidsInterface

BidsInterface is a client interface (i.e. for the experiment script running in the cloud) that provides data access to BIDS data.

To support RPC calls from the client, there will be two instances of dataInterface, one at the cloud projectServer which is a stub to forward requests (started with dataRemote=True), and another at the control room computer, run as a service and with dataRemote=False.

When not using RPC, i.e. when the projectServer is run without –dataRemote, there will be only one instance of dataInterface, as part of the projectServer with dataRemote=False.

Module Contents

Classes

BidsInterface	Provides functions for accessing remote or local BIDS data depending on if dataRemote flag
DicomToBidsStream	A class that watches for DICOM file creation in a specified directory and with
BidsStream	A class that opens a BIDS archive and prepares to stream the data as

class rtCommon.bidsInterface.BidsInterface(dataRemote=False, allowedDirs=[], scannerClockSkew=0)

Bases: rtCommon.remoteable.RemoteableExtensible

Provides functions for accessing remote or local BIDS data depending on if dataRemote flag is set true or false.

If dataRemote=True, then the RemoteExtensible parent class takes over and forwards all requests to a remote server via a callback function registered with the RemoteExtensible object. In that case none of the methods below will be locally invoked.

If dataRemote=False, then the methods below will be invoked locally and the RemoteExtensible parent class is inoperable (i.e. does nothing).

initDicomBidsStream(dicomDir, dicomFilePattern, dicomMinSize, anonymize=True, **entities) → int

Intialize a data stream that watches a directory for DICOM files to be written that match the given file pattern. When a DICOM is written it will be converted to a BIDS incremental and returned.

Parameters

• dicomDir – the directory where the images are or will be written from the MRI scanner.

• dicomFilePattern – a pattern of the image file names that has a TR tag which will be used to index the images, for example ‘scan01_{TR:03d}.dcm’. In this example a call to getImageData(imgIndex=6) would look for dicom file ‘scan01_006.dcm’.

• minFileSize – Minimum size of the file to return (continue waiting if below this size)

• anonymize – Whether to remove participant specific fields from the Dicom header

• entities – BIDS entities (subject, session, task, run, suffix, datatype) that will be required to fill in the BIDS metadata in the BIDS Incremental

Returns

An int identifier to be used when calling stream functions, such as getIncremental()

Return type

streamId

initBidsStream(archivePath, **entities) → int

Initialize a data stream from an existing BIDS archive.

Parameters

• archivePath – Full path to the BIDS archive

• entities – BIDS entities (subject, session, task, run, suffix, datatype) that define the particular subject/run of the data to stream

Returns

An int identifier to be used when calling stream functions, such as getIncremental()

Return type

streamId

initOpenNeuroStream(dsAccessionNumber, **entities) → int

Initialize a data stream that replays an OpenNeuro dataset.

Parameters

• dsAccessionNumber – OpenNeuro accession number of the dataset to replay

• entities – BIDS entities (subject, session, task, run, suffix, datatype) that define the particular subject/run of the data to stream

Returns

An identifier used when calling stream functions, such as getIncremental()

Return type

streamId

getIncremental(streamId, volIdx=-1, timeout=5, demoStep=0) → rtCommon.bidsIncremental.BidsIncremental

Get a BIDS Incremental from a stream

Parameters

• streamId – The stream handle returned by the initXXStream call

• volIdx – The brain volume index of the image to return. If -1 is entered it will return the next volume

• timeout – Max number of seconds to wait for incremental when running real-time

• demoStep – Simulate x second TR delay

Returns

A BidsIncremental containing the image volume

getNumVolumes(streamId) → int

Return the number of image volumes contained in the stream. This is only defined for Bids/OpenNeuro streams (not for DicomBidsStreams)

Parameters

streamId – The stream handle returned by the initXXStream call

Returns

An int of the number of volumes

closeStream(streamId)

getClockSkew(callerClockTime: float, roundTripTime: float) → float

Returns the clock skew between the caller’s computer and the scanner clock. This function is assumed to be running in the scanner room and have adjustments to translate this server’s clock to the scanner clock. Value returned is in seconds. A positive number means the scanner clock is ahead of the caller’s clock. The caller should add the skew to their localtime to get the time in the scanner’s clock.

Parameters

• time (callerClockTime - current) –

• caller (roundTripTime - measured RTT in seconds to remote) –

Returns

Clockskew - seconds the scanner’s clock is ahead of the caller’s clock

ping() → float

Returns seconds since the epoch

class rtCommon.bidsInterface.DicomToBidsStream(allowedDirs=[])

A class that watches for DICOM file creation in a specified directory and with a specified file pattern. When DICOM files arrive it converts them to BIDS incrementals and returns the BIDS incremental. This lets a real-time classification script process data directly as BIDS as it arrives from the scanner.

initStream(dicomDir, dicomFilePattern, dicomMinSize, anonymize=True, **entities)

Intialize a new DicomToBids stream, watches for Dicoms and streams as BIDS

Parameters

• dicomDir – The directory where the scanner will write new DICOM files

• dicomFilePattern – A regex style pattern of the DICOM filenames to watch for. They should include a {TR} tag with optional formatting. For example filenames like ‘001_000013_000005.dcm’ would have a pattern ‘001_000013_{TR:06d}.dcm’ where the volume number (TR) will be filled in by a 6 digit leading zeros value.

• dicomMinSize – Minimum size of the file to return (will continue waiting if below this size)

• anonymize – Whether to remove participant specific fields from the Dicom header

• entities – BIDS entities (subject, session, task, run, suffix, datatype) that define the particular subject/run of the data to stream

abstract getNumVolumes() → int

Return the number of brain volumes in the run, unknowable by this interface ahead of time for a real-time DICOM stream

getIncremental(volIdx=-1, timeout=5, demoStep=0) → rtCommon.bidsIncremental.BidsIncremental

Get the BIDS incremental for the corresponding DICOM image indicated by the volIdx, where volIdx is equivalent to TR id.

VolIdx acts similar to a file_seek pointer. If a volIdx >= 0 is supplied the volume pointer is advanced to that position. If no volIdx or a volIdx < 0 is supplied, then the next image volume after the previous position is returned and the pointer is incremented.

Parameters

• volIdx – The volume index (or TR) within the run to retrieve.

• timeout – Max number of seconds to wait for incremental

Returns

BidsIncremental for the matched DICOM for the run/volume

class rtCommon.bidsInterface.BidsStream(archivePath, **entities)

A class that opens a BIDS archive and prepares to stream the data as BIDS incrementals.

getNumVolumes() → int

Return the number of brain volumes in the run

getIncremental(volIdx=-1, timeout=5, demoStep=0) → rtCommon.bidsIncremental.BidsIncremental

Get a BIDS incremental for the indicated index in the current subject/run VolIdx acts similar to a file_seek pointer. If a volIdx >= 0 is supplied the volume pointer is advanced to that position. If no volIdx or a volIdx < 0 is supplied, then the next image volume after the previous position is returned and the pointer is incremented.

Parameters

• volIdx – The volume index (or TR) within the run to retrieve.

• timeout – Not used but present to support calling convention of other stream types

Returns

BidsIncremental of that volume index within this subject/run