Converting pheno-clinical data to 2D-barcodes
- Explanation
- Usage
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)
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.
- From Pheno-Ranker to QR
- From QR to Pheno-Ranker
- From Pheno-Ranker to PDF
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
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:
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 BFF and PXF files.
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
HOW TO RUN
When you run pheno-ranker use the flag --e. This will export the following files:
export.glob_hash.jsonexport.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
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.