Djerba

Modular system to create reports from metadata and workflow output

Introduction

The Djerba software:

• translates cancer bioinformatics workflow outputs and metadata into clinical reports;
• has a modular structure based on plugins;
• is named for an island off the coast of North Africa -- the initial letter D is silent, so it is pronounced "jerba";
• is developed and maintained by the Clinical Genome Informatics (CGI) group at OICR.

Demonstration

• A demonstration fork of Djerba, with full instructions to install and run, is at djerba-demo.

Documentation

• This document is intended as a very brief introduction to Djerba.
• The main site for Djerba documentation is ReadTheDocs.
• Conference talk slides:
  • NEW ISMB 2024 on 2024-07-15: Djerba: Sharing and Updating a Modular System for Clinical Report Generation
  • CGC 2023 on 2023-08-14: Djerba: A Modular System to Generate Clinical Genome Interpretation Reports for Cancer

Structure

Workflow steps

Generating a report with Djerba has the following steps:

1. Configure an INI file
2. Extract metrics to a JSON file
3. Render the JSON to HTML
4. Publish the HTML as PDF

In addition, Djerba supports:

• Archiving the JSON report documents to a CouchDB database.
• Updating a JSON document with revised summary text and/or PHI (as of version 1.3.0).

Software components

Reports are generated by the following types of component:

• Core: Central element of Djerba. Runs other components, as specified in the INI config file, to generate a report.
• Plugin: Main component type. Has its own configure, extract, and render operations.
• Helper: Writes ancillary files for use by plugins.
• Merger: Merges inputs from multiple plugins to generate an HTML section.

The report document is made up of one or more sections, generated by running plugins, helpers, and mergers in a specific order.

Installation and package locations

Djerba is primarily written in Python. It has a setup.py script and can be installed using pip. PDF conversion requires the wkhtmltopdf binary, and individual plugins may have dependencies on other languages such as R.

The Djerba core code is contained in a Python package called djerba. Djerba components (plugins, helpers, and mergers) are also Python packages. As of version 1.6.0, Djerba supports loading components from locations other than the main djerba package.

See ReadTheDocs for details.

History

See the changelog for a detailed development history. In brief:

• 2020-09: Early prototype addressing cBioPortal as well as the CGI clinical reporting format.
• 2021-05: Change of scope to focus exclusively on CGI clinical reports.
• 2022-01: Version 0.1.0. First production release of Djerba for CGI reports.
• 2022-02: Version 0.2.0. Incremental improvements and bugfixes.
• 2022-06: Version 0.3.0. Write reporting data in a machine-readable JSON document. Generate HTML with Mako templates (replacing Rmarkdown).
• 2023-03: Version 0.4.0. Upload the JSON document to a CouchDB database. (Prototyped in version 0.3.15, 2022-12.)
• 2023-11: Version 1.0.0. Major upgrade and refactoring to support a plugin structure.

Copyright and License

Copyright © 2020-2026 by Genome Sequence Informatics, Ontario Institute for Cancer Research.

Licensed under the GPL 3.0 license.