How-To Use Python Lib for Datasets

This guide explains how to set up a Python environment for the BI-Vital library, prepare measurement data, and create a BI-Vital project with bvtool.
No prior Python knowledge is required.

🎥 Prefer video? Watch the tutorial here — the same steps are explained in detail below.

Open video on YouTube (starts at 2:20)

1. Install a Python environment manager

A dedicated Python environment ensures a clean and reproducible setup.

Miniconda is a lightweight tool for managing Python versions and environments.

  1. Download Miniconda: https://www.anaconda.com/download
  2. Choose the installer for Windows, macOS, or Linux
  3. Install it

Windows note: You may use the Miniconda Prompt instead of adding Miniconda to PATH.

Other environment systems are also possible:

  • venv (built-in)
  • pyenv + venv
  • mamba / micromamba

This tutorial uses Miniconda.

2. Open a terminal

From now on, always use a terminal:

  • Windows: Miniconda Prompt
  • macOS / Linux: system terminal

3. Create a Miniconda environment

Create an environment named BI_Vital_Tutorial:

conda create -n BI_Vital_Tutorial python=3.12
conda activate BI_Vital_Tutorial

4. Ensure pip is available

Check:

pip --version

If missing:

conda install pip

5. Install the BI-Vital Python library

Install BI-Vital with notebook extras:

pip install "bivital[notebook]"

Installation instructions are also available in the
BI-Vital Python Library README.

6. Prepare BI-Vital measurement data (.csv)

BI-Vital recordings must be available as CSV files.

Ways to download/export:

  • Via USB from the BI-Vital sensor within the Web Toolbox

Save these CSV files locally. You will import them into your project.

7. Create a BI-Vital project using bvtool

bvtool organizes your data into:

  • Project → the main container
  • Series → measurement sessions (e.g. Day1, Day2…)
  • Data → your .csv recording files
  • Labels (optional) → exported from the smartphone LinkHub/App

Make sure BI-Vital is installed and your environment is active:

bvtool -h

7.1 Create a project 

bvtool project

You will:

  1. Choose where the new project folder should be created
  2. Enter a project name (e.g., Bi_Vital_Tutorial)

7.2 Create a series 

bvtool series

You will:

  1. Select the project folder
  2. Enter a series name (e.g., Day1)

A series represents one measurement day or session.

7.3 Add measurement data 

bvtool data

Steps:

  1. Select the series folder
  2. Choose the .csv file (either from PC or directly from a USB-C connected BI-Vital device)
  3. Optionally add multiple files or press Quit in the dialog

The selected files will be copied into the series folder.

7.4 Add label data (optional)

If you exported labels from the smartphone using the LinkHub Tool:

bvtool label

Steps:

  1. Select the series folder
  2. Choose the exported label file

This step is optional.

Use bvtool without UI dialogs

This mode is only recommended for advanced users who prefer terminal-only workflows:

bvtool -h
bvtool project -p PATH -n NAME
bvtool series  -p PATH -n NAME
bvtool data    -p PATH -s pc
bvtool label   -p PATH

Example:

bvtool project -p "C:/.../BI_Vital_Projects" -n "Bi_Vital_Tutorial"
bvtool series  -p "C:/.../BI_Vital_Projects/Bi_Vital_Tutorial" -n "Day1"
bvtool data    -p "C:/.../BI_Vital_Projects/Bi_Vital_Tutorial/Day1" -s pc

8. Test your setup with the example notebook

Start the examples:

bvtool example

When prompted, choose basic_example by typing:

0

and pressing Enter.

If a Jupyter Notebook error appears, install it and try again to open the exmaple:

conda install jupyterlab

8.1 Configure the notebook

Switch from example data to your own:

Data_to_use = 1

Set your project directory:

project_directory = "/path/to/your/BI_Vital_Project"
# macOS/Linux example: "/home/you/Documents/BI_Vital_Projects/Bi_Vital_Tutorial"
# Windows example:     "C:/Users/you/Documents/BI_Vital_Projects/Bi_Vital_Tutorial"

Run the cell and continue through the notebook.

You are now ready to process BI-Vital measurement data using Python.