Torch-ecg

----------------------------------------------------------------------------------------

Added
~~~~~

- Add functions for downloading PhysioNet data from AWS S3. It is now made
the default way to download data from PhysioNet.
- Add ``easydict`` as a dependency for backward compatibility (loading
old models using safe-mode ``torch.load`` with ``weights_only=True``.
Extra dependencies are added with
``torch.serialization.add_safe_globals``).

Changed
~~~~~~~

- Test files (in the `sample-data <sample-data>`__ directory) are
updated.
- Add keyword argument ``weights_only`` to ``from_checkpoint`` and
``from_remote`` methods of the models (indeed the ``CkptMixin``
class). The default value is ``"auto"``, which means the behavior is
the same as before. It checks if ``torch.serialization`` has
``add_safe_globals`` attribute. If it does, it will use safe-mode
``torch.load`` with ``weights_only=True``. Otherwise, it will use
``torch.load`` with ``weights_only=False``.

Deprecated
~~~~~~~~~~

- Support for Python 3.7, 3.8 is deprecated. The minimum supported Python
version is now 3.9. In the ``pyproject.toml`` file, the field
``requires-python`` is updated from ``>=3.7`` to ``>=3.9``.

Removed
~~~~~~~

- Restrictions on the version of ``wfdb`` and ``numpy`` packages are
removed.

Fixed
~~~~~

- Fix IO issues with several PhysioNet databases.

Security
~~~~~~~~

- Models are now loaded using safe-mode ``torch.load`` with
``weights_only=True`` by default.

----------------------------------------------------------------------------------------

Added
~~~~~

- Add support for AWS S3 in the download utility function ``http_get``
in the ``torch_ecg.utils.download`` module. PhysioNet now provides
data download links from AWS S3, and the download utility function
can now handle these links if AWS CLI is installed. This feature is
implemented but not put into use yet.

Changed
~~~~~~~

- Change the default value of the ``method`` argument of the
``torch_ecg.utils.utils_signal.resample_irregular_timeseries`` function
from ``"spline"`` to ``"interp1d"``. The former is probably not
correctly implemented.
- Update the logger classes: add checking of the write access of the
``log_dir``. If the directory is not writable, the default log dir
``~/.cache/torch_ecg/logs`` is used (ref. ``torch_ecg.cfg.DEFAULTS.log_dir``).
- Update the selection mechanism of the final model for the trainer
classes: if no monitor is specified, the last model is selected by
default (previously, no model was selected and saved).
- The main part of the ``_setup_criterion`` method of the ``BaseTrainer``
class is moved to the function ``setup_criterion`` in the
``torch_ecg.models.loss`` module. The method is simplified and
enhanced.

Deprecated
~~~~~~~~~~

- Script ``setup.py`` is deprecated. The package building system is
switched to ``hatchling``.

Removed
~~~~~~~

- Remove redundancy in base trainer classes: identical ``if`` blocks
are removed from the ``_setup_criterion`` method of the ``BaseTrainer``
class.

Fixed
~~~~~

- Fix potential error in getting model name in the trainer classes.
- Fix bugs in the ``CINC2020`` and ``CINC2021`` database reader classes
for parsing the header files.

----------------------------------------------------------------------------------------

Added
~~~~~

- Add keyword argument ``with_suffix`` to function
``torch_ecg.utils.misc.get_record_list_recursive3``.
- Add function ``_download_from_google_drive`` to the
``torch_ecg.utils.download`` module for downloading files from Google
Drive.
- Add ``gdown`` as a dependency in the ``requirements.txt`` file.
- Add database reader class ``PTBXLPlus`` for the PTB-XL+ database in
``torch_ecg.databases.physionet_databases``.
- Add github-release job to the publish action for creating a release
on GitHub automatically.

Changed
~~~~~~~

- Improve the main training loop method of the base trainer class
``torch_ecg.components.trainers.BaseTrainer``.
- Allow passing additional keyword arguments to pass to ``requests.head``
in the ``url_is_reachable`` function of the ``torch_ecg.utils.download``
module (via adding the ``**kwargs`` argument).
- Restrict version of ``numpy`` to be ``<=2.0.0`` in the
``requirements.txt`` file. ``numpy`` version ``2.0.0`` is a breaking
update, and a large proportion of the dependencies of this project
are not compatible with it yet.
- Enhance the ``cls_to_bin`` function and rename it to ``one_hot_encode``
in the ``torch_ecg.utils.utils_data`` module.

Fixed
~~~~~

- Enhance compatibility for different ``pandas`` versions.
- Fix errors for taking length of an empty database reader class.

Security
~~~~~~~~

- Fix code scanning alert - Incomplete regular expression for hostnames
`21 <https://github.com/DeepPSP/torch_ecg/pull/21>`__.
- Fix code scanning alert - Incomplete URL substring sanitization
`23 <https://github.com/DeepPSP/torch_ecg/pull/23>`__.

----------------------------------------------------------------------------------------

Added
~~~~~

- Add CD workflow for the publish action with GitHub Action.
- Add an optional argument ``return_fs`` for the ``load_data``
method for the database reader classes. If ``True``, the sampling
frequency of the record is returned along with the data as a tuple.
To keep the behavior consistent, the default value is ``False``.
- Add an optional parameter ``fs`` for the function ``compute_receptive_field``
in the ``torch_ecg.utils.utils_nn`` module. If ``fs`` is provided, the
receptive field is computed based on the sampling frequency.
- Add method ``compute_receptive_field`` for several convolutional neural
network models (layers) in the ``torch_ecg.models._nets`` module.
- Add helper function ``make_serializable`` in the ``torch_ecg.utils.misc``
module for making an object serializable (with the ``json`` package).
It will convert all ``numpy`` arrays to ``list`` in an object, and
also convert ``numpy`` data types to python data types in the object
recursively.
- Add helper function ``url_is_reachable`` in the ``torch_ecg.utils.download``
module for checking if a URL is reachable.
- Add database reader class ``PTBXL`` for the PTB-XL database in
``torch_ecg.databases.physionet_databases``.
- Add class method ``from_remote`` for ``CkptMixin`` classes. It is used
to load a model from a remote location (e.g., a URL) directly.
- Add ``sphinx-emoji-favicon`` as a dependency for generating the favicon
for the documentation.
- Add utility function ``ecg_plot`` from
`ecg-image-kit <https://github.com/alphanumericslab/ecg-image-kit/.>`__.
- Add ``pyarrow`` as a dependency in the ``requirements.txt`` file.
- Add benchmark study ``train_crnn_cinc2023`` for the CinC2023 challenge.

Changed
~~~~~~~

- Change the default value ``reset_index`` of the utility function
``torch_ecg.utils.utils_data.stratified_train_test_split`` from
``True`` to ``False``.
- Enhance the decorator ``torch_ecg.utils.misc.add_kwargs`` so that
the signature of the decorated function is also updated.
- Update the documentation: use ``sphinx_toolbox.collapse`` and
``sphinxcontrib.bibtex``; add citation info in the index page.
- Make ``Dataset`` classes accept slice index for the ``__getitem__``
method.

Deprecated
~~~~~~~~~~

- Support for Python 3.6 is deprecated. The minimum supported Python
version is updated to 3.7.

Removed
~~~~~~~

- Remove broken links in the docstrings of the database reader classes.
- Remove unused scripts ``formatting.sh`` and ``push2pypi.sh``.

Fixed
~~~~~

- Fix errors in the decorator ``torch_ecg.utils.misc.add_kwargs``
when a bound method is decorated.
- Fix bugs related to data overflow for preprocessor classes that
work with ``numpy`` arrays as reported in issue
`12 <https://github.com/DeepPSP/torch_ecg/issues/12>`__.
- Fix bugs in augmentor class ``StretchCompress`` in the
``torch_ecg.augmenters`` module.
- Fix dtype error when calling ``compute_class_weight`` from
``sklearn.utils``.
- Fix the issue when handling nan values in in computing metrics.
- Fix errors for the ``ApneaECG`` database reader class when passing
a path that does not exist or a path that contains no records at
initialization.

----------------------------------------------------------------------------------------

Added
~~~~~

- Add default configs for blocks of the ``ResNet`` model in the
``torch_ecg.models.cnn`` module.
- Add ``RegNet`` model in the ``torch_ecg.models.cnn`` module.
- Add ``CutMix`` augmentor in the ``torch_ecg.augmenters`` module.
- Add support for ``torch.nn.Dropout1d`` in the models.
- Add ``.readthedocs.yml`` to the project. The documentation is
now hosted on Read the Docs besides GitHub Pages.

Changed
~~~~~~~

- Move ``torch_ecg.utils.preproc`` to ``torch_ecg.utils._preproc``.
- Allow ``embed_dim`` of ``SelfAttention`` layer not divisible by
``num_heads`` via adding a linear projection layer before the
multi-head attention layer.
- Documentation is largely improved.

Deprecated
~~~~~~~~~~

- Drop compability for older versions of ``torch`` (1.5 and below).

Removed
~~~~~~~

- Remove ``protobuf`` from the ``requirements.txt`` file.
- Clear unused methods in the ``CINC2020`` and ``CINC2021`` database
reader classes.
- Clear unused layers in the ``torch_ecg.models._nets`` module.
- Remove the ``torch_ecg.utils._pantompkins`` module. It contains
the implementation of the Pan-Tompkins algorithm for QRS detection,
modified from old versions of the ``wfdb`` package. It is moved to
the ``legacy`` folder of the project.
- Remove ``WandbLogger`` class from the ``torch_ecg.components.loggers``
module.

Fixed
~~~~~

- Fix bugs when passing ``units=None`` for the ``load_data`` method
of the PhysioNet database reader classes.

----------------------------------------------------------------------------------------

Added
~~~~~

- Add a default ``load_data`` method for physionet databases reader
classes in the base class ``PhysioNetDataBase``. In most cases,
in the inherited classes, one does not need to implement the
``load_data`` method, as the default method is sufficient. This
method is a slight improvement over ``wfdb.rdrecord``.
- Add decorator ``add_kwargs`` in the ``torch_ecg.utils.misc`` module
for adding keyword arguments to a function or method.
- Add functions ``list_databases``, ``list_datasets`` in the
``torch_ecg.datasets`` module for listing available databases reader
classes and ``Dataset`` classes.
- Add ``save`` method for the ``CkptMixin`` class. It is used to save
the model to a file.
- Add ``_normalize_leads`` a method of the base ``_DataBase`` class
in the ``torch_ecg.databases.base`` module. It is used to normalize
the names of the ECG leads.
- Add subsampling functionality for database reader classes.
- Add benchmark study ``train_mtl_cinc2022`` for the CinC2022 challenge.
- Add ``CITATIONS.bib`` file for storing BibTeX entries of the
papers related to the project.
- Add 10 sample data from the CPSC2018 database for testing in the
``sample-data`` directory.

Changed
~~~~~~~

- Use ``CitationMixin`` from the ``bib-lookup`` package as the base
class for the ``DataBaseInfo`` class in ``torch_ecg.databases.base``.
- Use ``CitationMixin`` as one of the base classes for the models
in ``torch_ecg.models``.
- Allow dummy (empty) preprocessor managers, a warning instead of an
error is raised in such cases.
- Enhance error message for the computation of metrics.
- Add keyword argument ``requires_grad`` and ``include_buffers`` to
the ``torch_ecg.utils.utils_nn.compute_module_size`` function.
The ``dtype`` argument is removed as the data type of the model
is now inferred from the model itself.
- Improve several database reader classes: ``CPSC2018``, ``CPSC2021``,
``CINC2017``, ``ApneaECG``, ``MITDB``, ``SPH``.
- Add asymmetric zero pad for convolution layers, so that when
``stride = 1`` and ``kernel_size`` is even, strict ``"same"``
padding is conducted.
- Use loggers instead of ``print`` in database reader classes.
- Integrate code coverage into the CI workflow. The coverage report
is generated and uploaded to Codecov.
- More unit tests are added, and the existing ones are updated.
Code coverage is largely improved.

Deprecated
~~~~~~~~~~

- Drop compatibility for ``tqdm`` < 4.29.1

Removed
~~~~~~~

- Remove unused rpeaks detection methods in the ``torch_ecg.utils.rpeaks``
module.
- Remove ``_normalize_leads`` method in ``LUDB`` database reader class.
- Remove unused functions in the file of the ``CPSC2020`` database reader
class.

Fixed
~~~~~

- Fix bugs in the config class ``torch_ecg.cfg.CFG``.
- Fix errors in the ``plot`` method of ``CINC2020`` and ``CINC2021``
database reader classes.

Security
~~~~~~~~

- `CVE-2007-4559 <https://github.com/advisories/GHSA-gw9q-c7gh-j9vm>`__
patch: Fix a potential security vulnerability in the
``torch_ecg.utils.download.http_get`` function.