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]]