Recent Changes¶
This page lists recent changes in the wfdb package (since version 4.0.0) that may be relevant if you are upgrading from an older version of the package. For the complete history of changes in the package, please refer to the development repository on GitHub.
Version 5.0.0 (Nov 2026)¶
This release adds .wfdb archive support and requires Python 3.11 or newer.
ann2rr now uses only beat annotations by default and selects intervals by
their ending times in the record. Pass all_annotations=True to include
non-beat annotations. See the entries below for details.
- Fix writing channels that are entirely NaN
wrsampandcalc_adc_paramsno longer fail withcannot convert float NaN to integerwhen a channel contains only NaN values, and no longer emit an “All-NaN slice encountered” warning for such channels.- Reject negative infinity in expanded signals
calc_adc_paramsnow raises “Signal contains inf” whene_p_signalcontains-inf, as it already did forp_signal, instead of failing withcannot convert float NaN to integer.- Return 0 from calc_mean_hr when all intervals are filtered out
calc_mean_hrnow returns 0 whenmin_rrormax_rrremoves every R-R interval, as it does for empty input. It used to returnnanwith a “Mean of empty slice” warning.- Accept lists in calc_mean_hr with min_rr or max_rr
calc_mean_hrnow accepts R-R intervals as a list whenmin_rrormax_rris given. It used to raise aTypeError.- Allow empty annotations in compare_annotations
compare_annotations(Comparitor.compare) no longer fails when the reference or test annotations are empty, for example when a detector finds no beats. The sensitivity or positive predictivity that cannot be computed is NaN.- Fix test annotations matched twice in compare_annotations
compare_annotations(Comparitor.compare) could match one test annotation to two reference annotations, which gave a negative number of false positives and a positive predictivity above 1. Each test annotation is now matched at most once. Results are unchanged when no annotation was matched twice.- Check that QRS indices are increasing in compute_hr
compute_hrnow raises aValueErrorifqrs_indsis not strictly increasing. Repeated beats used to give aZeroDivisionError(orinffor NumPy arrays), and beats out of order gave a negative heart rate.- Use the last RR interval in compute_hr
compute_hrnow uses the interval between the last two beats for the heart rate after the last beat, instead of repeating the previous rate. With exactly two beats it now returns their rate after the second beat instead of only NaN.- Fix correct_peaks for peaks near the start of the signal
correct_peaksno longer moves peaks withinsearch_radiussamples of the start of the signal to the wrong place, often before the start (for example-6instead of0). The offset for these peaks was subtracted instead of added.- Fix search window in correct_peaks
correct_peaksnow searchessearch_radiussamples on both sides of each peak, including the last sample of the signal. It used to stop one sample short on the right, so a peak exactlysearch_radiussamples after the original index, or on the last sample, could not be found.- Fix parameter handling in csv_to_wfdb
csv_to_wfdbnow builds the sameRecordwhether it writes files or returns the record (record_only=True), so all header parameters (such asdat_file_name,counter_freq,base_counter,skew,byte_offset,adc_resandadc_zero) are written instead of being ignored. Single values of any numeric type (including NumPy scalars and floats) are used for all channels, and an explicit0is no longer replaced by the default. The initial value and checksum are computed from the digital samples, and the default ADC resolution now followsfmtin both modes. Thesamps_per_frame,init_valueandchecksumarguments are deprecated and ignored. The parameter descriptions in the docstring have been corrected.- Reduce memory use when writing format 16, 24 and 32 signals
wrsampandwr_dat_filenow convert signals in formats 16, 24 and 32 to bytes directly, instead of splitting every sample into separate byte arrays. For a 4-hour, 8-channel record at 500 Hz, the peak memory used to pack a format 16 signal drops from about 2 GB to 110 MB, and packing is about 13 times faster. The written files are unchanged.- Drop support for Python 3.9 and 3.10
The minimum supported Python version is now 3.11. The package is now also tested with Python 3.14 and 3.15.
- Include the right edge of the window in find_local_peaks
find_local_peaksnow compares each sample withradiussamples on both sides, as documented, and is about 3 times faster. The sampleradiuspositions to the right, and the last sample of the signal, used to be left out.XQRSusesfind_local_peaksto find candidate peaks, so its detections may change slightly.- Read units containing any non-whitespace characters
Header files with units containing characters such as
.or*(for examplea.u.oruV*s) are now read correctly. The units used to be cut off at the first such character, and the rest of the signal line (ADC resolution, ADC zero and so on) ended up in the signal name.- Read records from memory
rdrecord,rdsampandrdheadernow acceptmemory://URIs, which read from the in-memory filesystem offsspec, asrdannalready did. This also makes cloud URIs work for signal files and multi-segment records on Windows, where the file paths used to be built with backslashes.- Raise minimum versions of dependencies
The minimum versions of
soundfile(0.12.1),matplotlib(3.8.0) andrequests(2.31.0) have been raised. The minimum versions of the other dependencies are unchanged.- Write variable layout multi-segment records
MultiRecord.wrsampcan now write variable layout multi-segment records, such as those read withrdrecord(..., m2s=False). Previously, writing the layout header failed because its signals have no samples (format0, file name~).- Validate multi-segment record writes
MultiRecord.wrsampnow checks the segment lengths and sampling frequencies of all segments before writing any files, instead of writing a segment whose length does not matchseg_len.- Plot annotations outside the signal
plot_itemsandplot_wfdbno longer fail with anIndexErrorwhen an annotation is after the end of the signal, and no longer draw annotations before the start of the signal at values from its end. These annotations are now drawn at zero, as for channels without a signal, with a warning suggestingshift_samps=Trueinrdann.- Raise errors when rdann reads fs from the header
When an annotation file doesn’t store the sampling frequency,
rdannreads it from the record’s header. It used to ignore any error from that, for example when the header couldn’t be downloaded from PhysioNet, and return the annotation withfsset toNone. Now only a missing header is ignored, and other errors are raised.- Accept pathlib.Path record names in rdann
rdannnow accepts apathlib.Path(or other path-like object) asrecord_name, asrdrecord,rdsampandrdheaderalready do. It used to fail withTypeError: unsupported operand type(s) for +.- Speed up reading annotation files
rdannnow decodes annotation files using plain Python integers instead of indexing a NumPy array one byte at a time. Reading annotations is about 2 to 3 times faster (a 100,000-beat file now takes about 75 ms instead of 175). The annotations read are unchanged.- Fix rdedfann for EDF+ annotations
rdedfannno longer passes obsolete options toread_edfand can read EDF+ annotations again.- Read remote FLAC files with fewer requests
Remote files read in small pieces, such as FLAC signal files on PhysioNet, now use larger requests as reading goes on (up to 8 MB) instead of one request for every 32 kB. Reading a 7.4 MB MIMIC-IV signal file now takes 8 requests instead of 229, which saves several minutes per file.
- Add timeouts to requests for remote files
Requests for files on PhysioNet (and other web servers) now time out if the server does not respond (10 seconds to connect, and 60 seconds to wait for data), instead of waiting indefinitely. A
requests.exceptions.Timeout(ConnectTimeoutorReadTimeout) is raised in this case.- Fix resample_sig for signals starting with NaN
resample_sig(and the functions that use it, such asresample_singlechanandresample_multichan) returned only NaN values if the signal started with NaN. Leading NaN values now take the first valid value before resampling, as trailing ones already took the last.- Keep missing values missing in resample_sig
resample_sig(andresample_singlechanandresample_multichan) now return NaN for output samples with a NaN input value within half an output sample spacing (or within one input sample, when upsampling). NaN values are still filled before resampling, so the rest of the signal is unaffected, but the filled values are no longer returned as if they were real data.- Use Ruff for formatting and linting
The
devextra now includesruffinstead ofblackandpylint, and the code is formatted with a line length of 88 (the default).- Speed up the digital range check when writing records
wrsampnow uses NumPy to check that digital samples are within the range of each format, instead of Python’s built-inminandmax. Writing a 4-hour, 8-channel record at 500 Hz in format 16 now takes about 0.5 seconds instead of 3. The written files are unchanged.- Clarify smooth_frames behavior
The
rdrecorddocumentation now explains thatsmooth_framescontrols the output structure even when every channel has one sample per frame.- Fix smoothing of frames with invalid samples
When a signal with more than one sample per frame is read with
smooth_frames=True(the default), a frame that contains an invalid sample now gives an invalid value (NaN in physical units), as in the WFDB library. The invalid sample value used to be averaged with the other samples, which gave a large but valid-looking value.- Fix drifting timestamps in to_dataframe
Record.to_dataframenow computes the timestamp of each sample directly. Previously the sample interval was truncated to whole nanoseconds and added up, so for sampling frequencies such as 360 Hz or 62.4725 Hz the timestamps drifted by up to about a millisecond over a long record. The index no longer has afreqattribute.- Build with uv_build
The package is now built with
uv_buildinstead ofhatchling. The version number is specified inpyproject.tomlonly, andwfdb.__version__is read from the installed package metadata (it is"unknown"if the package is run from a source tree without being installed).- Read and write .wfdb archive files
A record can be stored in a single
.wfdbarchive file (a ZIP file containing the header and signal files).rdrecord,rdsamp,rdheaderandrdannread a record or its annotations from an archive when given the path of the archive, andwrsampwrites a record into an archive with the newwfdb_archiveargument. Multi-segment records are supported, with all their segments stored in the same archive.- Fix wfdb_to_mat encoding, slicing, and header metadata
wfdb_to_matnow passeschannelstordrecordand computes output length from the sliced record. It writes 8-bit (offset binary) and 32-bit MAT files with proper data types and 8-byte MAT v5 padding, preserves missing samples, clears already-applied channel skew, handles unsetadc_resandadc_zerofields, updates header checksums, and handles forward-slash record paths across platforms.- Preserve shifted samples in wfdb_to_mat
wfdb_to_matnow chooses a wider output type when samples shifted byadc_zerodo not fit the type suggested by the header. It raises an error instead of silently wrapping samples that cannot fit in a 32-bit MAT file.- Fix channels and invalid samples in wfdb_to_wav
wfdb_to_wavnow writes only the signals selected withchannels, which it used to ignore. Invalid samples are written as -32768, the format 16 invalid value, so they are read back as missing. For a resolution below 12 bits, they used to overflow and become 0. The samples are now read as digital values, instead of being read as physical values and converted back.- Fix wfdb_to_wav failing for every record
wfdb_to_wavnow reads the record withsmooth_frames=True, since a .wav file holds one sample per frame for each signal. It used to read the expanded samples, and then failed with anAttributeError(aTypeErrorin older versions) becausep_signalwas not set. Withwrite_header=True, the header now gives one sample per frame for each signal, as in the .wav file, so a converted record with more than one sample per frame can be read back.- Reject aux notes that can’t be written in wrann
wrannnow raises aValueErrorif anaux_noteis longer than 255 characters or contains characters outside Latin-1, instead of writing a corrupt annotation file. A longer note used to be read back as many extra annotations, and other characters were silently replaced.- Allow None for annotations without notes in wrann
wrannnow acceptsNoneinaux_notefor annotations without a note, as the docstring says, and writes it the same way as an empty string. It used to raise aTypeError.- Accept sample numbers stored as floats in wrann
wrannnow accepts asamplearray of floats if all the values are whole numbers (as from a detector that returns floats), and writes them as integers. Other floats, such as20.5or NaN, raise aValueError. Float arrays used to fail withTypeError: ufunc 'bitwise_and' not supported for the input types.- Fix writing physical-only records
Record.wrsampnow temporarily converts physical signals to digital samples when the corresponding digital signals are missing, then restores the record.- Speed up XQRS backsearch
XQRSno longer rechecks peaks that an earlier backsearch already rejected. Long stretches without QRS complexes (for example a disconnected lead) made detection take quadratic time, up to hours on long records. The detected QRS locations are unchanged.- Prevent ADC overflow with float32 signals
ADC parameter calculation and conversion now use float64 arithmetic for float32 physical signals. Samples near digital format limits no longer fail validation because of a one-value rounding overflow.
- Use only beat annotations in ann2rr
ann2rrnow computes intervals between beat (QRS) annotations only, as the WFDBann2rrprogram does, so rhythm changes, comments and other non-beat annotations no longer split an RR interval in two. The first interval is still measured from the start of the record. To include all annotations as before, passall_annotations=True(the equivalent ofann2rr -A).- Select intervals by time in the record in ann2rr
The
start_timeandstop_timearguments ofann2rrnow select intervals by when they end in the record, as the WFDBann2rrprogram’s-fand-toptions do, and the first interval is measured fromstart_time. They used to filter intervals by their length instead. Astart_timeafterstop_timenow raises aValueError.- Fix get_contained_labels with pandas 3
Annotation.get_contained_labelsno longer raises aTypeErrorwith pandas 3 for annotations withoutlabel_storevalues, such as those read withrdannby default.- Fix record name and add write directory in csv2ann
csv2annnow takes the record name from the CSV file name without its directory and extension, ascsv_to_wfdbdoes. Paths with a directory (such asdata/x.csv) used to fail when writing, and./x.csvgave an empty name. The annotation file is written to the newwrite_dirargument, which defaults to the current directory.csv2annis now included in the API documentation.- Fix rr2ann with times and with a symbol column
rr2annwithas_time=Truenow rounds times to the nearest sample instead of truncating them, so (for example) 0.29 seconds at 100 Hz gives sample 29 instead of 28. Intervals in samples with a second column of symbols no longer raise an error, and fractional intervals are summed before rounding.
Version 4.3.1 (Feb 2026)¶
- Add fix for Pandas 3.0
In Pandas 3.0, DataFrame.set_index() no longer accepts a raw numpy array as the keys argument. Adds fix by wrapping the index array in pd.Index().
- Fix ADC formula
Fixes [formula for ADC gain](https://github.com/MIT-LCP/wfdb-python/pull/551).
- Allow multifrequency signals to be written with expanded argument
Allow [expanded parameter in MultiRecord.wrsamp](https://github.com/MIT-LCP/wfdb-python/pull/555).
- Date validation when saving multi-segment records
Adds validation check for date and time fields in headers when saving multi-segment records.
Version 4.3.0 (Apr 2025)¶
- Bump Sphinx to 7.0.0
Bump Sphinx to 7.0.0
- Integrate `fsspec` for reading WFDB files from the cloud
Enables reading WFDB files from cloud URLs
Version 4.2.0 (Jan 2025)¶
- Add support for Numpy 2.0
Fixes were added to address [changes to type promotion](https://numpy.org/devdocs/numpy_2_0_migration_guide.html#changes-to-numpy-data-type-promotion) that led to overflow errors (e.g. https://github.com/MIT-LCP/wfdb-python/issues/493).
- Fix UnboundLocalError in GQRS algorithm
Fixes the GQRS algorithm to address an UnboundLocalError.
- Support write directory in `csv_to_wfdb`
write_dir can now be specified when calling csv_to_wfdb.
- Use uv for for package management
Moves package management from poetry to uv.
- Fix misordered arguments in `util.lines_to_file`
Fixes misordered arguments in util.lines_to_file.
- Allow signals to be written with unique samples per frame
Adds capability to write signal with unique samps_per_frame to wfdb.io.wrsamp.
- Allow expanded physical signal in `calc_adc_params`
Updates calc_adc_params to allow an expanded physical signal to be passed. Previously only a non-expanded signal was allowed.
- Allow selection of channels when converting to EDF
Fixes the wfdb-to_edf() function to support an optional channels argument.
- Migrates Ricker wavelet from SciPy to WFDB after deprecation
The Ricker wavelet (scipy.signal.ricker) was removed in SciPy v1.15, so the original implementation was migrated to the WFDB package.
- Miscellaneous style and typing fixes
Various fixes were made to code style and handling of data types.
Version 4.1.2 (June 2023)¶
- Handle more than 8 compressed signals in wrsamp
Previously, the package did not support writing of compressed records with more than 8 channels.
- Use int64 instead of int for ann2rr
Fixes ‘np has no attribute np.int’ error raised when running ann2rr.
Version 4.1.1 (April 2023)¶
- Remove upper bound on dependencies
Previously, the package provided restrictive caps on version number of dependencies. These caps have been removed.
- Miscellaneous style and typing fixes
Various fixes were made to code style and handling of data types.
Version 4.1.0 (December 2022)¶
- Converting a record into a DataFrame
The new method
wfdb.Record.to_dataframe()can be used to convert signal data from a Record object into a Pandas DataFrame, which can then be manipulated using Pandas methods.- Locating signals in a multi-segment record
The new method
wfdb.MultiRecord.contained_ranges()can be used to search for time intervals within a record that contain a specific channel. The methodwfdb.MultiRecord.contained_combined_ranges()searches for time intervals that contain several specific channels at once.- Writing custom annotation symbols
The
wfdb.wrann()function can now be used to write annotations with custom annotation types (symbolstrings.) Custom annotation types must be defined using thecustom_labelsargument.- Correct rounding when converting floating-point signal data
When calling
wfdb.wrsamp()with ap_signalargument, input values will be rounded to the nearest sample value rather than being truncated towards zero. The same applies to thewfdb.Record.adc()method.- Writing signals in compressed format
The
wfdb.wrsamp()function, and thewfdb.Record.wrsamp()method, now support writing compressed signal files. To write a compressed file, set thefmtvalue to"508"(for an 8-bit channel),"516"(for a 16-bit channel), or"524"(for a 24-bit channel).- Decoding non-ASCII text in EDF files
The
wfdb.io.convert.edf.read_edf()andwfdb.io.convert.edf.rdedfann()functions now take an optional argumentencoding, which specifies the character encoding for text fields. ISO-8859-1 encoding is used by default, in contrast to older versions of the package which used UTF-8.- Bug fixes when writing signal metadata
When calling
wfdb.Record.wrsamp(), the checksum and samples-per-frame fields in the header file will correctly match the signal data, rather than relying on attributes of the Record object.