Mini-Djerba¶
Introduction¶
Mini-Djerba allows a clinical geneticist to update personal health information (PHI) and edit the results summary in a Djerba report.
Input to mini-djerba is a file in JSON format containing clinical report data. Filenames are typically of the form [report_id].json
, eg. 100-009-005_LCM3-v1_report.json
.
Steps are as follows:
Render an initial PDF file for inspection
Generate a config file
Edit the config file with PHI values and summary text
Use the config file to generate a new PDF with the updated PHI and summary
Mini-Djerba is distributed as a single, executable file. It is a command-line application; run with -h
for help.
In brief, usage is mini-djerba [mode] [options]
Available modes are:
render
: Make a PDF from JSON input, without any changessetup
: Generate a config file to be updated by the userupdate
: Use the JSON input and config file to generate an updated PDF document
Usage¶
Render initial PDF¶
The render
mode converts a JSON document to PDF format. In other words, it goes from the machine-readable format to human-readable.
Example:
mini-djerba render -j report.json
The default location for output is a PDF file in the current working directory named [report_id].json
.
Generate config file¶
The config file is in MDC (mini-Djerba config) format. This is a simple text-based format defined for mini-Djerba. See the MDC section for details.
The file is generated in setup
mode. The -j
option inserts summary text drafted by a genome interpreter, for subsequent editing. Running without -j
produces a “blank” MDC file.
Example:
mini-djerba setup -j report.json
Edit config file¶
This can be done in any text editor, eg. nano, Notepad for Windows, Emacs, Vim.
Using a full-featured word processor such as MS Word is unnecessary; if doing so, output must be saved in plain-text format.
See the MDC section for details and an example config file.
Update to produce a new PDF¶
We now bring the input PDF and config file together, to produce an updated report PDF.
Example:
mini-djerba update -j report.json -c config.mdc
This will write a new JSON file with updated PHI and summary text. The default location for output is a PDF file in the current working directory named [report_id].json
.
Note the default is the same as for the render
option in Step 1, so it may overwrite the previous output – but this should not be an issue, as the PDF generated in this step is the version to be uploaded for clinical use.
Additional options¶
For a full listing of command-line options, run with -h
:
mini_djerba -h
mini_djerba render -h
mini_djerba setup -h
mini_djerba update -h
Troubleshooting¶
There are 3 main types of error in mini-Djerba:
Incorrectly formatted MDC file: Check the MDC documentation and try again.
Mismatched plugin versions: Mini-Djerba is built with a self-contained set of Djerba plugins. A Djerba JSON report may have been generated with newer plugin versions than the ones in mini-Djerba; this is cause for a warning, which can be overridden with the
--force
option. Running with mismatched plugin versions will usually work correctly, but may result in errors. Alternatively, upgrade to a newer version of mini-Djerba.Unexpected errors: Mini-Djerba is tested before release, but unexpected errors may occur from time to time.
In the first two cases, mini-djerba
will print an informative error message to the command line. In the third, the error is likely to be more technical. If in doubt, consult the Djerba developers.
The Mini-Djerba config file¶
MDC files (mini-Djerba config, file extension .mdc
) specify the PHI and summary in a compact, text-based format. It is a simple, text-based format developed for Mini-Djerba.
This document describes the current MDC format. See MDC formats for previous specifications.
MDC example¶
Here is an example MDC file with placeholder values:
patient_name = LAST, FIRST
patient_dob = yyyy/mm/dd
patient_genetic_sex = SEX
requisitioner_email = NAME@domain.com
physician_licence_number = nnnnnnnn
physician_name = LAST, FIRST
physician_phone_number = nnn-nnn-nnnn
hospital_name_and_address = HOSPITAL NAME AND ADDRESS
report_signoff_date = 2024/02/13
clinical_geneticist_name = Trevor Pugh, PhD, FACMG
clinical_geneticist_licence = 1027812
###
[Lorem ipsum dolor](https://www.lipsum.com/) sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
MDC Format Specification: Version 2.0¶
The following elements must appear in this order:
A section with exactly 11 entries of the form
key = value
A separator consisting of 3 hash marks:
###
Summary text
The 11 entries correspond to the 8 PHI fields listed above:
patient_name
patient_dob
patient_genetic_sex
requisitioner_email
physician_licence_number
physician_name
physician_phone_number
hospital_name_and_address
report_signoff_date
clinical_geneticist_name
clinical_geneticist_licence
These entries may occur in any order, but must be present and have non-empty values.
Field 9 is filled in with the current date but can be changed by the user.
Summary text must be non-empty. Leading or trailing whitespace will be removed before the text is inserted into the report; but whitespace, including line breaks, may occur within the text block. Formatting with Markdown notation and/or HTML tags is supported. This enables the user to create or edit bold/italic text, hyperlinks, etc.
MDC Version History¶
The MDC file format is versioned. Each version accompanies a release of the main Djerba software.
MDC Version |
Djerba version |
Release date |
---|---|---|
|
|
2024-02-13 |
|
|
2024-01-31 |
The JSON input file¶
The Djerba JSON document is produced as part of the report drafting process by the Clinical Genome Interpretation team. It is a machine-readable file containing the data needed to produce a clinical report.
The JSON is not intended to be edited by hand; mini-Djerba gets the user inputs it needs from the MDC file.
For Developers¶
Build instructions¶
Building mini-Djerba is done with PyInstaller.
Detailed instructions are on the OICR wiki.
Technical notes¶
Key/value parsing is done with the Python configparser package and has similar formatting conventions.
The MDC file format is implemented in Djerba as the mdc class.
Tests are in the TestMDC class.