Metadata-Version: 2.4
Name: damona
Version: 0.17
Summary: A manager of singularity containers and their singularity recipes (NGS applications)
License: BSD-3
License-File: LICENSE
Keywords: snakemake, sequana, RNAseq, RNADiff, differential analysis
Author: Thomas Cokelaer
Author-email: thomas.cokelaer@pasteur.fr
Requires-Python: >=3.8,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Dist: beautifulsoup4 (>=4.12.3,<5.0.0)
Requires-Dist: click (>=8.1.8,<9.0.0)
Requires-Dist: click-completion (>=0.5.2,<0.6.0)
Requires-Dist: colorlog (>=6.9.0,<7.0.0)
Requires-Dist: easydev (>=0.13.3,<0.14.0)
Requires-Dist: loguru (>=0.7.3,<0.8.0)
Requires-Dist: packaging (>=24.2,<25.0)
Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
Requires-Dist: requests (>=2.32.3,<3.0.0)
Requires-Dist: rich-click (>=1.8.5,<2.0.0)
Requires-Dist: spython (>=0.3.14,<0.4.0)
Requires-Dist: tqdm (>=4.67.1,<5.0.0)
Description-Content-Type: text/x-rst

DAMONA
######


.. image:: https://badge.fury.io/py/damona.svg
    :target: https://pypi.python.org/pypi/damona

.. image:: https://github.com/cokelaer/damona/actions/workflows/main.yml/badge.svg
   :target: https://github.com/cokelaer/damona/actions/workflows/main.yml

.. image:: https://coveralls.io/repos/github/cokelaer/damona/badge.svg?branch=master
    :target: https://coveralls.io/github/cokelaer/damona?branch=master

.. image:: http://readthedocs.org/projects/damona/badge/?version=latest
    :target: http://damona.readthedocs.org/en/latest/?badge=latest
    :alt: Documentation Status

.. image:: https://zenodo.org/badge/282275608.svg
   :target: https://zenodo.org/badge/latestdoi/282275608

.. image:: https://static.pepy.tech/badge/damona
   :target: https://pepy.tech/project/damona


.. image:: https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C3.11%20%7C3.12-blue.svg
    :target: https://pypi.python.org/pypi/damona
    :alt: Python 3.9 | 3.10 | 3.11 | 3.12

.. image:: https://img.shields.io/github/issues/cokelaer/damona.svg
    :target: https://github.com/cokelaer/damona/issues
    :alt: GitHub Issues

:Python version: Python 3.9, 3.10, 3.11, 3.12
:Source: `https://github.com/cokelaer/damona <https://github.com/cokelaer/damona/>`__
:Documentation: `https://damona.readthedocs.io <https://damona.readthedocs.io>`__
:Issues: `https://github.com/cokelaer/damona/issues <https://github.com/cokelaer/damona/issues>`__
:Platform: Linux with bash, zsh, or fish shell

Overview
========


.. image:: https://raw.githubusercontent.com/cokelaer/damona/refs/heads/main/doc/damona_logo.png
   :target: https://raw.githubusercontent.com/cokelaer/damona/refs/heads/main/doc/damona_logo.png
   :align: right
   :alt: logo
   :width: 300px


**Damona** is a conda-style package and environment manager built on top of
`Apptainer/Singularity <https://apptainer.org>`_ containers. It lets you
install bioinformatics (and other) tools as isolated containers, manage
multiple versions side-by-side, and run them **exactly like any other
command-line tool** — with no dependency conflicts and no root privileges
required.

Think of Damona as *conda for Singularity images*: the same familiar
``create / activate / install`` workflow you already know, but with the
rock-solid isolation and reproducibility that containers provide.

.. note::  As of Jan. 2024, **Damona** ships 117 containers (169 versions),
           providing **575 unique ready-to-use binaries**.

Why Damona?
===========

Managing scientific software is notoriously painful:

- Conda environments break when incompatible packages are installed together.
- Raw Singularity/Apptainer requires verbose ``singularity exec`` invocations
  and manual management of image files.
- Docker is unavailable or restricted on most HPC clusters.

**Damona solves all three problems at once:**

+----------------------------------------------+-------+-------+--------+
| Feature                                      | Conda | Singu-| Damona |
|                                              |       | larity|        |
+==============================================+=======+=======+========+
| Familiar install/activate workflow           | ✔     | ✗     | ✔      |
+----------------------------------------------+-------+-------+--------+
| Tools callable as plain commands             | ✔     | ✗     | ✔      |
+----------------------------------------------+-------+-------+--------+
| Full container isolation (no dep. conflicts) | ✗     | ✔     | ✔      |
+----------------------------------------------+-------+-------+--------+
| No root required                             | ✔     | ✔     | ✔      |
+----------------------------------------------+-------+-------+--------+
| Works on HPC/clusters without Docker         | ✔     | ✔     | ✔      |
+----------------------------------------------+-------+-------+--------+
| Multiple tool versions in separate envs      | ✔     | ✗     | ✔      |
+----------------------------------------------+-------+-------+--------+
| Images shared across environments            | ✗     | ✗     | ✔      |
+----------------------------------------------+-------+-------+--------+
| Central + custom registries                  | ✔     | ✗     | ✔      |
+----------------------------------------------+-------+-------+--------+

Key strengths at a glance
--------------------------

* **One command to install** — ``damona install bwa`` downloads the container
  *and* creates a wrapper script so that ``bwa`` just works in your shell.
* **Zero dependency conflicts** — every tool runs inside its own container,
  completely isolated from everything else on the system.
* **No root, no Docker** — Apptainer/Singularity runs fully unprivileged,
  making Damona ideal for shared HPC clusters where Docker is not available.
* **Multiple versions, one system** — need BWA 0.7.17 in one pipeline and
  BWA 0.7.18 in another? Create two Damona environments and switch instantly.
* **Images are shared** — re-installing a tool in a second environment reuses
  the already-downloaded image, saving disk space and time.
* **Reproducible by design** — pin exact versions in an environment file and
  export/import it to reproduce results anywhere.
* **Custom registries** — host your own registry to distribute in-house
  containers to your team, just like a private conda channel.


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

**Step 1 — Install Apptainer**

Damona is a manager for Apptainer/Singularity images, so Apptainer must be
present on your system first. Follow the official
`Apptainer installation guide <https://apptainer.org/docs/admin/main/installation.html>`_,
or — if you already use conda — install it with::

    conda install -c conda-forge apptainer

**Step 2 — Install Damona**

::

    pip install damona

**Step 3 — Initialise Damona**

Run ``damona`` once to create the configuration directory and shell helpers::

    damona

Follow the on-screen instructions. To make the shell integration permanent,
add **one** of the following lines to your shell start-up file:

*bash* — add to ``~/.bashrc``::

    source ~/.config/damona/damona.sh

*zsh* — add to ``~/.zshrc``::

    source ~/.config/damona/damona.zsh

*fish* — add to ``~/.config/fish/config.fish``::

    source ~/.config/damona/damona.fish

Then **open a new shell** and run ``damona`` again. You should see the help
screen:

.. image::  https://raw.githubusercontent.com/cokelaer/damona/refs/heads/main/doc/_static/cli.png

Quick Start
===========

The full workflow takes under a minute:

.. code-block:: bash

    # 1. Create a named environment
    damona create TEST

    # 2. Activate it (installed tools go here)
    damona activate TEST

    # 3. Install a tool — container + wrapper created automatically
    damona install fastqc:0.11.9

    # 4. Use it just like any other command
    fastqc --help

    # 5. Rename or remove the environment when you're done
    damona rename TEST --new-name prod
    damona delete prod

For more examples see the `User Guide <https://damona.readthedocs.io>`_.

Motivation
==========

`Conda/Bioconda <https://bioconda.github.io>`_ is excellent for distributing
pre-compiled scientific software, but dependency conflicts are a real-world
problem: installing one package can silently break another, and rebuilding
environments is time-consuming.

`Singularity/Apptainer <https://apptainer.org>`_ solves the isolation problem
perfectly — each image is self-contained and reproducible — but using it
directly requires verbose ``singularity exec`` commands and manual bookkeeping
of image files and wrapper scripts.

**Damona bridges the gap**: it wraps Singularity images in the familiar
conda-style environment model so that containers are as easy to install,
activate, and use as conda packages, while retaining full container isolation
and reproducibility.

Damona was originally developed for the
`Sequana project <https://sequana.readthedocs.io>`_, but it is completely
general-purpose and can be used to distribute any Singularity-compatible
software.


Commands (Full CLI Reference)
=============================

Run ``damona --help`` to see all available commands::

    activate    Activate a damona environment.
    clean       Remove orphan images and binaries from all environments.
    create      Create a new environment
    deactivate  Deactivate the current Damona environment.
    delete      Remove an environment
    env         List all environments with some stats.
    export      Create a bundle of a given environment.
    info        Print information about a given environment.
    install     Download and install an image and its binaries.
    list        List all packages that can be installed
    remove      Remove binaries or image from an environment.
    rename      Rename an existing environment
    search      Search for a container or binary.
    stats       Get information about Damona images and binaries

For command-specific help (e.g. ``install``)::

    damona install --help


1. List available environments
-------------------------------

By default there is one environment called **base**. Unlike conda's **base**,
it is not essential and may be altered freely (but it cannot be removed or
re-created). List all environments with::

    damona env

2. Create environments
-----------------------

All environments are stored in *~/.config/damona/envs/*. Create a new one::

    damona create TEST

Verify it was created::

    damona env

The last line should confirm that **TEST** is the current environment.

3. Activate and deactivate environments
----------------------------------------

Activating an environment appends its *bin* directory to your ``$PATH``::

    damona activate TEST
    damona env        # confirms TEST is active

Deactivating removes it from ``$PATH``::

    damona deactivate TEST

Multiple environments can be active simultaneously; they follow a
Last-In-First-Out order when deactivated without a name::

    damona activate base
    damona activate TEST
    damona deactivate           # removes TEST (last activated)
    damona deactivate base      # removes base by name

4. Install a tool
------------------

With the target environment active, install any available package::

    damona install fastqc:0.11.9

Damona downloads the Singularity image, registers it in
*~/.config/damona/images* (shared by all environments), and creates a
wrapper script so that ``fastqc`` is available as a plain command.

5. Inspect an environment
--------------------------

List the binaries installed in an environment together with the underlying
images::

    damona info TEST

6. Search the registry
-----------------------

Search for available packages::

    damona search PATTERN

Search an external registry (e.g. the official Damona registry)::

    damona search fastqc --url damona

The ``damona`` URL alias is pre-configured in
*~/.config/damona/damona.cfg*. You can add your own registry URLs there to
distribute in-house containers.

7. Combine multiple environments
----------------------------------

Images are shared across environments, so re-using an already-downloaded
image in a new environment is instant and costs no extra disk space::

    damona create test1
    damona activate test1
    damona install fastqc:0.11.9   # reuses the cached image

Activate several environments at once to mix tool sets::

    damona activate base
    damona activate test1

For more details see the `User Guide <https://damona.readthedocs.io>`_ and
the `Developer Guide <https://damona.readthedocs.io>`_.


Contributors
============

Maintaining Damona would not have been possible without users and contributors.
Each contribution has been an encouragement to pursue this project. Thanks to all:

.. image:: https://contrib.rocks/image?repo=cokelaer/damona
    :target: https://github.com/cokelaer/damona/graphs/contributors


Changelog
=========

From version 0.16 onwards, we will not mention the new software and their versions
but only changes made to the code itself. Entire list of software is available using
the command::

    damona list

========= ========================================================================
Version   Description
========= ========================================================================
0.17.0    * IMPROVED: rewrite README with clearer value proposition and
            comparison table
          * IMPROVED: add docstrings across core modules; Sphinx docs updated
          * IMPROVED: CLI output now uses rich tables and panels
          * IMPROVED: auto-update shell config files (bash/zsh/fish) on startup
          * FIXED: fish shell activation and PATH propagation
          * FIXED: subprocess-based shell detection replacing env-variable approach
          * FIXED: first-run exit code no longer causes CI failures
          * BUILD: remove sudo requirement from singularity build commands
          * BUILD: add dependency caching to CI workflows
0.16.0    * update precommit to create global registry automatically
0.15.2    * ADDED: purge_haplotigs
          * FIXED: access to online registry (Default behaviour)
0.15.1    * using loguru (tentative). Update to have real 0.15.X version
            0.15.0 is unfortunately is not uploading on pypi....
0.15.0    * biocontainers integrated
          * Fix #35 to have a common registry online. no need to update damona
            anymore.
0.14.7    * ADDED rseqc 5.0.4
          * UPDATED sequana_tools 0.19.1
0.14.6    * UPDATED freebayes to 1.3.9
          * ADDED meme suite 5.5.3
0.14.5    * UPDATED pyproject to use poetry2.0 and drop py3.8 support for py3.12
          * ADDED wget 1.25.4, chromap 0.2.7, qc3c 0.5.0 and pairtools 1.1.2
0.14.4    * UPDATE quast 5.3
          * ADDED RNAfold 2.7.0
          * ADDED pilon 1.24
          * ADDED Mauve 2.4.0
0.14.3    * ADDED pecat 0.0.3, necat 0.0.1, sequana_coverage 0.18
          * ADDED: bcftools 1.16, khmer 2.1.1  tRNAscan_SE 2.0.12
0.14.2    * ADDED: AdapterRemoval, bbmap 39.01, dsrc 2.0.2, lima 2.9.0,
            necat 0.0.1
0.14.1    * ADDED: ragtag 2.1.0, orthofinder 2.5.5, mcl , liftoff 1.6.3
          * Message if version is outdated
0.14      * ADDED: ir v2.8.0, vadr v1.6.4, seaview v5.0.5, repeatmasker 4.0.8
            bandage 0.8.1, rnammer 1.2, miniasm 0.3.0, hmmer 2.3.2 and 3.3.2
            infernal 1.1.5
          * NEW: progress bar for upload
          * CHANGES. fixed sandbox.zenodo upload
          * CHANGES: damona search with container sizes and recommendation
0.13      * Fix insallation of a registered software given a dockerhub link
          * Fix requests limits on zenodo (for the stats)
          * remove URLs section in config (will remove this feature)
          * handle docker:// link properly to pull image from registry
0.12.3    * ADDED dustmasker 1.0.0
          * update art with 2.1.8, 2.3.7, 2.5.8 versions
          * ADDED mosdepth 0.3.8
          * ADDED delly 1.2.6
          * UPDATED micromamba 1.5.8
0.12.2    * ADDED datasets
0.12.1    * ADDED pypolca, sratoolkit
0.12.0    * CORE development: rename zenodo-upload subcommand into upload
          * UPDATE rtools to v1.3.0 to include limma package
0.11.1    * ADD pbsim.
          * UPDATE hifiasm
0.11.0    * add precommit, update to use pyproject
0.10.1    * Fix the get_stats_software wrt new  zenodo API
0.10.0    * ADD zsh support
          * UPDATE flye 2.9.1
          * ADD nanopolish
          * UPDATE remove nanopolish from sequana_tools binaries
0.9.1     * ADD hmmer 3.2.2
          * ADD trinotate 4.0.1
          * ADD transdecode 5.7.0
          * ADD trinity 2.15.1
          * UPDATE bioconvert 1.1.0
          * update bowtie2 2.5.1
0.9.0     * refactorise the command 'env' by splitting into dedicated subcommands
            create, delete, rename. add progress bar when downloading container
          * NEW micromamba image to work as a localimage
          * NEW sequana_minimal package to hold common tools (bwa, samtools,
            kraken, etc)
          * NEW ivarm pangolin, nextclade, subread, mafft packages
          * UPDATE fastp to 0.23.3, gffread to 0.12.7 (3 times lighter).
          * UPDATE sequana_tools to use micromamba (30% lighter)
0.8.4     * fix damona stats command to return unique binaries
          * more recipes and version (e.g. fastqc 0.12.1, graphviz update, etc)
0.8.3     * create registry specifically for the sandbox (for testing)
          * add damona community in the uploads
          * add pbbam, bioconvert, busco, canu, ccs
          * add polypolish, samtools 1.16.1, sequana 0.14.6, flye 2.9, canu 2.1.1
            circlator 1.5.5, hifiasm
0.8.2     * add idr, samtools, homer, bamtools, bedtools, sequana_denovo
          * add seqkit recipe and container
          * add shustring
0.8.1     * Include ability to interact with biocontainers by allowing retrieval
            of all biocontainers docker images using this syntax:
            'damona install biocontainers/xx:1.2.3' Note that although 9000
            containers are available, in practice, only about 1000 dockers are
            on dockerhub, which is already nice :-)
0.8.0     * Fix regression to install a software with its version
0.7.1     * Implement the fish shell
          * add command "damona list"
          * rename recipes/ directory into software/ and created a new library/
            directory for images used as library, that are not installed.
0.7.0     * Check that singularity is installed
          * implement the remove command
            https://github.com/cokelaer/damona/issues/15
          * more recipes cleanup (https://github.com/cokelaer/damona/issues/12)
          * removed damona recipes (pure python package)
          * cleanup all recipes
          * add zenodo stats (for admin)
0.6.0     * add ability to upload images on zenodo. No need for external
            repositories.
          * ability to add/delete a software from different images
          * implement --help for the activate/deactivate (non trivial)
          * add --rename option in 'damona env'
          * 'base' environment is now at the same level as other environments
          * better bash script; no need for DAMONA_EXE variable anymore.
0.5.3     * Fixing config/shell
0.5.2     * add missing shell package
0.5.1     * add DAMONA_SINGULARITY_OPTIONS env variable in the binary
          * Fix the way binaries are found in the releases.
          * new recipes: rtools
          * new releases: sequana_tools_0.10.0
          * Fix shell script to handle DAMONA_EXE variable
0.5.0     * Major refactoring.

            - Simplification of the registries (dropping notion of exe/set
              class
            - Main script should now be fully functional with functional
              activation/deactivation.
            - New command to build images from local recipes or dockerhub
              entries.
            - Install command can now install local container.
            - DAMONA_PATH can be set to install damona images/binaries
              anywhere, not just in local home.
            - check md5 of images to not download/copy again
0.4.3     * Implement damona activate/deactivate
0.4.2     * Fix typo in the creation of aliases for 'set' containers
0.4.1     * implemented aliases for the --from-url option stored in a
            damona.cfg file
0.4.0     * implemented the 'env' and 'activate' command
          * ability to setup an external registry on any https and retrieve
            registry from there to download external images
0.3.X     * add gffread, rnadiff recipes
0.3.0     * A stable version with documentation and >95% coverage read-yto-use
0.2.3     * add new recipes (rnadiff)
0.2.2     * Download latest if no version provided
          * include *build* command to build image locally
0.2.1     fixed manifest
0.2.0     first working version of damona to pull image locally with binaries
0.1.1     small update to fix RTD, travis, coveralls
0.1       first release to test feasibility of the project
========= ========================================================================

