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 repors (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

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
  • ...

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.