Using external software with Doppio
-----------------------------------

How Doppio finds programs
.........................

Doppio (via the underlying CCP-EM Pipeliner) is designed to work with a wide range of
external software programs. It finds them by searching for the program executables in
the directories listed in the ``PATH`` environment variable. Full details of how to
configure the CCP-EM Pipeliner are :ref:`explained here <configuring_pipeliner>`, but in
brief, to add a new piece of software you should do one of the following things:

* Add the directory containing the program executables (typically called ``bin/``) to
  your ``PATH``, for example in a ``bash`` terminal you can run

  .. code-block:: bash

    export PATH="/path/to/new/program/bin:$PATH"

  or put that line in your ``.bashrc`` file so it is run automatically when you start
  a new shell.

* Add the directory containing the program executables to the
  ``"additional_program_paths"`` list in the CCP-EM Pipeliner settings file.

Then start Doppio and it should find the new software.

.. note::

  Doppio does not check the versions of external programs that it finds. If your jobs
  fail, try updating to a newer version of the software. The job info in Doppio should
  usually specify what version is required. We will add automatic version checking in
  future.

.. _external_programs:

Supported software
..................

The following programs are supported in Doppio. They can be installed separately, or
for convenience, a number of them can be installed at once using the scripts in the
`package-ccpem2 <https://gitlab.com/ccpem/package-ccpem2>`_ repository. An upcoming
version of Doppio will add a tool to allow additional packages to be installed
interactively from within the Doppio interface.

RELION
^^^^^^

Required for many Doppio jobs, which all generally include "RELION" in the name or
description.

We recommend using the latest stable version of RELION 5.0.

**Installation**: https://relion.readthedocs.io/en/release-5.0/Installation.html

Doppio will also work with RELION 4.0. This can be installed on its own, or the copy
included in the CCP-EM v1 20221108 package can be used (see below).

ModelAngelo
^^^^^^^^^^^

Required for the ModelAngelo job.

**Installation**: Doppio can use the copy of ModelAngelo installed along with RELION 5
(see above) or you can install it separately: https://github.com/3dem/model-angelo

CCP4 v9.0
^^^^^^^^^

Provides programs used by the following jobs:

* AceDRG
* Atomic Model Validation
* checkMySequence
* DoubleHelix
* em_placement
* emplace_local
* findMySequence
* ModelCraft
* Molprobity
* Molrep
* Privateer
* Process predicted model
* Refmac Servalcat
* Servalcat difference map
* Servalcat Trim
* Slice

Note that the programs used by some of these jobs can also be installed on their own,
for example by using the `package-ccpem2 <https://gitlab.com/ccpem/package-ccpem2>`_
script.

Also note that some of these jobs require the very latest version of CCP4 (9.0.005, for
the jobs in Doppio 1.2.0). You can update an existing installation by running
``ccp4um``.

**Download** from https://www.ccp4.ac.uk/download

**Installation**: https://www.ccp4.ac.uk/download/installation.html

**Known issues**: https://www.ccp4.ac.uk/download/doc/known_issues_linux.html

CCP-EM v1, build 20221108
^^^^^^^^^^^^^^^^^^^^^^^^^

Required for the following jobs:

* Confidence Map calculation
* CryoEF particle orientation analysis
* Flex-EM
* LAFTER
* ProShade

**Download** the last CCP-EM v1 nightly build for your OS from
https://www.ccpem.ac.uk/download.php

**Installation**
  .. code-block:: bash

    tar -xzf ccpem-20221108-linux-x86_64.tar.gz (or ...-mac-x86_64.tar.gz on Mac) to unpack
    cd ccpem-20221108
    ./install_ccpem.sh
    source setup_ccpem.sh (or setup_ccpem.csh for csh)

**Known issues**
https://www.ccpem.ac.uk/user_help/known_issues.php

Other software
^^^^^^^^^^^^^^

The following programs are also supported. Links and more documentation will be added
soon:

* Cinderella
* crYOLO
* CryoDRGN
* CTFFIND4
* EMDA2
* EMDB Validation Analysis
* Icebreaker
* LocScale
* MotionCor2
* Parakeet
* REPIC
* ResMap
* RIBFIND2.0
* TEMPy2.0
* TEMPy-REFF