Introduction

This document explains the VitalDB python library which helps the use of Vital file format and VitalDB data in Python language.

Installation

VitalDB Python Library can be installed using the package installer for python (PIP).

$ pip install vitaldb

And then you need to import the vitaldb library.

import vitaldb

Vital File API

You can read a track list from a vital file using vital_trks function.

vitaldb.vital_trks(ipath)

Parameter list

ipath: vital file path to read

Return value

list of track names in the vital file

You can read the samples(values) in a vital file using vital_recs function. It returns the samples in a numpy array.

vitaldb.vital_recs(ipath, track_names=None, interval=None, return_timestamp=False, return_datetime=False, return_pandas=False, exclude=None)

Parameter list

ipath: vital file path to read
track_names: list of track names, eg) ['SNUADC/ECG', 'Solar 8000/HR']
interval: interval of each sample. if None, maximum resolution. if there is no wave tracks, 1 sec
return_timestamp: return unix timestamp
return_datetime: return datetime of each sample at first column
return_pandas: return pandas dataframe

Return value

numpy array of samples that have the same interval specified by the input argument.

The library contains a VitalFile class to read and write Vital File Format.

vitaldb.VitalFile(ipath, track_names=None, header_only=False, skip_records=None, exclude=None, userid=None, maxlen=None, interval=None)

Parameter list

ipath:
- caseid: caseid of open dataset
- path: file path
- list: list of file path to merge files
track_names: list or comma separated track names (with device names). If missing, all tracks are loaded.
header_only / skip_records: read track information only if True. Othersize, all track data (default).
- True: read track names only
exclude: list or comma separated track names (with device names)
userid: user ID if vitaldb.net when downloading a vital file or parquet file from the cloud
maxlen: set max length of a VitalFile in seconds
interval: interval of each sample. if None, maximum resolution. if there is no wave tracks, 1 sec

Return value

VitalFile object

Sample Code

The following example code downloads a vital file with caseid of 1 to the current working directory.

vf = vitaldb.VitalFile(1)

vf.to_vital('1.vital')

Results:

You can open and visualize the downloaded vital file using the Vital Recorder.

The next sample code downloads the SNUADC/ECG_II track only. It is faster than the former example.

import vitaldb

vf = vitaldb.VitalFile(1, ['SNUADC/ECG_II'])

vf.to_vital('1.vital')

Results:

vitaldb.read_vital(ipath, track_names=None, exclude=None, header_only=False, maxlen=None)

Parameter list

ipath: vital file path to read
track_names: list of track names, eg) ['SNUADC/ECG', 'Solar 8000/HR']
exclude: list or comma separated track names (with device names)
header_only: read track information only if True.
maxlen: set max length of a VitalFile in seconds.

Return value

VitalFile object read from .vital file

vitaldb.read_csv(ipath, track_names=None, exclude=None, interval=None)

Parameter list

ipath: vital file path to read
track_names: list of track names, eg) ['SNUADC/ECG', 'Solar 8000/HR']
exclude: list or comma separated track names (with device names)
interval: interval of each sample. if None, maximum resolution. if there is no wave tracks, 1 sec

Return value

VitalFile object read from .csv file

vitaldb.read_wfdb(ipath, track_names=None, exclude=None, header_only=False)

Parameter list

ipath: vital file path to read
track_names: list of track names, eg) ['SNUADC/ECG', 'Solar 8000/HR']
exclude: list or comma separated track names (with device names)
header_only:read track information only if True.

Return value

VitalFile object read from .csv.gz file, written in waveform-database format

vitaldb.read_parquet(ipath, track_names=None, exclude=None)

Parameter list

ipath: vital file path to read
track_names: list of track names, eg) ['SNUADC/ECG', 'Solar 8000/HR']
exclude: list or comma separated track names (with device names)

Return value

VitalFile object read from .parquet file

After loading the vital file, you can convert it to pandas or numpy format for data analysis.

vitaldb.VitalFile.to_numpy(track_names, interval, return_datetime=False, return_timestamp=False)

Parameter list

track_names: list or comma separated track names (with device names)
interval: time interval of each row
return_datetime: add time in datetime format to each record
return_timestamp: add time in timestamp format to each record

Sample Code

The following code downloads arterial waveform from the first case of open dataset and show.

import vitaldb

import matplotlib.pyplot as plt

track_names = ['SNUADC/ART']

vf = vitaldb.VitalFile(1, track_names)

samples = vf.to_numpy(track_names, 1/100)

plt.figure(figsize=(20, 5))

plt.plot(samples[:, 0])

plt.show()

vitaldb.VitalFile.to_pandas(track_names, interval, return_datetime=False, return_timestamp=False)

Parameter list

track_names: list or comma separated track names (with device names)
interval: time interval of each row
return_datetime: add time in datetime format to each record
return_timestamp: add time in timestamp format to each record

You can save the vital files in several formats.

vitaldb.VitalFile.to_vital(opath, compresslevel=1)

Save as vital file

Parameter list

opath: file path to save

vitaldb.VitalFile.to_csv(opath, track_names, interval, return_datetime=False, return_timestamp=False)

Save as csv file

Parameter list

opath: file path to save
track_names: list of track names
interval: time interval of each row
return_datetime: add time in datetime format to each record
return_timestamp: add time in timestamp format to each record

vitaldb.VitalFile.to_wfdb(opath, track_names=None, interval=None)

Save as waveform-database file

Parameter list

opath: file path to save
track_names: list of track names
interval: time interval of each row

vitaldb.VitalFile.to_wav(opath, track_names, srate=None)

Save as wave file

Parameter list

opath: file path to save
track_names: list of track names
srate: sample frequency

vitaldb.VitalFile.to_parquet(opath)

Save as parquet file

Parameter list

opath: file path to save

There are other functions for using and editing VitalFile.

vitaldb.VitalFile.crop(dtfrom=None, dtend=None)

Cut the vital file to the desired time

Parameter list

dtfrom: start time in unix timestamp format
dtend: end time in unix timestamp format

vitaldb.VitalFile.get_track_names()

Return only the track names contained in the vital file

vitaldb.VitalFile.get_track_samples(dtname, interval)

Get samples of each track

Parameter list

* dtname: list or comma separated track names (with device names)
* interval: interval of samples in sec. if None, maximum resolution. if no resolution, 1/500

vitaldb.VitalFile.remove_track(dtname)

Delete track by name

Parameter list

dtname: device and track name

vitaldb.VitalFile.add_track(dtname, recs, srate=0, unit=’’, mindisp=0, maxdisp=0)

Parameter list

dtname: device and track name
recs: list or comma separated dictionary with ‘val’ and ‘dt’ as key
srate: If wave track, Hz of float type
unit: unit of string type
mindisp: minimum value
maxdisp: maximum value

vitaldb.VitalFile.find_track(dtname)

Find track from name

Parameter list

dtname: device and track name

Platform API

You can access the vital files from cloud storage or intranet server with the api module.

vitaldb.login(id, pw, host=None, port=None)

Use the setserver function above to set the site with given host and port

Parameter list

id: id to login
pw: pw to login
host: IP address (default value: vitaldb.net)
port: string type of port number

vitaldb.filelist(bedname=None, dtstart=None, dtend=None)

request file list

Parameter list

bedname: bed name and bed number connected with “_”
dtstart: start time in “Y-m-d h:m:s” format
dtend: end time in “Y-m-d h:m:s” format

vitaldb.download(filename, localpath=None)

Request file download

Parameter list

filename: file name to download(‘0000_00_000000_000000.vital’)
localpath: local path to download

Sample code

The following sample code downloads all vital files with bedname and periods.

import vitaldb

import pandas as pd

import os

# path to save downloaded files

DOWNLOAD_DIR = "Download"

SERVER_IP = 'xxx.xx.xxx.xxx'

SERVER_PORT = '80'

LOGIN_ID = '' # Please enter your login id

LOGIN_PW = '' # Please enter your login password

BED_NAME = "MICU"

START_DATE = "2022-01-01"

END_DATE = "2022-01-31"

if vitaldb.login(LOGIN_ID, LOGIN_PW, SERVER_IP, SERVER_PORT): # login

# check filelist

filelist = vitaldb.filelist(bedname=BED_NAME, dtstart=START_DATE, dtend=END_DATE)

print(pd.DataFrame(filelist))

if not os.path.exists(DOWNLOAD_DIR):

os.mkdir(DOWNLOAD_DIR)

# files load & download

for file in filelist:

print('downloading ' + file['filename'], end='...')

localpath = DOWNLOAD_DIR + '/' + file['filename']

res = vitaldb.download(file['filename'], localpath)

print('done')

else:

print('login error')

Dataset API

You can use vitaldb open datasets with vitaldb python library.

Find cases in the VitalDB open dataset

caseids = vitaldb.find_cases(['ECG_II', 'ART'])

len(caseids)

Results: 3644

Read an open dataset case

vals = vitaldb.load_case(caseids[0], ['ECG_II','ART'], 1/100)

print(vals)

ecg = vals[:,0]

art = vals[:,1]

# plot

import matplotlib.pyplot as plt

plt.figure(figsize=(20,10))

plt.subplot(211)

plt.plot(ecg[110000:111000], color='g')

plt.subplot(212)

plt.plot(art[110000:111000], color='r')

plt.show()

Results:

[[ nan nan]

[ nan nan]

...

[ 0.148893 -32.5087 ]

[ -0.325087 19.8266 ]

[ nan nan]]