Jointly

Jointly is a python package for synchronizing sensors with accelerometer data. You need this package if you're a researcher who has recorded accelerometer data (plus possibly other data) on multiple sensors and wants to synchronize the multiple data streams precisely. Specifically, shake all your sensors together before and after a study and jointly will find these shakes, remove any temporal offset between sensors, and stretch the data so every clock aligns with a reference sensor. Jointly ingests and produces pandas DataFrame objects.

• Free software: MIT license
• Documentation: https://jointly.readthedocs.io

Features

• Detect and compare shakes in multiple sensor data streams
• Remove temporal offsets in the data
• Remove clock speed offsets by stretching the data

Installation

Install the package from pypi:

pip install jointly

You might want to check out our contributing guide in case you want to edit the package.

Usage

The data has to be provided in pandas DataFrame instances with a DateTimeIndex for each sensor. In the following example, Faros and Empatica are two sensors we want to synchronize, and we have already prepared dataframes for them. The Empatica is the reference source, and thus the Faros' data will be changed in the output. The ref_column is the column that contains the characteristic shake, and all other columns in the DataFrame will be synchronized together with that column.

import pandas as pd
import tempfile
import traceback

import jointly

# load source dataframes with datetime index
faros_df = pd.read_csv(
    "./test-data/faros-plus-physilog/faros.csv.gz",
    index_col=[0],
    parse_dates=True
)
physilog_df = pd.read_csv(
    "./test-data/faros-plus-physilog/physilog.csv.gz",
    index_col=[0],
    parse_dates=True,
)

# the magnitude is a common property that keeps shake information without axis relevance
faros_df["Accel Mag"] = jointly.calculate_magnitude(
    faros_df, ["Accel X", "Accel Y", "Accel Z"]
)
physilog_df["Accel Mag"] = jointly.calculate_magnitude(
    physilog_df, ["Accel X", "Accel Y", "Accel Z"]
)

# create dictionary of source sensors
sources = {
    "Faros": {
        "data": faros_df,
        "ref_column": "Accel Mag",
    },
    "Physilog": {
        "data": physilog_df,
        "ref_column": "Accel Mag",
    },
}

# set shake extraction parameters
extractor = jointly.ShakeExtractor()
extractor.start_window_length = pd.Timedelta(seconds=15)
extractor.end_window_length = pd.Timedelta(seconds=10)
extractor.min_length = 3
extractor.threshold = 0.55

# prepare the synchronizer
synchronizer = jointly.Synchronizer(
    sources, reference_source_name="Faros", extractor=extractor
)

# if the extractor parameters are wrong, print the problem and show the data
try:
    # get_synced_data returns a dictionary of sensor names to synced DataFrames
    synchronizer.get_synced_data()
except Exception:
    traceback.print_exc()
    jointly.plot_reference_columns(sources)

# save a file for each input sensor somewhere
with tempfile.TemporaryDirectory() as tmp_dir:
    synchronizer.save_pickles(tmp_dir)

Documentation Deep Links

Here you can find more information on specific topics:

• Preparing Data for Ingestion
• Tuning the Shake Detection
• Debugging the Shake Detection
• How to Save the Synchronized Data
• How to Enable Logging
• Full Explanation of the Synchronization

Template Credits

This package was created with Cookiecutter and the pyOpenSci/cookiecutter-pyopensci project template, based off audreyr/cookiecutter-pypackage.

Citation

Arne Herdick, Felix Musmann, Ariane Sasso, Justin Albert, & Bert Arnrich. (2022). Jointly: A Python package for synchronizing multiple sensors with accelerometer data (1.0.4). Zenodo. https://doi.org/10.5281/zenodo.5833858