Skip to content

Converting pheno-clinical data to 2D-barcodes

As a proof of concept, we created an utility that encodes/decodes the Pheno-Ranker format to QR codes.

About the utility of QR codes

2D barcodes are straightforward and easy to scan, typically using a smartphone camera. They offer the convenience of encoding various data. Below are a few examples:

  • Enrolling in clinical trial or health data program via QR
  • Patient-doctor transfer of information
  • Medical reports with augmented data
  • Clinical trials reports (see example below)

Of course if you plan to use Pheno-Ranker with non pheno-clinical data you will need to come up with your own examples 😄.

Ok, let's convert Pheno-Ranker data to QRs.

Experimental feature

This feature serves as a proof of concept. The generated QR code images exclusively encode Pheno-Ranker data and do not include any clinical information. To decode these images back into phenotypic-clinical data, a specific template is required. In a production environment, implementing an additional security layer, such as AES encryption, is recommended to enhance data safety.

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:

Pheno-Ranker
QR code from 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.

We created a simple utility to create a PDF report from Pheno-Ranker data. It works for BFFand PXF files.

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 --logo my-logo.png -o my_pdf_dir

MoviePackets
Example of Pheno-Ranker report

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] [--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  Path to the logo image.
  --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

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.