jointly readme

https://img.shields.io/pypi/v/jointly.svg https://github.com/hpi-dhc/jointly/actions/workflows/deploy.yml/badge.svg https://github.com/hpi-dhc/jointly/actions/workflows/all.yml/badge.svg https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/enra64/f731de158a21515e2d6c52ed48d406ad/raw/jointly_coverage_main.json Documentation Status Updates https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg

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 want to precisely synchronize the multiple data streams. Specifically, shake all your sensors in a box before and after a trial, and jointly will find these shakes, remove any temporal offset between sensors, and stretch the data so every clock aligns to a reference sensor. Jointly ingests and produces pandasDataFrame objects.

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

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)

Template Credits

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