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

# Setting up plotly environment
import plotly.io as pio
pio.renderers.default = "png"

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.

df = niimpy.read_csv(config.MULTIUSER_AWARE_BATTERY_PATH, tz='Europe/Helsinki')
df.head()

	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.

gaps = battery.battery_gaps(df)
gaps.head()

	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.

occurrences = battery.battery_occurrences(df, resample_args = {"rule": "1h"})
occurrences.head()

	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.

fig = missingness.bar_count(df, columns=['battery_level'], sampling_freq='min')
fig.show()

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

fig = punchcard.punchcard_plot(df,
                                   user_list=['jd9INuQ5BBlW'],
                                   columns=['battery_status', 'battery_level'],
                                   resample='10min',
                                   title="Battery level")
fig.show()

For more information, refer to the Exploration section.