VitalDB Python Library

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]
[ nan nan]
...
[ 0.148893 -32.5087 ]
[ -0.325087 19.8266 ]
[ nan nan]]