Converting pheno-clinical data to 2D-barcodes

Encode analysis profiles as QR images, decode them with the matching variable template, or create PDF research reports. These operations are available in Desktop and as standalone utilities.

Experimental feature

QR images encode analysis data, not the complete original record. Decoding requires the matching variable template. Compression is not encryption: treat QR images, templates, and decoded reports as potentially sensitive data.

Usage

Desktop

1. Open Tools > Encode QR codes and select a completed analysis with intermediate exports, or supply its exported binary vectors.
2. Browse the resulting QR images. To decode an image, use Decode QR codes with the matching global-variable template from the same analysis.
3. Use PDF reports to create reports from decoded records and their matching QR images. Label hints use the matching analysis exports and enrich the PDF only; they do not change the decoded JSON or QR payload.

Keep each QR set with its original template. An unrelated template cannot reliably recover the variables represented by the encoded positions.

CLI

Explanation

As a proof of concept, we created companion command-line utilities that encode/decode the Pheno-Ranker format to QR codes.

About the utility of QR codes

QR codes can attach an encoded profile to a report or transfer it between controlled systems. Possible uses include:

• Enrolling in a clinical trial or health data program
• Transferring information between a patient and doctor
• Medical reports with augmented data
• Clinical trial reports (see example below)

From Pheno-Ranker to QR

The first thing is to run Pheno-Ranker with your data, but using the flag --export:

./pheno-ranker -r individuals.json --export my_export_name

This will create a set of files, including my_export_name.glob_hash.json and my_export_name.ref_binary_hash.json.

Now you can run the following command:

./pheno-ranker2barcode -i my_export_name.ref_binary_hash.json -o my_fav_dir --no-compress

About compression

If you don't include the --no-compress option, by default the binary digit string will be compressed using zlib and then encoded in base64. This reduces the string size, allowing more variables to be encoded in the QR code.

This will create 1 png image (inside my_fav_dir) for each individual in individuals.json. Like this one:

QR code from Pheno-Ranker

From QR to Pheno-Ranker

To decode a QR into Pheno-Ranker original format use the following:

./barcode2pheno-ranker -i my_fav_dir/*png -t my_export_name.glob_hash.json -o individuals.qr.json 

Do I retrieve all my data back?

You will access the data used by Pheno-Ranker to encode that patient. For example, using PXF, you won't receive labels. The filtering behavior is determined by the configuration file.

From Pheno-Ranker to PDF

pheno-ranker2pdf creates a research report from decoded BFF or PXF data, with a QR code, phenotype overview, and separate sections for each record field. The Pheno-Ranker logo is included by default; use --logo to replace it.

About the QR code

Please note that the QR code has to match the JSON file from which it was created.

./pheno-ranker2pdf -j individuals.qr.json -q my_fav_dir/*png -t bff \
  --template my_export_name.glob_hash.json --labels my_export_name.labels.json \
  -o my_pdf_dir

The optional --labels and matching --template add missing ontology names in a Label hint column beside the corresponding IDs. Hints are resolved from active positions in the same analysis's binary vector, not by matching names. The decoded JSON and QR payload are unchanged. Omit both arguments to report only the decoded data. These reports are descriptive, not diagnostic interpretations.

First page of the v1.09 report, generated from the repository's BFF example.

Open the complete example PDF

CLI usage

View source README

HOW TO RUN

When you run pheno-ranker use the flag --e. This will export the following files:

• export.glob_hash.json
• export.ref_binary_hash.json
• ...

See also this link.

pheno-ranker2barcode

usage: pheno-ranker2barcode [-h] -i INPUT [-o OUTPUT] [--no-compress]

Generate QR codes from JSON data.

options:
  -h, --help            show this help message and exit
  -i INPUT, --input INPUT
                        Input JSON file path
  -o OUTPUT, --output OUTPUT
                        Output directory for QR codes
  --no-compress         Disable compression of the binary digit string

Example:

./pheno-ranker2barcode -i export.ref_binary_hash.json -o my_out_dir

barcode2pheno-ranker

usage: barcode2pheno-ranker [-h] -i INPUT [INPUT ...] -t TEMPLATE [-o OUTPUT]

Decode QR codes to JSON format.

options:
  -h, --help            show this help message and exit
  -i INPUT [INPUT ...], --input INPUT [INPUT ...]
                        Input PNG files (e.g., "image1.png image2.png")
  -t TEMPLATE, --template TEMPLATE
                        JSON template file
  -o OUTPUT, --output OUTPUT
                        Output JSON file

Example:

./barcode2pheno-ranker -i my_out_dir/*png -t export.glob_hash.json -o output.json

pheno-ranker2pdf

usage: pheno-ranker2pdf [-h] -j JSON -q QR [QR ...] [-o OUTPUT] -t {bff,pxf}
                      [-l LOGO] [--labels LABELS] [--template TEMPLATE] [--test]

Convert JSON data to a formatted PDF file.

options:
  -h, --help            show this help message and exit
  -j JSON, --json JSON  Path to the JSON file.
  -q QR [QR ...], --qr QR [QR ...]
                        Path to the QR code images, use space to separate multiple files.
  -o OUTPUT, --output OUTPUT
                        Output directory for PDF files. Default: pdf
  -t {bff,pxf}, --type {bff,pxf}
                        Type of data processing required.
  -l LOGO, --logo LOGO  Custom logo image (default: Pheno-Ranker logo).
  --labels LABELS       Optional export.labels.json[.gz] for missing ontology labels.
  --template TEMPLATE   Matching export.glob_hash.json; required with --labels.
  --test                Enable test mode (does not print date to PDF).

Example:

./pheno-ranker2pdf -j output.json -q qr_codes/*png -t bff -o my_pdf_dir

INSTALLATION

It should work out of the box with the containerized version. Otherwise:

sudo apt-get install libzbar0
pip install qrcode[pil] Pillow pyzbar pandas reportlab

TESTING

Core Python helpers can be tested without generating or decoding QR images:

python3 -m unittest discover -s utils/barcode/tests -v

End-to-end barcode CLI tests are kept as local tests because they require Python packages and the system zbar library:

prove -lv xt/barcode.t

AUTHOR

Written by Manuel Rueda, PhD. Info about CNAG can be found at https://www.cnag.eu.

COPYRIGHT AND LICENSE

This Python file is copyrighted. See the LICENSE file included in this distribution.