jointly readme
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 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
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:
Template Credits
This package was created with Cookiecutter and the pyOpenSci/cookiecutter-pyopensci project template, based off audreyr/cookiecutter-pypackage.