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()

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()

For more information, refer to the Exploration section.