Quick start

We will guide you through the main features of niimpy. This guide assumes that you have basic knowledge of Python. Also, please refers to the installation page for installing niimpy.

This guide provides an example of reading and handling Aware battery data. The tutorial will guide you through 4 basic steps of a data analysis pipeline:

  • Reading

  • Preprocessing

  • Visualization

  • Basic analysis

[1]:
# Setting up plotly environment
import plotly.io as pio
pio.renderers.default = "png"
[2]:
import numpy as np
import niimpy
from niimpy import config
from niimpy.exploration.eda import punchcard, missingness
from niimpy.preprocessing import battery
/u/24/rantahj1/unix/miniconda3/envs/niimpy/lib/python3.12/site-packages/tqdm/auto.py:21: TqdmWarning:

IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html

Reading

niimpy provides a simple function to read data from csv and sqlite database. We will read a csv file containing 1 month of battery data from an individual.

[3]:
df = niimpy.read_csv(config.MULTIUSER_AWARE_BATTERY_PATH, tz='Europe/Helsinki')
df.head()
[3]:
user device time battery_level battery_status battery_health battery_adaptor datetime
2020-01-09 02:20:02.924999952+02:00 jd9INuQ5BBlW 3p83yASkOb_B 1.578529e+09 74 3 2 0 2020-01-09 02:20:02.924999952+02:00
2020-01-09 02:21:30.405999899+02:00 jd9INuQ5BBlW 3p83yASkOb_B 1.578529e+09 73 3 2 0 2020-01-09 02:21:30.405999899+02:00
2020-01-09 02:24:12.805999994+02:00 jd9INuQ5BBlW 3p83yASkOb_B 1.578529e+09 72 3 2 0 2020-01-09 02:24:12.805999994+02:00
2020-01-09 02:35:38.561000109+02:00 jd9INuQ5BBlW 3p83yASkOb_B 1.578530e+09 72 2 2 0 2020-01-09 02:35:38.561000109+02:00
2020-01-09 02:35:38.953000069+02:00 jd9INuQ5BBlW 3p83yASkOb_B 1.578530e+09 72 2 2 2 2020-01-09 02:35:38.953000069+02:00

Preprocessing

There are various ways to handle battery data. For example, you can extract the gaps between consecutive battery timestamps.

[4]:
gaps = battery.battery_gaps(df)
gaps.head()
[4]:
user battery_gap device
2019-08-05 14:00:00+03:00 dvWdLQesv21a 0 days 00:00:00 i8jmoIuoe12Mo
2019-08-05 14:30:00+03:00 dvWdLQesv21a NaT i8jmoIuoe12Mo
2019-08-05 15:00:00+03:00 dvWdLQesv21a NaT i8jmoIuoe12Mo
2019-08-05 15:30:00+03:00 dvWdLQesv21a NaT i8jmoIuoe12Mo
2019-08-05 16:00:00+03:00 dvWdLQesv21a 0 days 02:18:38.523000002 i8jmoIuoe12Mo

niimpy can also extract the amount of battery data found within an interval.

[5]:
occurrences = battery.battery_occurrences(df, resample_args = {"rule": "1h"})
occurrences.head()
[5]:
user occurrences device
2019-08-05 14:00:00+03:00 dvWdLQesv21a 1 i8jmoIuoe12Mo
2019-08-05 15:00:00+03:00 dvWdLQesv21a 0 i8jmoIuoe12Mo
2019-08-05 16:00:00+03:00 dvWdLQesv21a 1 i8jmoIuoe12Mo
2019-08-05 17:00:00+03:00 dvWdLQesv21a 1 i8jmoIuoe12Mo
2019-08-05 18:00:00+03:00 dvWdLQesv21a 1 i8jmoIuoe12Mo

Visualization

niimpy provides a selection of visualization tools curated for exploring behavioural data. For example, you can examine the frenquency of battery level in specified interval.

[6]:
fig = missingness.bar_count(df, columns=['battery_level'], sampling_freq='min')
fig.show()
../_images/quick-start_10_0.png

In addition, you can analyze the battery level at each sampling interval by using a punchcard plot.

[7]:
fig = punchcard.punchcard_plot(df,
                                   user_list=['jd9INuQ5BBlW'],
                                   columns=['battery_status', 'battery_level'],
                                   resample='10min',
                                   title="Battery level")
fig.show()
../_images/quick-start_12_0.png

For more information, refer to the Exploration section.