.. _installation:

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

This section describes two types of installation:

- `Installation for standard users`_: for processing and analyzing disdrometer data.
- `Installation for contributors`_: for those who want to enrich the project (e.g., adding a new reader, data, etc.).

We recommend setting up a virtual environment before installing DISDRODB.


.. _virtual_environment:

Virtual Environment Creation
============================

Although optional, using a virtual environment when installing DISDRODB is recommended.

Virtual environments isolate dependencies, simplify package management, improve maintainability,
enhance security, and streamline your development workflow.

Below are two options for creating a virtual environment,
using `venv <https://docs.python.org/3/library/venv.html>`__ or
`conda <https://docs.conda.io/en/latest/>`__ (recommended).

**With conda:**

* Install `mamba <https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html>`_, `miniconda <https://docs.conda.io/en/latest/miniconda.html>`__ or `anaconda <https://docs.anaconda.com/anaconda/install/>`__ if you haven't already.
* Create a new conda environment with one of the latest Python versions (e.g., Python 3.13):

.. code-block:: bash

    conda create --name disdrodb python=3.13

* Activate the environment:

.. code-block:: bash

    conda activate disdrodb

**With venv:**

* On Windows, create and activate a virtual environment (replace ``pyXXX`` with your Python version, e.g., ``py313``):

.. code-block:: bash

    python -m venv disdrodb-pyXXX
    cd disdrodb-pyXXX/Scripts
    activate

* On macOS/Linux, create and activate a virtual environment (replace ``pyXXX`` with your Python version, e.g., ``py313``):

.. code-block:: bash

    python3 -m venv disdrodb-pyXXX
    source disdrodb-pyXXX/bin/activate


.. _installation_standard:

Installation for standard users
==================================

The latest disdrodb stable version is available
on the `Python Packaging Index (PyPI) <https://pypi.org/project/disdrodb/>`__
and on the `conda-forge channel <https://anaconda.org/conda-forge/disdrodb>`__.

You can install the package with either pip or conda (recommended).
If you created a virtual environment, make sure to activate it before installing.

**With conda:**

.. code-block:: bash

   conda install -c conda-forge disdrodb


.. note::
   As a lightweight alternative to conda, you can use `micromamba <https://micromamba.readthedocs.io/en/latest/>`__.

**With pip:**

.. code-block:: bash

   pip install disdrodb


.. _installation_contributor:

Installation for contributors
================================

The latest disdrodb version is available on the GitHub repository `disdrodb <https://github.com/ltelab/disdrodb>`__.
You can install the package in editable mode to modify the code and see changes immediately.
Follow the steps below to install the package in editable mode.

Clone the repository from GitHub
......................................

According to the :ref:`contributors guidelines <contributor_guidelines>`, you should first
`create a fork into your personal GitHub account <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo>`__.

Then create a local copy of the repository you forked with:

.. code-block:: bash

   git clone https://github.com/<your-account>/disdrodb.git
   cd disdrodb

Create the development environment
......................................

We recommend creating a dedicated conda environment for development purposes.
You can create a conda environment (e.g., with Python 3.13) with:

.. code-block:: bash

	conda create --name disdrodb-dev python=3.13
	conda activate disdrodb-dev

Install the package dependencies
............................................

Install all required dependencies without installing disdrodb itself:

.. code-block:: bash

	conda install --only-deps disdrodb


Install the package in editable mode
................................................

Install the disdrodb package in editable mode by executing the following command in the disdrodb repository's root:

.. code-block:: bash

	pip install -e ".[dev]"


Install code quality checks
..............................................

Install the pre-commit hook by executing the following command in the disdrodb repository's root:

.. code-block:: bash

   pre-commit install


Pre-commit hooks are automated scripts that run during each commit to detect basic code quality issues.
If a hook identifies an issue (signified by the pre-commit script exiting with a non-zero status), it halts the commit process and displays the error messages.

.. note::

	The versions of the software used in the pre-commit hooks is specified in the `.pre-commit-config.yaml <https://github.com/ltelab/disdrodb/blob/main/.pre-commit-config.yaml>`__ file. This file serves as a configuration guide, ensuring that the hooks are executed with the correct versions of each tool, thereby maintaining consistency and reliability in the code quality checks.


Further details about pre-commit hooks can be found in the Contributors Guidelines, specifically in the provided in the :ref:`Code quality control <code_quality_control>` section.


Optional dependencies
=======================

Specific functionality in disdrodb may require additional optional dependencies.
To unlock the full functionality offered by disdrodb, we recommend installing the packages detailed below.

IDEs
..............

For an improved development experience, consider installing the intuitive `Jupyter <https://jupyter.org/>`_ and
`Spyder <https://www.spyder-ide.org/>`_ Python Integrated Development Environments (IDEs):

.. code-block:: bash

   conda install -c conda-forge jupyter spyder


Speed Up Xarray Computations
...............................

To speed up arrays computations with xarray, install
`flox <https://flox.readthedocs.io/en/latest/>`_,
`numbagg <https://github.com/numbagg/numbagg>`_,
`bottleneck <https://bottleneck.readthedocs.io/en/latest/intro.html>`_ and
`opt-einsum <https://optimized-einsum.readthedocs.io/en/stable/>`_:

.. code-block:: bash

   conda install -c conda-forge flox numbagg bottleneck opt-einsum


Summary Tables
..............................

To generate automatic summary tables of rain events or DSD parameters within the disdrodb software,
you must install `Tectonic <https://tectonic-typesetting.github.io/en-US/>`__.
Tectonic is a modern typesetting system used to compile LaTeX documents and create PDF files.

You can install Tectonic using conda:

.. code-block:: bash

   conda install -c conda-forge tectonic

.. _pytmatrix_installation:

T-Matrix Radar Simulations
............................

To simulate radar polarimetric variables in the DISDRODB L2E and L2M products, you must install the pyTMatrix package.
The original pyTMatrix cannot be installed on recent Python versions.

The instructions below show how to install the LTE-maintained fork of pyTMatrix, which is compatible with modern Python interpreters.

1. Install the GNU `Fortran <https://fortran-lang.org/>`__ Compiler (gfortran) and the `Meson Build system <https://mesonbuild.com/>`__.

.. code-block:: bash

   conda install -c conda-forge gfortran meson

2. Then install pyTMatrix with:

.. code-block:: bash

   pip install git+https://github.com/ltelab/pytmatrix-lte.git

3. Verify that the package is installed correctly:

.. code-block:: bash

   python -c "import pytmatrix; print(pytmatrix.__version__)"
   python -c "import pytmatrix; raise SystemExit(pytmatrix.run_tests())"


Alternative installation instructions for developers are available at `https://github.com/ltelab/pytmatrix-lte <https://github.com/ltelab/pytmatrix-lte>`__.



Run DISDRODB on Jupyter Notebooks
==================================

To run disdrodb in a `Jupyter Notebook <https://jupyter.org/>`__,
you need to set up an IPython kernel for the environment where disdrodb is installed.

For example, if your conda/virtual environment is named ``disdrodb-dev``, run:

.. code-block:: bash

   python -m ipykernel install --user --name=disdrodb-dev

When using Jupyter Notebook, click on ``Kernel`` and then ``Change Kernel`` to select the ``disdrodb-dev`` kernel.