install.rst

.. SPDX-FileCopyrightText: Copyright © 2023 Idiap Research Institute <contact@idiap.ch>
..
.. SPDX-License-Identifier: GPL-3.0-or-later

.. _mednet.libs.classification.install:

==============
 Installation
==============

Installation may follow one of three paths: deployment or development for
CPU-only execution, or a mixed development and deployment environment with
Nvidia CUDA support. Choose the relevant tab for details on each of those
installation paths.

.. tab:: Deployment

   Install using pip_, or your preferred Python project management solution (e.g.
   uv_, rye_ or poetry_).

   **Stable** release, from PyPI:

   .. code:: sh

      pip install mednet
      mednet info

   **Latest** development branch, from its git repository:

   .. code:: sh

      pip install git+https://gitlab.idiap.ch/biosignal/software/mednet@main
      mednet info


.. tab:: Development

   Checkout the repository, and then use pixi_ to setup a full development
   environment:

   .. code:: sh

      git clone git@gitlab.idiap.ch:biosignal/software/mednet
      pixi install --frozen
      pixi run mednet info

   .. tip::

      The ``--frozen`` flag will ensure that the latest lock-file available
      with sources is used.  If you'd like to update the lock-file to the
      latest set of compatible dependencies, remove that option.

      If you use `direnv to setup your pixi environment
      <https://pixi.sh/latest/features/environment/#using-pixi-with-direnv>`_
      when you enter the directory containing this package, you can use a
      ``.envrc`` file similar to this:

      .. code:: sh

         watch_file pixi.lock
         export PIXI_FROZEN="true"
         eval "$(pixi shell-hook)"


.. tab:: CUDA

   Checkout the repository, and then use pixi_ to setup a version of this
   package that can run on a CUDA-enabled machine:

   .. code:: sh

      git clone git@gitlab.idiap.ch:biosignal/software/mednet
      pixi install --frozen -e cuda
      pixi run -e cuda mednet info

   To enable CUDA support, always run applications using the ``cuda``
   environment via ``pixi run -e cuda ...``.  Refer to further pixi
   configuration tips on the *Development* tab above.


.. _mednet.libs.classification.setup:

Setup
-----

A configuration file may be useful to setup global options that should be often
reused.  The location of the configuration file depends on the value of the
environment variable ``$XDG_CONFIG_HOME``, but defaults to
``~/.config/mednet.libs.classification.toml``.  You may edit this file using your preferred
editor.

Here is an example configuration file that may be useful as a starting point:

.. code:: toml

   [datadir]
   indian = "/Users/myself/dbs/tbxpredict"
   montgomery = "/Users/myself/dbs/montgomery-xrayset"
   shenzhen = "/Users/myself/dbs/shenzhen"
   nih_cxr14_re = "/Users/myself/dbs/nih-cxr14-re"
   tbx11k_simplified = "/Users/myself/dbs/tbx11k-simplified"

   [nih_cxr14_re]
   idiap_folder_structure = false  # set to `true` if at Idiap


.. tip::

   To get a list of valid data directories that can be configured, execute:

   .. code:: sh

      mednet database list


   You must procure and download databases by yourself.  The raw data is not
   included in this package as we are not authorised to redistribute it.

   To check whether the downloaded version is consistent with the structure
   that is expected by this package, run:

   .. code:: sh

      mednet database check <database_name>


.. _mednet.libs.classification.setup.databases:

Supported Databases
===================

Here is a list of currently supported databases in this package, alongside
notable properties.  Each database name is linked to the location where
raw data can be downloaded.  The list of images in each split is available
in the source code.


.. _mednet.libs.classification.setup.databases.tb:

Tuberculosis databases
~~~~~~~~~~~~~~~~~~~~~~

The following databases contain only the tuberculosis final diagnosis (0 or 1).
In addition to the splits presented in the following table, 10 folds
(for cross-validation) randomly generated are available for these databases.

.. list-table::

   * - Database
     - Reference
     - H x W
     - Samples
     - Training
     - Validation
     - Test
   * - Montgomery_
     - [MONTGOMERY-SHENZHEN-2014]_
     - 4020 x 4892
     - 138
     - 88
     - 22
     - 28
   * - Shenzhen_
     - [MONTGOMERY-SHENZHEN-2014]_
     - Varying
     - 662
     - 422
     - 107
     - 133
   * - Indian_
     - [INDIAN-2013]_
     - Varying
     - 155
     - 83
     - 20
     - 52


.. _mednet.libs.classification.setup.databases.tb+signs:

Tuberculosis multilabel databases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following databases contain the labels healthy, sick & non-TB, active TB,
and latent TB. The implemented tbx11k database in this package is based on
the simplified version, which is just a more compact version of the original.
In addition to the splits presented in the following table, 10 folds
(for cross-validation) randomly generated are available for these databases.

.. list-table::

   * - Database
     - Reference
     - H x W
     - Samples
     - Training
     - Validation
     - Test
   * - TBX11K_
     - [TBX11K-2020]_
     - 512 x 512
     - 11'200
     - 6600
     - 1800
     - 2800
   * - TBX11K_SIMPLIFIED_
     - [TBX11K-SIMPLIFIED-2020]_
     - 512 x 512
     - 11'200
     - 6600
     - 1800
     - 2800


.. _mednet.libs.classification.setup.databases.tbmultilabel+signs:

Tuberculosis + radiological findings databases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following databases contain both the tuberculosis final diagnosis (0 or 1)
and radiological findings.

.. list-table::

   * - Database
     - Reference
     - H x W
     - Samples
     - Train
     - Test
   * - PadChest_
     - [PADCHEST-2019]_
     - Varying
     - 160'861
     - 160'861
     - 0


.. _mednet.libs.classification.setup.databases.signs:

Radiological findings databases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following database contains only the radiological findings without any
information about tuberculosis.

.. note::

   NIH CXR14 labels for training and validation sets are the relabeled
   versions done by the author of the CheXNeXt study [CHEXNEXT-2018]_.

.. list-table::

   * - Database
     - Reference
     - H x W
     - Samples
     - Training
     - Validation
     - Test
   * - NIH_CXR14_re_
     - [NIH-CXR14-2017]_
     - 1024 x 1024
     - 109'041
     - 98'637
     - 6'350
     - 4'054


.. _mednet.libs.classification.setup.databases.hiv-tb:

HIV-Tuberculosis databases
~~~~~~~~~~~~~~~~~~~~~~~~~~

The following databases contain only the tuberculosis final diagnosis (0 or 1)
and come from HIV infected patients. 10 folds (for cross-validation) randomly
generated are available for these databases.

Please contact the authors of these databases to have access to the data.

.. list-table::

   * - Database
     - Reference
     - H x W
     - Samples
   * - TB POC
     - [TB-POC-2018]_
     - 2048 x 2500
     - 407
   * - HIV TB
     - [HIV-TB-2019]_
     - 2048 x 2500
     - 243


.. _mednet.libs.segmentation.setup.databases.retinography:

Retinography
------------


.. list-table:: Supported Retinography Datasets (``*``: provided within this package)

   * - Dataset
     - Reference
     - H x W
     - Samples
     - Mask
     - Vessel
     - OD
     - Cup
     - Split Reference
     - Train
     - Test
   * - DRIVE_
     - [DRIVE-2004]_
     - 584 x 565
     - 40
     - ``x``
     - ``x``
     -
     -
     - [DRIVE-2004]_
     - 20
     - 20
   * - STARE_
     - [STARE-2000]_
     - 605 x 700
     - 20
     - ``*``
     - ``x``
     -
     -
     - [MANINIS-2016]_
     - 10
     - 10
   * - CHASE-DB1_
     - [CHASEDB1-2012]_
     - 960 x 999
     - 28
     - ``*``
     - ``x``
     -
     -
     - [CHASEDB1-2012]_
     - 8
     - 20
   * - HRF_
     - [HRF-2013]_
     - 2336 x 3504
     - 45
     - ``x``
     - ``x``
     -
     -
     - [ORLANDO-2017]_
     - 15
     - 30
   * - IOSTAR_
     - [IOSTAR-2016]_
     - 1024 x 1024
     - 30
     - ``x``
     - ``x``
     - ``x``
     -
     - [MEYER-2017]_
     - 20
     - 10
   * - DRIONS-DB_
     - [DRIONSDB-2008]_
     - 400 x 600
     - 110
     -
     -
     - ``x``
     -
     - [MANINIS-2016]_
     - 60
     - 50
   * - `RIM-ONE r3`_
     - [RIMONER3-2015]_
     - 1424 x 1072
     - 159
     -
     -
     - ``x``
     - ``x``
     - [MANINIS-2016]_
     - 99
     - 60
   * - Drishti-GS1_
     - [DRISHTIGS1-2014]_
     - varying
     - 101
     -
     -
     - ``x``
     - ``x``
     - [DRISHTIGS1-2014]_
     - 50
     - 51
   * - REFUGE_
     - [REFUGE-2018]_
     - 2056 x 2124 (1634 x 1634)
     - 1200
     -
     -
     - ``x``
     - ``x``
     - [REFUGE-2018]_
     - 400 (+400)
     - 400
   * - DRHAGIS_
     - [DRHAGIS-2017]_
     - Varying
     - 39
     - ``x``
     - ``x``
     -
     -
     - [DRHAGIS-2017]_
     - 19
     - 20

.. warning:: **REFUGE Dataset Support**

  The original directory ``Training400/AMD`` in REFUGE is considered to be
  replaced by an updated version provided by the `AMD Grand-Challenge`_ (with
  matching names).

  The changes concerns images ``A0012.jpg``, which was corrupted in REFUGE, and
  ``A0013.jpg``, which only exists in the AMD Grand-Challenge version.


.. _mednet.libs.segmentation.setup.databases.xray:

X-Ray
-----

.. list-table:: Supported X-Ray Datasets

   * - Dataset
     - Reference
     - H x W
     - Radiography Type
     - Samples
     - Mask
     - Split Reference
     - Train
     - Test
   * - `Montgomery County`_
     - [MC-2014]_
     - 4020 x 4892, or 4892 x 4020
     - Digital Radiography (DR)
     - 138
     - ``*``
     - [GAAL-2020]_
     - 96 (+14)
     - 28
   * - JSRT_
     - [JSRT-2000]_
     - 2048 x 2048
     - Digitized Radiography (laser digitizer)
     - 247
     - ``*``
     - [GAAL-2020]_
     - 172 (+25)
     - 50
   * - Shenzhen_
     - [SHENZHEN-2014]_
     - Varying
     - Computed Radiography (CR)
     - 662
     - ``*``
     - [GAAL-2020]_
     - 396 (+56)
     - 114
   * - CXR8_
     - [CXR8-2017]_
     - 1024 x 1024
     - Digital Radiography
     - 112120
     - ``x``
     - [GAAL-2020]_
     - 78484 (+11212)
     - 22424

.. warning:: **SHENZHEN/JSRT/CXR8 Dataset Support**

  For some datasets (in which the annotations/masks are downloaded separately
  from the dataset with the original images), both the original images and
  annotations must be downloaded and placed inside the same directory, to match
  the dataset reference dictionary's path.

  * The Shenzhen_ root directory should then contain at least these two
    subdirectories:

    - ``CXR_png/`` (directory containing the CXR images)
    - ``mask/`` (contains masks downloaded from `Shenzhen Annotations`_)

  * The CXR8_ root directory:

    - ``images/`` (directory containing the CXR images)
    - ``segmentations/`` (contains masks downloaded from `CXR8 Annotations`_)

  * The JSRT_ root directory:

    - ``All247images/`` (directory containing the CXR images, in raw format)
    - ``scratch/`` (contains masks downloaded from `JSRT Annotations`_)


.. include:: links.rst