import os
import numpy as np
import pandas as pd
from wfdb.io.annotation import format_ann_from_df, Annotation, wrann
from wfdb.io.record import Record, wrsamp
def csv_to_wfdb(
file_name,
fs,
units,
fmt=None,
adc_gain=None,
baseline=None,
samps_per_frame=None,
counter_freq=None,
base_counter=None,
base_time=None,
base_date=None,
comments=None,
sig_name=None,
dat_file_name=None,
skew=None,
byte_offset=None,
adc_res=None,
adc_zero=None,
init_value=None,
checksum=None,
block_size=None,
record_only=False,
header=True,
delimiter=",",
verbose=False,
):
"""
Read a WFDB header file and return either a `Record` object with the
record descriptors as attributes or write a record and header file.
Parameters
----------
file_name : str
The name of the WFDB record to be read, without any file
extensions. If the argument contains any path delimiter
characters, the argument will be interpreted as PATH/BASE_RECORD.
Both relative and absolute paths are accepted. If the `pn_dir`
parameter is set, this parameter should contain just the base
record name, and the files fill be searched for remotely.
Otherwise, the data files will be searched for in the local path.
fs : float
This number can be expressed in any format legal for a Python input of
floating point numbers (thus '360', '360.', '360.0', and '3.6e2' are
all legal and equivalent). The sampling frequency must be greater than 0;
if it is missing, a value of 250 is assumed.
units : list, str
This will be applied as the passed list unless a single str is passed
instead - in which case the str will be assigned for all channels.
This field can be present only if the ADC gain is also present. It
follows the baseline field if that field is present, or the gain field
if the baseline field is absent. The units field is a list of character
strings that specifies the type of physical unit. If the units field is
absent, the physical unit may be assumed to be 1 mV.
fmt : list, str, optional
This will be applied as the passed list unless a single str is passed
instead - in which case the str will be assigned for all
channels. A list of strings giving the WFDB format of each file used to
store each channel. Accepted formats are: '80','212','16','24', and
'32'. There are other WFDB formats as specified by:
https://www.physionet.org/physiotools/wag/signal-5.htm
but this library will not write (though it will read) those file types.
Each field is an integer that specifies the storage format of the signal.
All signals in a given group are stored in the same format. The most
common format is format `16` (sixteen-bit amplitudes). The parameters
`samps_per_frame`, `skew`, and `byte_offset` are optional fields, and
if present, are bound to the format field. In other words, they may be
considered as format modifiers, since they further describe the encoding
of samples within the signal file.
adc_gain : list, int, optional
This will be applied as the passed list unless a single int is passed
instead - in which case the int will be assigned for all channels.
This field is a list of numbers that specifies the difference in
sample values that would be observed if a step of one physical unit
occurred in the original analog signal. For ECGs, the gain is usually
roughly equal to the R-wave amplitude in a lead that is roughly parallel
to the mean cardiac electrical axis. If the gain is zero or missing, this
indicates that the signal amplitude is uncalibrated; in such cases, a
value of 200 ADC units per physical unit may be assumed.
baseline : list, int, optional
This will be applied as the passed list unless a single int is passed
instead - in which case the int will be assigned for all channels. This
field can be present only if the ADC gain is also present. It is not
separated by whitespace from the ADC gain field; rather, it is
surrounded by parentheses, which delimit it. The baseline is an integer
that specifies the sample value corresponding to 0 physical units. If
absent, the baseline is taken to be equal to the ADC zero. Note that
the baseline need not be a value within the ADC range; for example,
if the ADC input range corresponds to 200-300 degrees Kelvin, the
baseline is the (extended precision) value that would map to 0 degrees
Kelvin.
samps_per_frame : list, int, optional
This will be applied as the passed list unless a single int is passed
instead - in which case the int will be assigned for all channels.
Normally, all signals in a given record are sampled at the (base)
sampling frequency as specified by `fs`; in this case, the number of
samples per frame is 1 for all signals, and this field is conventionally
omitted. If the signal was sampled at some integer multiple, n, of the
base sampling frequency, however, each frame contains n samples of the
signal, and the value specified in this field is also n. (Note that
non-integer multiples of the base sampling frequency are not supported).
counter_freq : float, optional
This field (a floating-point number, in the same format as `fs`) can be
present only if `fs` is also present. Typically, the counter frequency
may be derived from an analog tape counter, or from page numbers in a
chart recording. If the counter frequency is absent or not positive,
it is assumed to be equal to `fs`.
base_counter : float, optional
This field can be present only if the counter frequency is also present.
The base counter value is a floating-point number that specifies the counter
value corresponding to sample 0. If absent, the base counter value is
taken to be 0.
base_time : datetime.time, optional
This field can be present only if the number of samples is also present.
It gives the time of day that corresponds to the beginning of the
record.
base_date : datetime.date, optional
This field can be present only if the base time is also present. It contains
the date that corresponds to the beginning of the record.
comments : list, optional
A list of string comments to be written to the header file. Each string
entry represents a new line to be appended to the bottom of the header
file ('.hea').
sig_name : list, optional
A list of strings giving the signal name of each signal channel. This
will be used for plotting the signal both in this package and
LightWave. Note, this value will be used in preference to the CSV
header, if applicable, to define custom signal names.
dat_file_name : str, optional
The name of the file in which samples of the signal are kept. Although the
record name is usually part of the signal file name, this convention is
not a requirement. Note that several signals can share the same file
(i.e., they can belong to the same signal group); all entries for signals
that share a given file must be consecutive, however. Note, the default
behavior is to save the files in the current working directory, not the
directory of the file being read.
skew : list, int, optional
This will be applied as the passed list unless a single int is passed
instead - in which case the int will be assigned for all channels.
Ideally, within a given record, samples of different signals with the
same sample number are simultaneous (within one sampling interval).
If this is not the case (as, for example, when a multitrack analog
tape recording is digitized and the azimuth of the playback head does
not match that of the recording head), the skew between signals can
sometimes be determined (for example, by locating recorded waveform
features with known time relationships, such as calibration signals).
If this has been done, the skew field may be inserted into the header
file to indicate the (positive) number of samples of the signal that
are considered to precede sample 0. These samples, if any, are included
in the checksum. (Note the checksum need not be changed if the skew field
is inserted or modified).
byte_offset : list, int, optional
This will be applied as the passed list unless a single int is passed
instead - in which case the int will be assigned for all channels.
Normally, signal files include only sample data. If a signal file
includes a preamble, however, this field specifies the offset in bytes
from the beginning of the signal file to sample 0 (i.e., the length
of the preamble). Data within the preamble is not included in the signal
checksum. Note that the byte offset must be the same for all signals
within a given group (use the skew field to correct for intersignal
skew). This feature is provided only to simplify the task of reading
signal files not generated using the WFDB library; the WFDB library
does not support any means of writing such files, and byte offsets must
be inserted into header files manually.
adc_res: list, int, optional
This will be applied as the passed list unless a single int is passed
instead - in which case the int will be assigned for all channels.
This field can be present only if the ADC gain is also present. It
specifies the resolution of the analog-to-digital converter used to
digitize the signal. Typical ADCs have resolutions between 8 and 16
bits. If this field is missing or zero, the default value is 12 bits
for amplitude-format signals, or 10 bits for difference-format signals
(unless a lower value is specified by the format field).
adc_zero: list, int, optional
This will be applied as the passed list unless a single int is passed
instead - in which case the int will be assigned for all channels.
This field can be present only if the ADC resolution is also present.
It is an integer that represents the amplitude (sample value) that
would be observed if the analog signal present at the ADC inputs had
a level that fell exactly in the middle of the input range of the ADC.
For a bipolar ADC, this value is usually zero, but a unipolar (offset
binary) ADC usually produces a non-zero value in the middle of its
range. Together with the ADC resolution, the contents of this field
can be used to determine the range of possible sample values. If this
field is missing, a value of 0 is assumed.
init_value : list, int, optional
This will be applied as the passed list unless a single int is passed
instead - in which case the int will be assigned for all channels.
This field can be present only if the ADC zero is also present. It
specifies the value of sample 0 in the signal, but is used only if the
signal is stored in difference format. If this field is missing, a
value equal to the ADC zero is assumed.
checksum : list, optional
This field can be present only if the initial value is also present. It
is a 16-bit signed checksum of all samples in the signal. (Thus the
checksum is independent of the storage format.) If the entire record
is read without skipping samples, and the header’s record line specifies
the correct number of samples per signal, this field is compared against
a computed checksum to verify that the signal file has not been corrupted.
A value of zero may be used as a field placeholder if the number of
samples is unspecified.
block_size : list, int, optional
This will be applied as the passed list unless a single int is passed
instead - in which case the int will be assigned for all channels.
This field can be present only if the checksum is present. This field
is an integer and is usually 0. If the signal is stored in a file
that must be read in blocks of a specific size, however, this field
specifies the block size in bytes. (On UNIX systems, this is the case
only for character special files, corresponding to certain tape and
raw disk files. If necessary, the block size may be given as a negative
number to indicate that the associated file lacks I/O driver support for
some operations.) All signals belonging to the same signal group have
the same block size.
record_only : bool, optional
Whether to only return the record information (True) or not (False).
If false, this function will generate both a .dat and .hea file.
header : bool, optional
Whether to assume the CSV has a first line header (True) or not (False)
which defines the signal names. If false, this function will generate
either the signal names provided by `sig_name` or set `[ch_1, ch_2, ...]`
as the default.
delimiter : str, optional
What to use as the delimiter for the file to separate data. The default
if a comma (','). Other common delimiters are tabs ('\t'), spaces (' '),
pipes ('|'), and colons (':').
verbose : bool, optional
Whether to print all the information read about the file (True) or
not (False).
Returns
-------
record : Record or MultiRecord, optional
The WFDB Record or MultiRecord object representing the contents
of the CSV file read.
Notes
-----
CSVs should be in the following format:
sig_1_name,sig_2_name,...
sig_1_val_1,sig_2_val_1,...
sig_1_val_2,sig_2_val_2,...
...,...,...
Or this format if `header=False` is defined:
sig_1_val_1,sig_2_val_1,...
sig_1_val_2,sig_2_val_2,...
...,...,...
The signal will be saved defaultly as a `p_signal` so both floats and
ints are acceptable.
Examples
--------
Create the header ('.hea') and record ('.dat') files, specifies both
units to be 'mV'
>>> csv_to_wfdb('sample-data/100.csv', fs=360, units='mV')
Create the header ('.hea') and record ('.dat') files, change units for
each signal
>>> csv_to_wfdb('sample-data/100.csv', fs=360, units=['mV','kV'])
Return just the record, note the use of lists to specify which values should
be applied to each signal
>>> csv_record = csv_to_wfdb('sample-data/100.csv', fs=360, units=['mV','mV'],
fmt=['80',212'], adc_gain=[100,200],
baseline=[1024,512], record_only=True)
Return just the record, note the use of single strings and ints to specify
when fields can be applied to all signals
>>> csv_record = csv_to_wfdb('sample-data/100.csv', fs=360, units='mV',
fmt=['80','212'], adc_gain=200, baseline=1024,
record_only=True)
"""
# NOTE: No need to write input checks here since the Record class should
# handle them (except verifying the CSV input format which is for Pandas)
if header:
df_CSV = pd.read_csv(file_name, delimiter=delimiter)
else:
df_CSV = pd.read_csv(file_name, delimiter=delimiter, header=None)
if verbose:
print("Successfully read CSV")
# Extract the entire signal from the dataframe
p_signal = df_CSV.values
# The dataframe should be in (`sig_len`, `n_sig`) dimensions
sig_len = p_signal.shape[0]
if verbose:
print("Signal length: {}".format(sig_len))
n_sig = p_signal.shape[1]
if verbose:
print("Number of signals: {}".format(n_sig))
# Check if signal names are valid and set defaults
if not sig_name:
if header:
sig_name = df_CSV.columns.to_list()
if any(map(str.isdigit, sig_name)):
print(
"WARNING: One or more of your signal names are numbers, this "
"is not recommended:\n- Does your CSV have a header line "
"which defines the signal names?\n- If not, please set the "
"parameter 'header' to False.\nSignal names: {}".format(
sig_name
)
)
else:
sig_name = ["ch_" + str(i) for i in range(n_sig)]
if verbose:
print("Signal names: {}".format(sig_name))
# Set the output header file name to be the same, remove path
if os.sep in file_name:
file_name = file_name.split(os.sep)[-1]
record_name = file_name.replace(".csv", "")
if verbose:
print("Output header: {}.hea".format(record_name))
# Replace the CSV file tag with DAT
dat_file_name = file_name.replace(".csv", ".dat")
dat_file_name = [dat_file_name] * n_sig
if verbose:
print("Output record: {}".format(dat_file_name[0]))
# Convert `units` from string to list if necessary
units = [units] * n_sig if type(units) is str else units
# Set the default `fmt` if none exists
if not fmt:
fmt = ["16"] * n_sig
fmt = [fmt] * n_sig if type(fmt) is str else fmt
if verbose:
print("Signal format: {}".format(fmt))
# Set the default `adc_gain` if none exists
if not adc_gain:
adc_gain = [200] * n_sig
adc_gain = [adc_gain] * n_sig if type(adc_gain) is int else adc_gain
if verbose:
print("Signal ADC gain: {}".format(adc_gain))
# Set the default `baseline` if none exists
if not baseline:
if adc_zero:
baseline = [adc_zero] * n_sig
else:
baseline = [0] * n_sig
baseline = [baseline] * n_sig if type(baseline) is int else baseline
if verbose:
print("Signal baseline: {}".format(baseline))
# Convert `samps_per_frame` from int to list if necessary
samps_per_frame = (
[samps_per_frame] * n_sig
if type(samps_per_frame) is int
else samps_per_frame
)
# Convert `skew` from int to list if necessary
skew = [skew] * n_sig if type(skew) is int else skew
# Convert `byte_offset` from int to list if necessary
byte_offset = (
[byte_offset] * n_sig if type(byte_offset) is int else byte_offset
)
# Set the default `adc_res` if none exists
if not adc_res:
adc_res = [12] * n_sig
adc_res = [adc_res] * n_sig if type(adc_res) is int else adc_res
if verbose:
print("Signal ADC resolution: {}".format(adc_res))
# Set the default `adc_zero` if none exists
if not adc_zero:
adc_zero = [0] * n_sig
adc_zero = [adc_zero] * n_sig if type(adc_zero) is int else adc_zero
if verbose:
print("Signal ADC zero: {}".format(adc_zero))
# Set the default `init_value`
# NOTE: Initial value (and subsequently the digital signal) won't be correct
# unless the correct `baseline` and `adc_gain` are provided... this is just
# the best approximation
if not init_value:
init_value = p_signal[0, :]
init_value = baseline + (np.array(adc_gain) * init_value)
init_value = [int(i) for i in init_value.tolist()]
if verbose:
print("Signal initial value: {}".format(init_value))
# Set the default `checksum`
if not checksum:
checksum = [int(np.sum(v) % 65536) for v in np.transpose(p_signal)]
if verbose:
print("Signal checksum: {}".format(checksum))
# Set the default `block_size`
if not block_size:
block_size = [0] * n_sig
block_size = [block_size] * n_sig if type(block_size) is int else block_size
if verbose:
print("Signal block size: {}".format(block_size))
# Convert array to floating point
p_signal = p_signal.astype("float64")
# Either return the record or generate the record and header files
# if requested
if record_only:
# Create the record from the input and generated values
record = Record(
record_name=record_name,
n_sig=n_sig,
fs=fs,
samps_per_frame=samps_per_frame,
counter_freq=counter_freq,
base_counter=base_counter,
sig_len=sig_len,
base_time=base_time,
base_date=base_date,
comments=comments,
sig_name=sig_name,
p_signal=p_signal,
d_signal=None,
e_p_signal=None,
e_d_signal=None,
file_name=dat_file_name,
fmt=fmt,
skew=skew,
byte_offset=byte_offset,
adc_gain=adc_gain,
baseline=baseline,
units=units,
adc_res=adc_res,
adc_zero=adc_zero,
init_value=init_value,
checksum=checksum,
block_size=block_size,
)
if verbose:
print("Record generated successfully")
return record
else:
# Write the information to a record and header file
wrsamp(
record_name=record_name,
fs=fs,
units=units,
sig_name=sig_name,
p_signal=p_signal,
fmt=fmt,
adc_gain=adc_gain,
baseline=baseline,
comments=comments,
base_time=base_time,
base_date=base_date,
)
if verbose:
print("File generated successfully")
def csv2ann(
file_name,
extension="atr",
fs=None,
record_only=False,
time_onset=True,
header=True,
delimiter=",",
verbose=False,
):
"""
Read a CSV/TSV/etc. file and return either an `Annotation` object with the
annotation descriptors as attributes or write an annotation file.
Parameters
----------
file_name : str
The name of the CSV file to be read, including the '.csv' file
extension. If the argument contains any path delimiter characters, the
argument will be interpreted as PATH/BASE_RECORD. Both relative and
absolute paths are accepted. The BASE_RECORD file name will be used to
name the annotation file with the desired extension.
extension : str, optional
The string annotation file extension.
fs : float, optional
This will be used if annotation onsets are given in the format of time
(`time_onset` = True) instead of sample since onsets must be sample
numbers in order for `wrann` to work. This number can be expressed in
any format legal for a Python input of floating point numbers (thus
'360', '360.', '360.0', and '3.6e2' are all legal and equivalent). The
sampling frequency must be greater than 0; if it is missing, a value
of 250 is assumed.
record_only : bool, optional
Whether to only return the record information (True) or not (False).
If false, this function will generate the annotation file.
time_onset : bool, optional
Whether to assume the values provided in the 'onset' column are in
units of time (True) or samples (False). If True, convert the onset
times to samples by using the, now required, `fs` input.
header : bool, optional
Whether to assume the CSV has a first line header (True) or not
(False) which defines the signal names.
delimiter : str, optional
What to use as the delimiter for the file to separate data. The default
if a comma (','). Other common delimiters are tabs ('\t'), spaces (' '),
pipes ('|'), and colons (':').
verbose : bool, optional
Whether to print all the information read about the file (True) or
not (False).
Returns
-------
N/A : Annotation, optional
The WFDB Annotation object representing the contents of the CSV file
read.
Notes
-----
CSVs should be in one of the two possible following format:
1) All events are single time events (no duration).
onset,description
onset_1,description_1
onset_2,description_2
...,...
Or this format if `header=False` is defined:
onset_1,description_1
onset_2,description_2
...,...
2) A duration is specified for some events.
onset,duration,description
onset_1,duration_1,description_1
onset_2,duration_2,description_2
...,...,...
Or this format if `header=False` is defined:
onset_1,duration_1,description_1
onset_2,duration_2,description_2
...,...,...
By default, the 'onset' will be interpreted as a sample number if it is
strictly in integer format and as a time otherwise. By default, the
'duration' will be interpreted as time values and not elapsed samples. By
default, the 'description' will be interpreted as the `aux_note` for the
annotation and the `symbol` will automatically be set to " which defines a
comment. Future additions will allow the user to customize such
attributes.
Examples
--------
1) Write WFDB annotation file from CSV with time onsets:
======= start example.csv =======
onset,description
0.2,p-wave
0.8,qrs
======== end example.csv ========
>>> wfdb.csv2ann('example.csv', fs=360)
* Creates a WFDB annotation file called: 'example.atr'
2) Write WFDB annotation file from CSV with sample onsets:
======= start example.csv =======
onset,description
5,p-wave
13,qrs
======== end example.csv ========
>>> wfdb.csv2ann('example.csv', fs=10, time_onset=False)
* Creates a WFDB annotation file called: 'example.atr'
* 5,13 samples -> 0.5,1.3 seconds for onset
3) Write WFDB annotation file from CSV with time onsets, durations, and no
header:
======= start example.csv =======
0.2,0.1,qrs
0.8,0.4,qrs
======== end example.csv ========
>>> wfdb.csv2ann('example.csv', extension='qrs', fs=360, header=False)
* Creates a WFDB annotation file called: 'example.qrs'
"""
# NOTE: No need to write input checks here since the Annotation class
# should handle them (except verifying the CSV input format which is for
# Pandas)
if header:
df_CSV = pd.read_csv(file_name, delimiter=delimiter)
else:
df_CSV = pd.read_csv(file_name, delimiter=delimiter, header=None)
if verbose:
print("Successfully read CSV")
if verbose:
print("Creating Pandas dataframe from CSV")
if df_CSV.shape[1] == 2:
if verbose:
print("onset,description format detected")
if not header:
df_CSV.columns = ["onset", "description"]
df_out = df_CSV
elif df_CSV.shape[1] == 3:
if verbose:
print("onset,duration,description format detected")
print("Converting durations to single time-point events")
if not header:
df_CSV.columns = ["onset", "duration", "description"]
df_out = format_ann_from_df(df_CSV)
else:
raise Exception(
"""The number of columns in the CSV was not
recognized."""
)
# Remove extension from input file name
file_name = file_name.split(".")[0]
if time_onset:
if not fs:
raise Exception(
"""`fs` must be provided if `time_onset` is True
since it is required to convert time onsets to
samples"""
)
sample = (df_out["onset"].to_numpy() * fs).astype(np.int64)
else:
sample = df_out["onset"].to_numpy()
# Assume each annotation is a comment
symbol = ['"'] * len(df_out.index)
subtype = np.array([22] * len(df_out.index))
# Assume each annotation belongs with the 1st channel
chan = np.array([0] * len(df_out.index))
num = np.array([0] * len(df_out.index))
aux_note = df_out["description"].tolist()
if verbose:
print("Finished CSV parsing... writing to Annotation object")
if record_only:
if verbose:
print("Finished creating Annotation object")
return Annotation(
record_name=file_name,
extension=extension,
sample=sample,
symbol=symbol,
subtype=subtype,
chan=chan,
num=num,
aux_note=aux_note,
fs=fs,
)
else:
wrann(
file_name,
extension,
sample=sample,
symbol=symbol,
subtype=subtype,
chan=chan,
num=num,
aux_note=aux_note,
fs=fs,
)
if verbose:
print("Finished writing Annotation file")