idelib.sync#

Functions to assist in syncing one file to another, and functions to adjust files’ timestamps based on the GPS/GNSS satelite time; two separate but related operations.

Syncing#

Syncing modifies the start time and timestamps of one or more Dataset objects’ recording session to match a ‘reference’ Dataset. Syncing is non-destructive; the sync can be repeatedly changed (i.e., a Dataset can be synced to a different reference) or removed without any cumulative effect to the timing.

Syncing can only be done with IDE files containing a common time reference channel; currently, only Wi-Fi enabled devices (i.e., the enDAQ W series) connected to the same Wi-Fi access point can create these. Note that the time sync reference channels are not shown in enDAQ Lab, but can be seen in Dataset.channels.

GPS/GNSS Time Adjustment#

Adjusting a recording’s starting timestamp using GPS/GNSS time requires the file was recorded on a device with a GPS module (e.g., an enDAQ W series recorder) and contains GPS/GNSS timing data. Please note that the former does not guarantee the latter; the GPS timing data may be missing if satellite reception was poor, or the recording ended before the signal was acquired.

Syncing and GPS/GNSS time adjustment can be used together by first applying the GPS/GNSS adjustment to the ‘reference’ recording before syncing other files to it. All recordings must have the same sync time channel, but only the ‘reference’ recording needs the GPS/GNSS data as well.

Usage#

While this module implements several functions, the primary ones are idelib.sync.sync() and idelib.sync.applyGNSSTime(). idelib.sync.updateUserdata() (in conjunction with idelib.userdata.writeUserData())can be used to save a recording’s calculated time/sync info into itself for later use.

exception idelib.sync.SyncError#

Exception raised when files cannot be synchronized.

idelib.sync.applyGNSSTime(data, clear=False)#

Modify the recording’s UTC start time using GPS/GNSS time data. Note that recordings with GPS/GNSS time bases cannot be synchronized to another recording; they should be the ‘reference’ recording to which others are synchronized.

Parameters

  • data (Dataset) – The recording to modify. It must contain GPS/GNSS time data.

  • clear – If True, remove any previous synchronization before updating the recording’s timebase. If False and the recording has been synced to another, a SyncError will be raised.

Returns

The recording’s original initial starting time and the new GNSS-corrected time (UNIX epoch seconds).

Return type

Tuple[float, float]

idelib.sync.applySyncInfo(dataset, info, validate=True)#

Apply a dictionary of sync info to a dataset.

Note that this function runs synchronously, and can block/be blocked by other functions affecting the contents of the Dataset.

Parameters

  • dataset (Dataset) – The Dataset to which the sync info will be applied.

  • info (Dict[str, Any]) – The dictionary of synchronization info to validate. The keys match the names of SyncInfo child elements in the mide_ide.xml EBML schema.

  • validate (bool) – If True, validate the sync info before applying.

idelib.sync.getCommonSensorIds(*datasets)#

Get the Sensor ID of the time reference shared by two or more recordings. This does not verify that any time data has been recorded from it, only that the sensor exists.

idelib.sync.getGNSSTimebase(data)#

Get the recording’s fine-grained UTC start time from its GPS/GNSS data.

Parameters

data (Union[Dataset, EventArray]) – The data from which to get the timebase. It can be either a Dataset (in which case it uses the first GNSS time source found) or an EventArray (to get the timebase from a specific subchannel).

Returns

The recording’s updated UTC start time with fractional seconds (UNIX epoch).

Return type

float

idelib.sync.getSyncInfo(dataset)#

Get a dictionary of sync info from a recording.

idelib.sync.getSyncSensor(dataset, sourceId=None, sourceName=None)#

Get a specific time reference sensor from a Dataset by name and/or identifier.

Parameters

  • dataset (Dataset) – The Dataset from which to get the sensor.

  • sourceId (Optional[str]) – The time reference sensor’s unique ID (e.g., the MAC address of a Wi-Fi access point generating TSF data).

  • sourceName (Optional[str]) – The name of the time reference sensor (e.g., the name of a Wi-Fi access point generating TSF data).

idelib.sync.getSyncSensors(dataset)#

Get all the ‘sensors’ in a Dataset that can be used for time synchronization.

idelib.sync.getSyncSources(dataset)#

Get the SubChannel instances that can be used for time synchronization.

Parameters

dataset (Dataset) – The Dataset from which to get the sources.

idelib.sync.getSyncTimeZero(data, start=None, end=None, sensorId=None, clear=False)#

Get the sync reference’s time corresponding to the recording’s relative timestamp zero.

Parameters

  • data (Union[Dataset, EventArray]) – The data from which to get the reference time. It can be either a Dataset (in which case it uses either the first sync source found or the one indicated by sensorId) or an EventArray (to use a specific subchannel as the time reference).

  • start (Optional[int]) – The starting index into the time reference data, to use a limited range to compute the zero offset. For use with large and/or noisy Datasets. Defaults to the beginning of the data.

  • end (Optional[int]) – The ending index into the time reference data, to use a limited range to compute the zero offset. For use with large and/or noisy Datasets. Defaults to the end of the data.

  • sensorId (Optional[int]) – The ID of a specific time reference sensor. Only used if data is a Dataset. If None, the first time reference sensor found is used.

  • clear (bool) – If False, use cached zero offset (if present).

Returns

The sync reference time (in microseconds) corresponding to the recording’s relative timestamp zero.

Return type

int

idelib.sync.hasSyncReferenceInfo(info)#

Check if a dictionary of sync info contains the information needed to sync to a reference recording (e.g., copied from a recording that has already been synced).

Parameters

info (Dict[str, Any]) – The dictionary of synchronization info to check. The keys match the names of SyncInfo child elements in the mide_ide.xml EBML schema.

idelib.sync.isSynced(data)#

Has the data been synchronized to another recording?

idelib.sync.loadSyncInfo(dataset, refresh=False)#

Read and apply sync info from a file’s userdata.

Parameters

  • dataset (Dataset) – The Dataset from which to load the sync info.

  • refresh (bool) – If True, ignore any cached user data and reload from the file.

Returns

True if sync info was present, False otherwise. Errors in the sync data will raise exceptions (e.g., SyncError).

Return type

bool

idelib.sync.makeSyncReferenceInfo(info)#

Create a dictionary of sync ‘reference’ info from a dictionary of sync ‘target’ info. For use with applySyncInfo() when applying sync info copied from another recording, to sync to that recording.

idelib.sync.removeGNSSTime(data)#

Remove the GPS/GNSS UTC start time from a recording, reverting to the original, device-generated initial timestamp.

idelib.sync.removeSync(data, clean=False)#

Remove sync info from a Dataset recording session. The UTC start time and timestamp offsets will revert to those originally in the file.

Note that this function runs synchronously, and can block/be blocked by other functions affecting the contents of the Dataset.

Parameters

  • data (Union[Dataset, EventArray, Session]) – The data from which to remove the sync info.

  • clean (bool) – If False, the information syncing this recording to another is removed, but metadata about the file itself is kept. If True, all sync-related info is completely removed.

idelib.sync.sync(reference, *datasets, sensorId=None, inherit=True)#

Synchronize one or more recordings with a canonical ‘reference’ recording. The ‘reference’ is not modified. Synched recordings will have their timestamps and UTC start time offset to match the reference.

Note that this function runs synchronously, and can block/be blocked by other functions affecting the contents of the Dataset.

Parameters

  • reference (Dataset) – The reference Dataset to which to synchronize the others.

  • datasets (Dataset) – One or more Dataset objects to synchronize.

  • sensorId (Optional[int]) – The time reference’s sensor ID. If None, the first common time reference sensor detected is used. Use if the recordings have multiple time references in common.

  • inherit (bool) – If True and the reference Dataset has been synced to another recording, sync the datasets to the same recording reference has been synced to. If False, clear existing sync info from the reference and sync the datasets to the reference’s zero time.

idelib.sync.updateUserdata(dataset)#

Create or update sync info in a Dataset’s userdata. Note that this does not save the updated user data to the file; the function idelib.userdata.writeUserData() must be called explicitly.

Parameters

dataset (Dataset) – The Dataset to update.

idelib.sync.validateSyncInfo(dataset, info)#

Check that a dictionary of sync info is valid for a dataset.

Parameters

  • dataset (Dataset) – The Dataset to which the sync info will be applied.

  • info (Dict[str, Any]) – The dictionary of synchronization info to validate. The keys match the names of SyncInfo child elements in the mide_ide.xml EBML schema.

On this page
Show Source