install.rst

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

.. _mednet.install:

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

We support two installation modes, through pip_, or mamba_ (conda).


.. tab:: pip

   Stable, from PyPI:

   .. code:: sh

      pip install mednet

   Latest beta, from GitLab package registry:

   .. code:: sh

      pip install --pre --index-url https://gitlab.idiap.ch/api/v4/groups/software/-/packages/pypi/simple --extra-index-url https://pypi.org/simple mednet

   .. tip::

      To avoid long command-lines you may configure pip to define the indexes and
      package search priorities as you like.


.. tab:: mamba/conda

   Stable:

   .. code:: sh

      mamba install -c https://www.idiap.ch/software/biosignal/conda -c conda-forge mednet

   Latest beta:

   .. code:: sh

      mamba install -c https://www.idiap.ch/software/biosignal/conda/label/beta -c conda-forge mednet

   .. tip::

      To force-install Nvidia GPU support on Linux machines, execute:

      .. code:: sh

         $ mamba install pytorch-gpu

         # or, to force the Nvidia CUDA version (environments w/o Nvidia setup):

         $ CONDA_OVERRIDE_CUDA=11.2 mamba install 'pytorch-gpu=*=cuda112*'


.. _mednet.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.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 dataset list


   You must procure and download datasets 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 dataset check montgomery


.. _mednet.setup.databases:

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

Here is a list of currently supported datasets in this package, alongside
notable properties.  Each dataset 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.setup.databases.tb:

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

The following datasets 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 datasets.

.. list-table::

   * - Dataset
     - 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.setup.datasets.tb+signs:

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

The following dataset contains the labels healthy, sick & non-TB, active TB,
and latent TB. The implemented tbx11k dataset 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 datasets.

.. list-table::

   * - Dataset
     - 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.setup.datasets.tbmultilabel+signs:

Tuberculosis + radiological findings dataset
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. list-table::

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


.. _mednet.setup.datasets.signs:

Radiological findings datasets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following dataset 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::

   * - Dataset
     - 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.setup.datasets.hiv-tb:

HIV-Tuberculosis datasets
~~~~~~~~~~~~~~~~~~~~~~~~~

The following datasets 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 datasets.

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

.. list-table::

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


.. include:: links.rst