#!/usr/bin/env perl
#
#   A script that performs semantic similarity in PXF|BFF data structures
#
#   Last Modified: Aug/09/2024
#
#   $VERSION taken from Pheno::Ranker
#
#   Copyright (C) 2023-2024 Manuel Rueda - CNAG (manuel.rueda@cnag.eu)
#
#   License: Artistic License 2.0
#
#   If this program helps you in your research, please cite.

package main;

use strict;
use warnings;
use autodie;
use feature qw(say);
use Getopt::Long qw(:config no_ignore_case);
use Pod::Usage;
use Data::Dumper;
use Sys::Hostname;
use POSIX qw(strftime);
use Term::ANSIColor qw(:constants);
use File::ShareDir::ProjectDistDir qw(dist_dir);
use FindBin qw($Bin);
use lib "$Bin/../lib";
use Pheno::Ranker qw($VERSION write_json);

# Defining a few variables
my $out_file_cohort      = 'matrix.txt';
my $out_file_patient     = 'rank.txt';
my $out_file_graph       = 'graph.json';
my $out_file_graph_stats = 'graph_stats.txt';
my $export_basename      = 'export';
my $align_basename       = 'alignment';
my $log_file             = 'pheno-ranker-log.json';
my $color                = 1;
my $age                  = 0;
my $cli                  = 1;

# Reading arguments
GetOptions(
    'reference|r=s{1,}'              => \my @reference_files,             # array
    'target|t=s'                     => \my $target_file,                 # string
    'weights|w=s'                    => \my $weights_file,                # string
    'append-prefixes=s{1,}'          => \my @append_prefixes,             # array
    'out-file|o=s'                   => \my $out_file_arg,                # string
    'max-out:i'                      => \my $max_out,                     # integer
    'max-number-var:i'               => \my $max_number_var,              # integer
    'include-hpo-ascendants'         => \my $include_hpo_ascendants,      # flag
    'export|e:s'                     => \my $export,                      # opt-string (defined)
    'align|a:s'                      => \my $align,                       # opt-string (defined)
    'cytoscape-json:s'               => \my $cytoscape_json,              # opt-string (defined)
    'graph-stats:s'                  => \my $graph_stats,                 # opt-string (defined)
    'sort-by=s'                      => \my $sort_by,                     # string
    'similarity-metric-cohort=s'     => \my $similarity_metric_cohort,    # string
    'patients-of-interest|poi=s{1,}' => \my @patients_of_interest,        # array
    'poi-out-dir=s'                  => \my $poi_out_dir,                 # string
    'include-terms=s{1,11}'          => \my @include_terms,               # array
    'exclude-terms=s{1,11}'          => \my @exclude_terms,               # array
    'config=s'                       => \my $config_file,                 # string
    'age!'                           => \$age,                            # flag
    'help|?'                         => \my $help,                        # flag
    'log:s'                          => \my $log,                         # opt-string (defined)
    'man'                            => \my $man,                         # flag
    'debug=i'                        => \my $debug,                       # integer
    'verbose|'                       => \my $verbose,                     # flag
    'color!'                         => \$color,                          # flag
    'version|V'                      => sub { say "$0 Version $VERSION"; exit; }
) or pod2usage(2);
pod2usage(1)                              if $help;
pod2usage( -verbose => 2, -exitval => 0 ) if $man;
pod2usage(
    -message => "Please specify a reference-cohort(s) with <--r>\n",
    -exitval => 1
) unless @reference_files;
pod2usage(
    -message =>
      "<--graph_stats> only works in conjunction with <--cytoscape-json>\n",
    -exitval => 1
) if ( defined $graph_stats && !defined $cytoscape_json );
pod2usage(
    -message =>
      "Weights file <$weights_file> does not exist\n",
    -exitval => 1
) if ( defined $weights_file && !-f $weights_file );

# Set the name of the output
my $out_file = $out_file_arg
  // ( $target_file ? $out_file_patient : $out_file_cohort );

# Set cytoscape-json logic
handle_option( \$cytoscape_json, "<--cytoscape-json> only works in cohort-mode",
    $target_file, $out_file_graph );

# Set graph-stats logic
handle_option( \$graph_stats, "<--graph-stats> only works in cohort-mode",
    $target_file, $out_file_graph_stats );

# Turning color off if argument <--no-color>
$ENV{'ANSI_COLORS_DISABLED'} = 1 unless $color;

# Start printing to STDOUT
say BOLD CYAN program_header($VERSION), RESET if $verbose;

######################
# START PHENO-RANKER #
######################

# Load data as hashref
my $data = {
    reference_files          => \@reference_files,
    target_file              => $target_file,
    weights_file             => $weights_file,
    include_hpo_ascendants   => $include_hpo_ascendants,
    hpo_file                 => undef,
    align                    => $align,
    align_basename           => $align_basename,
    export                   => $export,
    export_basename          => $export_basename,
    out_file                 => $out_file,
    cytoscape_json           => $cytoscape_json,
    graph_stats              => $graph_stats,
    max_out                  => $max_out,
    max_number_var           => $max_number_var,
    sort_by                  => $sort_by,
    similarity_metric_cohort => $similarity_metric_cohort,
    patients_of_interest     => \@patients_of_interest,
    poi_out_dir              => $poi_out_dir,
    include_terms            => \@include_terms,
    exclude_terms            => \@exclude_terms,
    config_file              => $config_file,
    age                      => $age,                        # Solution, use ageRange in PXF/BFF, measures' values more difficult
    cli                      => $cli,
    append_prefixes          => \@append_prefixes,
    log                      => $log,
    debug                    => $debug,
    verbose                  => $verbose
};

# Create object
my $ranker = Pheno::Ranker->new($data);

# Run method
$ranker->run();

# Create log if <--log>
write_log( $log ? $log : $log_file, $data, $VERSION )
  if defined $log;

####################
# END PHENO-RANKER #
####################

sub handle_option {

    my ( $option_ref, $message, $target_file, $default ) = @_;
    if ( defined $$option_ref ) {
        pod2usage( -message => $message, -exitval => 1 ) if $target_file;
        $$option_ref = $$option_ref ? $$option_ref : $default;
    }
}

sub write_log {

    my ( $log, $data, $VERSION ) = @_;

    # NB: Darwin does not have nproc to show #logical-cores, using sysctl instead
    my $os = $^O;
    chomp(
        my $ncpuhost =
          lc($os) eq 'darwin' ? qx{/usr/sbin/sysctl -n hw.logicalcpu}
        : $os eq 'MSWin32' ? qx{wmic cpu get NumberOfLogicalProcessors}
        :                    qx{/usr/bin/nproc} // 1
    );

    # For the Windows command, the result will also contain the string
    # "NumberOfLogicalProcessors" which is the header of the output.
    # So we need to extract the actual number from it:
    if ( $os eq 'MSWin32' ) {
        ($ncpuhost) = $ncpuhost =~ /(\d+)/;
    }
    $ncpuhost = 0 + $ncpuhost;    # coercing it to be a number

    my $info = {
        date      => ( strftime "%a %b %e %H:%M:%S %Y", localtime ),
        ncpuhost  => $ncpuhost,
        hostname  => hostname,
        id        => time . substr( "00000$$", -5 ),                   # string
        version   => $VERSION,
             user => $ENV{'LOGNAME'}
          || $ENV{'USER'}
          || $ENV{'USERNAME'}
          || 'dummy-user'
    };

    # Saving file
    say BOLD GREEN "Writing <$log> file\n" if $data->{verbose};
    write_json(
        {
            filepath => $log,
            data     => { info => $info, data => $data }
        }
    );
}

sub program_header {

    my $VERSION = shift;
    my $str     = <<EOF;
****************************************
*   Rank against cohort(s) (BFF/PXF)   *
*          - PHENO-RANKER -            *
*          Version: $VERSION              *
*   (C) 2023-2024 Manuel Rueda, PhD    *
*       The Artistic License 2.0       *
****************************************
EOF
    return $str;
}

=head1 NAME

pheno-ranker: A script that performs semantic similarity in PXF/BFF data structures and beyond (JSON|YAML)

=head1 SYNOPSIS

 pheno-ranker -r <individuals.json> -t <patient.json> [-options]

   Arguments:
     * Cohort mode:
       -r, --reference <file>         BFF/PXF file(s) in JSON or YAML format (array or object)

     * Patient mode:
       -t, --target <file>            BFF/PXF file in JSON or YAML format (object or array of 1 object)

   Options:
     -age                             Include age-related variables; excludes agent-like terms (BFF/PXF-only) [>no-age|age]
     -a, --align [path/basename]      Write alignment file(s). If not specified, default filenames are used [default: alignment.*]
     -append-prefixes <prefixes>      Prefixes for primary_key when #cohorts >= 2 [default: C]
     -config <file>                   YAML config file to modify default parameters [default: share/conf/config.yaml]
     -cytoscape-json [file]           Serializes the pairwise comparison matrix as an undirected graph in JSON, compatible with Cytoscape [default: graph.json]
     -e, --export [path/basename]     Export miscellaneous JSON files. If not specified, default filenames are used [default: export.*]
     -exclude-terms <terms>           Exclude BFF/PXF terms (e.g., --exclude-terms sex, id)
     -graph-stats [file]              Generates a text file with key graph metrics, for use with <-cytoscape-json> [default: graph_stats.txt]
     -include-hpo-ascendants          Include ascendant terms from the Human Phenotype Ontology (HPO)
     -include-terms <terms>           Include BFF/PXF terms (e.g., --include-terms diseases)
     -max-number-var <number>         Maximum variables for binary string [default: 10000]
     -max-out <number>                Print only N comparisons [default: 50]
     -o, --out-file <file>            Output file path [default: -r matrix.txt | -t rank.txt]
     -poi, --patients-of-interest <id_list>   Export JSON files for the selected individual IDs during a dry-run
     -poi-out-dir <directory>         Directory for JSON files (used with --poi)
     -similarity-metric-cohort <metric>  Similarity metric for cohort mode [>hamming|jaccard]
     -sort-by <metric>                Sort by Hamming distance or Jaccard index [>hamming|jaccard]
     -w, --weights <file>             YAML file with weights

   Generic Options:
     -debug <level>                   Print debugging (from 1 to 5, being 5 max)
     -h, --help                       Brief help message
     -log                             Save log file [default: pheno-ranker-log.json]
     -man                             Full documentation
     -no-color                        Toggle color output [>color|no-color]
     -v, --verbose                    Verbosity on
     -V, --version                    Print version

=head1 DESCRIPTION

pheno-ranker: A script that performs semantic similarity in PXF/BFF data structures and beyond (JSON|YAML)

The script also accepts CSV files that have been pre-processed using the C<csv2pheno-ranker> utility (included).

=head1 SUMMARY

Pheno-Ranker is a lightweight and easy to install tool specifically designed for performing semantic similarity analysis on phenotypic data structured in JSON format, such as Beacon v2 Models or Phenopackets v2.

=head1 INSTALLATION

=head2 Non containerized

The script runs on command-line Linux and it has been tested on Debian/RedHat/macOS based distributions (only showing commands for Debian). Perl 5 is installed by default on Linux, 
but we will install a few CPAN modules with C<cpanminus>.

=head3 Method 1: From CPAN

First install system level dependencies:

  sudo apt-get install cpanminus libperl-dev

Now you have to choose between one of the 2 options below:

B<Option 1:> System-level installation:

  cpanm --notest --sudo Pheno::Ranker
  pheno-ranker -h

B<Option 2:> Install Pheno-Ranker and the dependencies at C<~/perl5>

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

To ensure Perl recognizes your local modules every time you start a new terminal, you should type:

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

=head3 Method 2: From CPAN in a CONDA environment

Please follow L<these instructions|https://cnag-biomedical-informatics.github.io/pheno-ranker/download-and-installation/#__tabbed_1_2>.

=head3 Method 3: From GitHub

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

Install system level dependencies:
  
  sudo apt-get install cpanminus libperl-dev

Now you have to choose between one of the 2 options below:

B<Option 1:> Install dependencies (they're harmless to your system) as C<sudo>:

  cpanm --notest --sudo --installdeps .
  bin/pheno-ranker --help            

B<Option 2:> Install the dependencies at C<~/perl5>:

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

To ensure Perl recognizes your local modules every time you start a new terminal, you should type:

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

I<Optional:> If you want to use C<utils/barcode> or C<utils/bff_pxf_plot>:

  sudo apt-get install python3-pip libzbar0
  pip3 install -r requirements.txt

=head2 Containerized

=head3 Method 4: From Docker Hub

Download a docker image (latest version - amd64|x86-64) from L<Docker Hub|https://hub.docker.com/r/manuelrueda/pheno-ranker> by executing:

  docker pull manuelrueda/pheno-ranker:latest
  docker image tag manuelrueda/pheno-ranker:latest cnag/pheno-ranker:latest

See additional instructions below.

=head3 Method 5: With Dockerfile

Please download the C<Dockerfile> from the repo:

  wget https://raw.githubusercontent.com/cnag-biomedical-informatics/pheno-ranker/main/Dockerfile

And then run:

  # Docker Version 19.03 and Above (Supports buildx)
  docker buildx build -t cnag/pheno-ranker:latest .

  # Docker Version Older than 19.03 (Does Not Support buildx)
  docker build -t cnag/pheno-ranker:latest .

=head3 Additional instructions for Methods 4 and 5

To run the container (detached) execute:

  docker run -tid -e USERNAME=root --name pheno-ranker cnag/pheno-ranker:latest

To enter:

  docker exec -ti pheno-ranker bash

The command-line executable can be found at:

  /usr/share/pheno-ranker/bin/pheno-ranker

The default container user is C<root> but you can also run the container as C<$UID=1000> (C<dockeruser>). 

  docker run --user 1000 -tid --name pheno-ranker cnag/pheno-ranker:latest
 
=head3 Mounting volumes

Docker containers are fully isolated. If you need the mount a volume to the container please use the following syntax (C<-v host:container>). 
Find an example below (note that you need to change the paths to match yours):

  docker run -tid --volume /media/mrueda/4TBT/data:/data --name pheno-ranker-mount cnag/pheno-ranker:latest

Then I will do something like this:

  # First I create an alias to simplify invocation (from the host)
  alias pheno-ranker='docker exec -ti pheno-ranker-mount /usr/share/pheno-ranker/bin/pheno-ranker'

  # Now I use the alias to run the command (note that I use the flag --o to specify the filepath)
  pheno-ranker -r /data/individuals.json -o /data/matrix.txt

=head3 System requirements

  * Ideally a Debian-based distribution (Ubuntu or Mint), but any other (e.g., CentOS, OpenSUSE) should do as well.
    (It should also work on macOS and Windows Server, but we are only providing information for Linux here)
  * Perl 5 (>= 5.26 core; installed by default in most Linux distributions). Check the version with "perl -v".
  * >= 4GB of RAM
  * 1 core
  * At least 16GB HDD

=head1 HOW TO RUN PHENO-RANKER

For executing pheno-ranker you will need a PXF/BFF file(s) in JSON|YAML format. The reference cohort must be a JSON array, where each individual data are consolidated in one object.

You can download examples from L<this location|https://github.com/CNAG-Biomedical-Informatics/pheno-ranker/tree/main/share/ex>.

There are two modes of operation:

=over 4

=item Cohort mode:
 
B<Intra-cohort:> With C<--r> argument and 1 cohort.

B<Inter-cohort:> With C<--r> and multiple cohort files. It can be used in combination with C<--append-prefixes> to add prefixes to each individual id.

=item Patient Mode:

With C<-r> reference cohort(s) and C<--t> patient data.

=back

B<Examples:>

 $ ./pheno-ranker -r phenopackets.json  # intra-cohort

 $ ./pheno-ranker -r phenopackets.yaml -o my_matrix.txt # intra-cohort

 $ ./pheno-ranker -r phenopackets.json -w weights.yaml --exclude-terms sex ethnicity exposures # intra-cohort with weights

 $ $path/pheno-ranker -r individuals.json others.yaml --append-prefixes CANCER CONTROL  # inter-cohort

 $ $path/pheno-ranker -r individuals.json -t patient.yaml -max-out 100 # mode patient


=head2 COMMON ERRORS AND SOLUTIONS

 * Error message: R plotting
     Error in scan(file = file, what = what, sep = sep, quote = quote, dec = dec,  : 
     line 1 did not have X elements
     Calls: as.matrix -> read.table -> scan
     Execution halted
   Solution: Make sure that the values of your primary key (e.g., "id") do not contain spaces (e.g., "my fav id" must be "my_fav_id")

 * Error message: Foo
   Solution: Bar

=head1 CITATION

The author requests that any published work that utilizes C<Pheno-Ranker> includes a cite to the following reference:

Leist, I.C. et al., (2024). Pheno-Ranker: A Toolkit for Comparison of Phenotypic Data Stored in GA4GH Standards and Beyond. I<Submitted>.

=head1 AUTHOR 

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

=head1 COPYRIGHT AND LICENSE

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

=cut
