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=12.0 mamba install 'pytorch-gpu=*=cuda118*'


.. _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 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.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.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.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.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.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.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


.. include:: links.rst