Skip to main content

Non-Containerized Installation

Use this path when you want to run convert-pheno directly from CPAN, GitHub, or inside your own Perl environment. For most users, installing from CPAN under ~/perl5 is the simplest non-containerized method.

Install System Dependencies​

On Debian-based distributions, install:

sudo apt-get install cpanminus libbz2-dev zlib1g-dev libperl-dev

Also install the following when your install path pulls the full dependency set from cpanfile or Makefile.PL:

sudo apt-get install libssl-dev

In practice, this matters for repository installs such as cpanm --notest --installdeps . and for dependencies like JSONLD, IO::Socket::SSL, and Net::SSLeay.

Install Under ~/perl5​

cpanm --local-lib=~/perl5 local::lib && eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)
cpanm --notest Convert::Pheno
convert-pheno --help

To make the local Perl library persistent across shells:

echo 'eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)' >> ~/.bashrc

To update later:

cpanm Convert::Pheno

Uninstall​

Run the following command from the same Perl environment used to install Convert-Pheno:

cpanm --uninstall Convert::Pheno

This removes Convert-Pheno but leaves shared Perl dependencies installed.

Alternative Installation Paths​

Native Windows with Strawberry Perl

Native Windows support is tested with Strawberry Perl 5.40 and 5.42. The current CPAN release of Net::IDN::Encode, an indirect dependency of JSON::Validator, does not build with these Perl versions. Until a compatible release reaches CPAN, install the upstream patch before Convert-Pheno:

$netIdnPatch = 'https://github.com/ernix/Net-IDN-Encode/archive/3ebe6f2e239b470efcb64a044edc8202798188af.tar.gz'
cpanm --notest $netIdnPatch
cpanm --notest Convert::Pheno
convert-pheno --help

This dependency supports internationalized domain-name validation; it is not used by the conversion logic itself.

CPAN inside a Conda environment

This path is useful when you want an isolated environment but still want to run the non-containerized CLI or Perl module.

The following Miniconda example targets x86_64 Linux systems:

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

Close and reopen the terminal after the installer finishes. Then configure the Bioconda channel:

conda config --add channels bioconda

Install into a fresh environment to reduce dependency conflicts:

conda create -n myenv
conda activate myenv
conda install -c conda-forge gcc_linux-64 perl perl-app-cpanminus
# conda install -c bioconda perl-mac-systemdirectory   # macOS only
cpanm --notest Convert::Pheno
convert-pheno --help

Replace myenv with your preferred environment name. To deactivate it:

conda deactivate
Install the latest version directly from GitHub

If you want the latest GitHub version without keeping an editable checkout, cpanm can install directly from the repository URL:

cpanm --notest https://github.com/CNAG-Biomedical-Informatics/convert-pheno.git
convert-pheno --help
Developer checkout

Use a full clone when you want to inspect the source, run tests, or edit the code locally:

git clone https://github.com/cnag-biomedical-informatics/convert-pheno.git
cd convert-pheno

Update an existing clone:

git pull

Install dependencies under ~/perl5:

cpanm --local-lib=~/perl5 local::lib && eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)
cpanm --notest --installdeps .
bin/convert-pheno --help

If this step fails in Net::SSLeay, IO::Socket::SSL, or JSONLD, make sure libssl-dev is installed and rerun it.

Persist the local Perl library:

echo 'eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)' >> ~/.bashrc

Optional Athena-OHDSI Database​

OMOP output requires the current ohdsi.db; OMOP input can also use it when a concept is absent from the supplied CONCEPT table. The database is approximately 3.2 GB and includes the concept domains, standard-concept status, and Maps to relationships needed for safe OMOP concept resolution. Older four-column copies are not compatible.

Download and configure ohdsi.db

You can either download it manually in a browser from this Google Drive directory:

or download the file from the command line with gdown:

pip install gdown
import gdown

url = "https://drive.google.com/uc?export=download&id=1zQ26Q1qsqTBPDGrtZbhDP-85NhaOrfBP"
output = "./ohdsi.db"
gdown.download(url, output, quiet=False)

Once downloaded, either:

  1. Move ohdsi.db into share/db/v0/, the bundle currently selected by share/db/manifest.json.
  2. Keep it elsewhere and pass its containing directory with --path-to-ohdsi-db.