Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@noscode
noscode committed Nov 6, 2024
1 parent 4c69619 commit b1b715a
Show file tree
Hide file tree
Showing 3 changed files with 104 additions and 167 deletions.
16 changes: 16 additions & 0 deletions docs/source/changelogs.rst
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,29 @@
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
--------------------

**Major release**
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)
Expand Down
253 changes: 87 additions & 166 deletions docs/source/user_manual/installation.rst
View file
Original file line number Diff line number Diff line change
@@ -1,88 +1,18 @@
Installation
==============

Dependencies
-------------

**The current version of GADMA (greater than 2.0.0) supports Python3 only**. `Older versions <https://github.com/ctlab/GADMA/releases/tag/1.0.2>`_ 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 <https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#>`_.
**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 <https://momi2.readthedocs.io/en/latest/installation.html#>`_.

.. 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 <https://github.com/ctlab/GADMA/issues#>`_ 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
------------------------------
Expand All @@ -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 <https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#>`_:

.. 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 <https://github.com/ctlab/GADMA/blob/master/requirements/minimal.txt#>`_ 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 <https://github.com/ctlab/GADMA/issues/82>`_):
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 <https://momi2.readthedocs.io/en/latest/installation.html#>`_.

.. 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 <https://github.com/ctlab/GADMA/issues#>`_ 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 .
2 changes: 1 addition & 1 deletion docs/source/user_manual/set_model/set_model_struct.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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``.
Expand Down

0 comments on commit b1b715a

Please sign in to comment.