oicr-gsi / djerba

Create cancer bioinformatics reports from metadata and workflow output

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.

Documentation

• This document is intended as a very brief introduction to Djerba.
• The main site for Djerba documentation is ReadTheDocs.
• A general overview is given by slides from a talk on Djerba by Iain Bancarz at CGC 2023 on 2023-08-14.

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-2024 by Genome Sequence Informatics, Ontario Institute for Cancer Research.

Licensed under the GPL 3.0 license.

djerba's Issues

COLO829 demo

This issue is to track and discuss any install/run issues related to the COLO829 cross-site demo of the wgts.snv_indel plugin.

Djerba plug-in early access

Please comment here to express interest in Djerba plug-ins, due for launch in September 2023.

Hello from CGC!

Hello!

It was so nice to meet you all at the CGC conference! I loved your presentations and your work, both with the laboratory as a whole and this project. Iain definitely has left me feeling inspired with plugin-centric development (p.s. Iain, you may find Obsidian to be neat).

Feel free to close this Issue whenever you want, I just wanted to initiate staying in touch. You can reach me at breardon [at] broadinstitute.org. Enjoy the rest of your summer!

Brendan