From b1b715aa0b838cf50b4127d3eafc969deaeeb210 Mon Sep 17 00:00:00 2001 From: Ekaterina Noskova Date: Wed, 6 Nov 2024 13:59:29 +0100 Subject: [PATCH] Update docs --- docs/source/changelogs.rst | 16 ++ docs/source/user_manual/installation.rst | 253 ++++++------------ .../set_model/set_model_struct.rst | 2 +- 3 files changed, 104 insertions(+), 167 deletions(-) diff --git a/docs/source/changelogs.rst b/docs/source/changelogs.rst index 9f87551..b05263f 100644 --- a/docs/source/changelogs.rst +++ b/docs/source/changelogs.rst @@ -1,6 +1,21 @@ Changelogs ============== +[2.0.1] - 2023-11-06 +-------------------- +GADMA was updated and tested on Python3.10 with the latest versions of dependencies. + +Changelog since 2.0.0: + +1. Add lower bounds for first and second splits (see #92) +2. Create pyproject.toml and setup.cfg +3. Add dependencies including `moments-popgen`, `demes` and `demesdraw` to setup - they will be automatically installed. +4. Change code to work with last version of `moments`. +5. Drop support for Gpy and GPyOpt bayesian optimization - class will be removed in the next releases +6. Tests for SMAC bayesian optimization does not run on GitHub Actions - need to upgrade code for the last `smac` version (TODO). +7. Update params_file template +8. Update docs + [2.0.0] - 2023-09-23 -------------------- @@ -8,6 +23,7 @@ Changelogs Official release of GADMA2.0.0, it includes all pre-releases 2.0.0rc1 - 2.0.0rc26 Changelog since 2.0.0rc26: + 1. Catch cases when theta and ancestral population size are negative for moments and dadi engines (issue #84). Fix optimization routine to ignore such parameters. 2. Fix GitHub Action tests and PyPi publishing. 3. Add documentation (regarding issues #60, #75, #85) diff --git a/docs/source/user_manual/installation.rst b/docs/source/user_manual/installation.rst index 6db9a55..98e3458 100644 --- a/docs/source/user_manual/installation.rst +++ b/docs/source/user_manual/installation.rst @@ -1,88 +1,18 @@ Installation ============== -Dependencies -------------- - -**The current version of GADMA (greater than 2.0.0) supports Python3 only**. `Older versions `_ supported Python 2 as well but not any more. - -Below we hightlight GADMA dependencies. All of them could be easily installed using requirements files which are specified in the brackets before lists. To install dependencies from requerement file run: +Set up conda environment +------------------------ +In order to avoid issues, we recommend to create an empty `conda environment `_. +**The current version of GADMA (greater than 2.0.0) supports Python3 only**. .. code-block:: console - $ pip -r requirements_file - -GADMA requires the following dependencies (`requirements/minimal.txt`): - -* Python3 -* NumPy (>= 1.2.0) -* Scipy (>= 0.6.0) -* ruamel.yaml (<0.18.0) -* ``dadi`` (>= 1.7.0) -* ``moments`` (>= 1.0.0) -* ``momi`` -* ``moments.LD`` (is installed alongside with ``moments``) -* nlopt (for ``dadi``) -* Cython (for ``moments``) -* mpmath (for ``moments``) - -To draw demographic models one should also install the following packages (`requirements/minimal.txt`): - -* matplotlib (>= 0.98.1, <3.5) -* Pillow (>= 4.2.1) - optional -* ``moments`` (>= 1.0.0) - -To use ``demes`` engine to draw models (`requirements/engines.txt`): - -* demes -* demesdraw - -To calculate confidence intervals one should install (`requirements/minimal.txt`): - -* pandas - -To run Bayesian optimization `smac` of specified version is requered (`requirements/bayes_opt.txt`): - -* scikit-optimize -* configspace -* smac (**==0.13.1**) - -.. note:: - ``momi`` package sometimes is not installed correctly for Windows and MacOS. If ``momi`` is not available please install it manually following the installation instructions in `momi's manual `_. - -.. note:: - ``momentsLD`` - the extension of ``moments``, it is installed together with ``moments``. - -Getting help for engine installation ------------------------------------- -If there are some troubles installing the engine, please, first of all check the table below for the ability to install this engine on your system. You are always welcome to `open an issue `_ on GitHub for getting help. - -GADMA has automatic tests on GitHUb for engines on different systems (Linux, Windows, MacOS). The following table indicates (according to our tests) if engine could be installed on specified system: - -.. list-table:: - :header-rows: 1 - - * - Feature - - ``dadi`` - - ``moments`` - - ``momi`` - - ``momentsLD`` + $ conda create -n gadma_env python=3.10 + $ conda activate gadma_env + $ conda config --add channels bioconda + $ conda config --add channels conda-forge - * - Linux - - ✅ - - ✅ - - ✅ - - ✅ - * - Windows - - ✅ - - ✅ - - ❌ - - ✅ - * - MacOS - - ✅ - - ✅ - - ✅ - - ✅ Installing the latest release ------------------------------ @@ -99,146 +29,137 @@ or $ conda install -c bioconda gadma +This will install GADMA with ``dadi``, ``moments`` and ``momentsLD`` engines. .. warning:: - Installation via ``pip`` and ``conda`` will not install the ``moments`` library. To install it one should run: + Sometimes some dependencies (e.g. ``dadi`` or ``scikit-allel``) fail to install when GADMA is installed using ``pip``. You can install them using ``conda`` before the installation of GADMA: .. code-block:: console - $ pip install git+https://github.com/MomentsLD/moments.git + $ conda install dadi scikit-allel - or + If you faced an issue for ``moments`` (``moments-popgen``) package on MacOS, try installing it independently using: .. code-block:: console - $ conda install -c bioconda moments + $ pip install Cython + $ pip install "setuptools_scm>=8" + $ pip install --no-build-isolation moments-popgen -Troubleshooting ---------------- - -If you experience problems with dependencies, we recommend to create an empty `conda environment `_: - -.. code-block:: console - - $ conda create -n gadma_env python=3.10 - $ conda activate gadma_env - -It is possible to install versions that are used for testing by downloading file `minimal.txt` from `here `_ and install requirements using: - -.. code-block:: console - - $ pip install -r minimal.txt - $ pip install gadma -For **MacOS with M processor** we suggest the following recipe (credit to `@Enricobazzi `_): +If you want to use ``momi2`` engine, please install it: .. code-block:: console - $ pip install git+https://github.com/MomentsLD/moments.git - $ conda install -c conda-forge dadi - $ conda install -c conda-forge scikit-allel - $ pip install gadma - $ pip uninstall ruamel.yaml - $ pip install "ruamel.yaml<0.18.0" - $ pip uninstall matplotlib - $ pip install "matplotlib<3.5" + $ pip install momi -Manual installation ------------------------------ - -Some features are added to the GADMA project but are not released yet. One can install GADMA directly from the repository. - -First clone the repository: +.. note:: + ``momi`` package sometimes is not installed correctly for Windows and MacOS. If ``momi`` is not available please install it manually following the installation instructions in `momi's manual `_. - .. code-block:: console - $ git clone https://github.com/ctlab/GADMA.git - $ cd GADMA -Dependencies could be installed either automatically or manually. -Automatic mode -************** +Verifying installation +------------------------- -One could install everything with the ``install`` script: +To verify the installation, run: .. code-block:: console - $ ./install + $ gadma --test -Full-manual mode -**************** -Install dependencies manually: +If the installation was successful, one will find the following information at the end: - * NumPy - .. code-block:: console +.. code-block:: console - $ pip install numpy + --Finish pipeline-- - * Scipy - .. code-block:: console + --Test passed correctly-- + Thank you for using GADMA! - $ pip install scipy - * ruamel.yaml - .. code-block:: console +Dependencies +------------- - $ pip install ruamel.yaml +Below we hightlight GADMA dependencies: - * ``dadi``, nlopt - .. code-block:: console +* Python3 +* numPy +* scipy +* matplotlib +* Pillow (>= 4.2.1) +* pandas (<= 2.2.2) +* ruamel.yaml (== 0.16.12) +* ``dadi`` +* ``moments`` +* ``momi`` +* ``moments.LD`` (is installed alongside with ``moments``) +* h5py == 3.10.0 (for ``momentsLD``) +* scikit-allel (for ``moments``) - $ pip install dadi +If you wish to use ``moments`` for demographic models plotting you need older +version of ``matplotlib``: - * ``moments``, mpmath, Cython - .. code-block:: console - $ pip install --upgrade Cython - $ pip install mpmath - $ pip install git+https://github.com/MomentsLD/moments.git +To calculate confidence intervals one should install (`requirements/minimal.txt`): - * ``momi`` - .. code-block:: console +* pandas - $ pip install momi +To run Bayesian optimization `smac` of specified version is requered (`requirements/bayes_opt.txt`): - * matplotlib - .. code-block:: console +* scikit-optimize +* configspace +* bayesmark +* smac (**==0.13.1**) - $ pip install matplotlib +Troubleshooting +--------------- +If there are some troubles installing the engine, please, first of all check the table below for the ability to install this engine on your system. You are always welcome to `open an issue `_ on GitHub for getting help. - * Pillow - .. code-block:: console +GADMA has automatic tests on GitHUb for engines on different systems (Linux, Windows, MacOS). The following table indicates (according to our tests) if engine could be installed on specified system: - $ pip install Pillow +.. list-table:: + :header-rows: 1 - * pandas - .. code-block:: console + * - Feature + - ``dadi`` + - ``moments`` + - ``momi`` + - ``momentsLD`` - $ pip install pandas + * - Linux + - ✅ + - ✅ + - ✅ + - ✅ + * - Windows + - ✅ + - ✅ + - ❌ + - ✅ + * - MacOS + - ✅ + - ✅ + - ✅ + - ✅ -3) Install GADMA - .. code-block:: console - $ pip install . +Manual installation +----------------------------- -Verifying installation -------------------------- +Some features are added to the GADMA project but are not released yet. One can install GADMA directly from the repository. -To verify the installation, run: +First clone the repository: .. code-block:: console - $ gadma --test - + $ git clone https://github.com/ctlab/GADMA.git + $ cd GADMA -If the installation was successful, one will find the following information at the end: +Run installation: .. code-block:: console - --Finish pipeline-- - - --Test passed correctly-- - Thank you for using GADMA! + $ pip install . diff --git a/docs/source/user_manual/set_model/set_model_struct.rst b/docs/source/user_manual/set_model/set_model_struct.rst index bda666f..097190f 100644 --- a/docs/source/user_manual/set_model/set_model_struct.rst +++ b/docs/source/user_manual/set_model/set_model_struct.rst @@ -155,7 +155,7 @@ For example, if there is model structure equal to (2, 1, 1) and one want to have .. code-block:: none # params_file - Migration masks: [[[0, 0], [1, 0], [[0, 0, 1], [0, 0, 0], [1, 0, 0]]] + Migration masks: [[[0, 0], [1, 0]], [[0, 0, 1], [0, 0, 0], [1, 0, 0]]] .. note:: Option ``Migration masks`` is used only in case of demographic model with structure and ``Initial structure`` equal to ``Final structure``.