#!/usr/bin/perl -w
############################################################
#
# $Id: pathway-extractor,v 1.37 2012/09/12 08:19:47 rsat Exp $
#
############################################################

## use strict;

=pod

=head1 Extract Pathway from gene list

=head1 VERSION 1.0

=head1 DESCRIPTION

This tool is a Perl Wrapper around the stand-alone application
(PathwayInference) developed by Karoline Faust.

The PathwayInference tool can also be used via the Web interface
"Pathway Extraction" (http:// rsat.ulb.ac.be/neat).

The Perl wrapper performs several steps to enable the extraction of
pathways from sets of functionally related genes (e.g. co-expressed,
co-regulated, members of the same operon, …).

1. Gene to reaction mapping. Identify the set of reactions ("seed
reactions") catalyzed by the set of input genes ("seed genes"). The
mapping relies on a user-specified file describing the mapping of
genes to reactions (GNN and NNN, Gene-Node Name and Network Node
Name<>NodeID file).

2. Pathway extraction (=Pathway inference). PathwayInference takes as
input a network (typically a metabolic network made of compounds +
reactions) and a set of "seed" nodes. The program attempts to return a
subnetwork that interconnects the seed nodes at a minimal “cost",
where the cost is a weighted sum of the intermediate compounds and
reactions used to link the seed nodes (Faust, et al., 2011; Faust and
van Helden, 2011).

This implementation requires no database or Internet connection and
works with local files only.  The PathwayInference tool wraps a number
of algorithms to infer pathways: k shortest paths (REA), kWalks and a
hybrid approach combining both (Faust, et al., 2010). In addition, two
Steiner tree algorithms are available (Takahashi-Matsuyama and
Klein-Ravi), each of them alone or in combination with kWalks.

=head1 AUTHORS

The java PathwInference tool was developed by Karoline Faust. This
Perl wrapper was developed by Didier Croes. The doc was written by
Didier Croes and Jacques van Helden.

=head1 REFERENCES

Faust, K., Croes, D. and van Helden, J. (2011). Prediction of
metabolic pathways from genome-scale metabolic networks. Biosystems.

Faust, K., Dupont, P., Callut, J. and van Helden, J. (2010). Pathway
discovery in metabolic networks by subgraph extraction. Bioinformatics
26, 1211-8.

Faust, K. and van Helden, J. (2011). Predicting metabolic pathways by
sub-network extraction.  Methods in Molecular Biology in press, 15.

=head1 CATEGORY

Graph tool

=head1 USAGE

pathway_extractor -h -hp [-i inputfile] [-o output_directory] [-v verbosity] \
    -g infile{graph} -a gene2ec -b ec/rxn/cpd2rxnid/cpdid [-d unique_descriptor] [-t temp_directory] [-ecg ECGenericity level] [-show]

=head1 INPUT FORMAT

Warning: the same gene identifiers should be used in all input files.

=head2 1) List of seed genes (gene identifiers):

(Warning at least 2 gene ids must be present in the graph file see
below) in this example we use gene IDs. Beware, the gene IDs must be
compatible with the genome version installed on RSAT. Depending on the
organism source, the IDs can correspond to RefSeq, EnsEMBL, or other
references.

Example of seed gene file:
NP_414739
NP_414740
NP_414741
NP_416617
NP_417417
NP_417481
NP_418232
NP_418272
NP_418273
NP_418373
NP_418374
NP_418375
NP_418376
NP_418437
NP_418443

----------------------------------------------------------------

=head2 2)Graph file format:

see Pathwayinference tools helppathway_extractor

java graphtools.algorithms.Pathwayinference –h

The same result can be obtained by typing

pathway-extractor -hp

----------------------------------------------------------------



=head2 Seed mapping file

The seed mapping file makes the link between different types of seeds
(genes, EC numbers, proteins, compound names) and nodes of the network
(reactions or compounds depending on the seed type).

=head3 Network Node Names (nnn) file (option I<-nnn>)

Mandatory.

The NNN files makes the link between EC numbers/rxn name/cpd name and node id in the network .

These files are used for the reaction ids/compound ids to gene annotation (backward).


=head3 Example of NNN file

 #query  id      qualifier       name
1.-.-.- RXN1G-1486      EC      3-oxo-C78-α-mycolate-reductase
1.-.-.- RXN1G-1527      EC      3-oxo-C85-cis-methoxy-mycolate reductase
1.-.-.- RXN1G-1528      EC      3-oxo-C86-trans-methoxy-mycolate-reductase
10-deoxysarpagine       10-DEOXYSARPAGINE       compounds       10-deoxysarpagine
10-DEOXYSARPAGINE       10-DEOXYSARPAGINE       compounds       10-deoxysarpagine
 ...

=head3 Gene to Node Names (gnn) file (option I<-gnn>)

not mandatory, in this cas the queyr file or stdin must contains only Node Names.

The GNN files makes the link between external identifier and node names (example: gene name, refseq, locuslink) . 


=head3 Example of NNN file

#query	id	qualifier	name	taxonomy_id	species
aas	2.3.1.40	GENE_NAME	aas	83333	Escherichia coli (strain K12)
aas	6.2.1.20	GENE_NAME	aas	83333	Escherichia coli (strain K12)
aat	2.3.2.6	GENE_NAME	aat	83333	Escherichia coli (strain K12)


=head1 EXAMPLES

=head2 With an input file

=head3 Motivation

Get methionine-related genes in Escherichia coli genome. This
generates a file containing one line per gene and one column per
attribute (ID, start, end, name, ...).


=head3 Commands

Extract all E.coli genes whose name starts with met
 gene-info -org Escherichia_coli_K_12_substr__MG1655_uid57779 -feattype CDS -full -q '^met.*' -o met_genes.tab

Select the first column, containing gene Ids.
 grep -v "^;" met_genes.tab | cut -f 1 > met_genes_IDs.txt

Extract a pathway connecting at best the reactions catalyzed by these gene products
  pathway-extractor -i met_genes_IDs.txt \
     -g data/networks/MetaCyc/MetaCyc_directed_141.txt \
     -gnn ${RSAT}/data/metabolic_networks/GER_files/GPR_Uniprot_112011_Escherichia_coli_K12.tab \
     -o result_dir \
     -t temp_dir

----------------------------------------------------------------

=head2 Using standard input

The script pathway-extractor can also use as input the STDIN. This
allows to use it in aconcatenation of commands. For example, all the
commands above could be combined in a single pipeline as follows.

 gene-info -org Escherichia_coli_K_12_substr__MG1655_uid57779 -feattype CDS -q 'met.*' \
   | grep -v "^;" met_genes.tab | cut -f 1 \
   | pathway-extractor -g data/networks/MetaCyc/MetaCyc_directed_141.txt \
       -ger data/networks/MetaCyc/METACYC_GPR_EC_20110620.txt \
       -o result_dir -t temp_dir

----------------------------------------------------------------

=head1 OUTPUT FILES:

*_converted_seeds.txt : pathway inference input file.

*_pred_pathways.txt : result graph file of the pathway inference

*_annot_pred_pathways.txt : : result file of the pathway inference with gene and EC annotation

*_annot_pred_pathways.dot : result file in dot format, which can be converted to a figure using the
automatic layout program dot (included in the software suite graphviz).

*._annot_pred_pathways.png : png image file of the inferred pathway
----------------------------------------------------------------

=cut


BEGIN {
    if ($0 =~ /([^(\/)]+)$/) {
	push (@INC, "$`lib/");
	push (@INC,"$ENV{RSAT}/perl-scripts/lib/");
	push (@INC,"$ENV{RSAT}/perl-scripts/lib/RSAT");
    }
}
require "RSA.lib";
use Getopt::Long;
use RSAT::util;
use RSAT::PathwayExtraction;

################################################################
## pathwayinference package
package main;
{
  #other pathwayinference otptions : specific opions that will be directly pass to the java pathway inference app
  our @pioptions=('-s','-i','-g','-f','-b','-n','-q','-o','-O','-E','-a','-y','-p','-F','-Z','-m','-w','-t',
		  '-l','-T','-W','-P','-C','-e','-d','-u','-x','-k','-U','-B','-r','-D','-M','-I','-N','-G',
		  '-H','-X','-A','-K','-S','-R','-j','-J','-Q','-L','-Y','-v','-h','-V');
  our @piflags=('-n','-q','-C','-P','-d','-u','-k','-U','-B','-r','-D','-M','-H','-R','-j','-J','-Q','-L','-Y','-v','-h','-V'); 	   
  our %otherPIoptions=();
   ## Input/output files
  our %infile = ();	     # input file names container
  our %outfile = ();	     # output file names container

  ## Directories
  our %dir = ();
  $dir{output} = "."; # output directory
  $dir{temp}= "";     # temporary directory

  our $verbose = "3";
  our $ECgenericitylevel = "4"; # number of dash in an EC number equal the max genericity level ->>>>> 1.-.-.- (level 3) or 1.2.-.- (level2) or 1.2.3.- (level 1) or 1.2.3.4 (level 0 = no generic EC) 
  our $in = STDIN;
  our $out = STDOUT;
  our $directed;
  $infile{gnn} =""; # GPR Gene -> EC -> REACTION annotation file path. Default (METACYC_GPR_EC.tab)
  $infile{nnn}=""; 
  $infile{graph}="";		# File containing the graph
  our $process="";
  our $graph = "";		# Graph Name
  our $group_descriptor= ""; # Unique name to differenciate output files

  ################################################################
  ## Read argument values
  &ReadArguments();

  ################################################################
  ## Check argument values
  my $input = $infile{input};
  my $isInputFile=0;
  if ($input){
    $isInputFile=1;
  }else{
    my @query_id_list = <$in>;
    chomp(@query_id_list);
    $input = join("\t", @query_id_list);
    print STDERR "SEEDS:" .$input;
  }
  &RSAT::message::Info("--INPUT ", $input) if ($verbose >= 3);
  my $output = &RSAT::PathwayExtraction::Inferpathway($input,$isInputFile, $dir{output},$infile{gnn},$infile{nnn},$infile{graph},$directed,$dir{temp},$group_descriptor,$ECgenericitylevel,$verbose,\%otherPIoptions);
   print $out "OUTPUTFILE = $output\n";
  if ($process && -e $output){
    &RSAT::message::TimeWarn("processing files:Start") if ($verbose >= 2); 
    &RSAT::PathwayExtraction::ProcessOutputFiles(
      $output,
      $dir{output},
      $infile{gnn},
      $infile{nnn},$directed,$verbose);
    &RSAT::message::TimeWarn("processing files:End") if ($verbose >= 2); 
  }
 
}


################################################################
################### SUBROUTINE DEFINITION ######################
################################################################



################################################################
## Display full help message
sub PrintHelp {
  system "pod2text -c $0";
  exit()
}

################################################################
## Display short help message
sub PrintOptions {
  &PrintHelp();
}

################################################################
## Read arguments
sub ReadArguments {
  my $arg;
  my @arguments = @ARGV; ## create a copy to shift, because we need ARGV to report command line in &Verbose()
  while (scalar(@arguments) >= 1) {
    $arg = shift (@arguments);
    ## Verbosity

=pod

=head1 OPTIONS

=over 4

=item B<-v>

Verbose mode

=cut
    if ($arg eq "-v") {
      if (&RSAT::util::IsNatural($arguments[0])) {
	$verbose = shift(@arguments);
      } else {
	$verbose = 1;
      }


=pod

=item B<-h>

Display full help message

=cut
    } elsif ($arg eq "-h") {
      &PrintHelp();


=pod

=item B<-help>

Same as -h

=cut
    } elsif ($arg eq "-help") {
      &PrintOptions();

=pod

=item B<-hp>

Display full PathwayInference help message

=cut
    } elsif ($arg eq "-hp") {
      system("java graphtools.algorithms.Pathwayinference -h");
      print "\n";
      exit(0);

=pod

=item B<-show>

execute gwenview to display the pathway results in png format

=cut
    } elsif ($arg eq "-show") {
     $show = 1;
=pod

=item B<-process>

Process the ouput to generate a dot file and a png file 

=cut
    } elsif ($arg eq "-process") {
     $process = 1;


=pod

=item B<-i inputfile>

If no input file is specified, the standard input is used.  This
allows to use the command within a pipe.

=cut
    } elsif ($arg eq "-i") {
      $infile{input} = shift(@arguments);

=pod

=item	B<-gnn GE Genes file>

Gene -> EC (GE) annotation file.

=cut
    } elsif ($arg eq "-gnn") {
      $infile{gnn} = shift(@arguments);
=pod

=item	B<-nnn ECR file>

EC -> REACTION and COUMPOUNDS (ECR) annotation file.

=cut
    } elsif ($arg eq "-nnn") {
      $infile{nnn} = shift(@arguments);      
# =item	B<-b GR Gene -> REACTION annotation>
#
# An gene annotation file with diredt link gene to reaction. Does not rely on the EC number annotation
#
#
# =pod
#
# =cut
#     } elsif ($arg eq "-b") {
#       $outfile{gr} = shift(@arguments);

=pod

=item	B<-ecg Max EC genericity>

Ec max genericity level. Used to limit the level of genericity of EC when mapping. 
The max genericity level may have level from 0 to 4 :  1.-.-.- (level 3) or 1.2.-.- (level2) or 1.2.3.- (level 1) or 1.2.3.4 (level 0 = no generic EC)
Generic EC may contained a large number of reaction node that can increase drasticaly computatioal time and gives little information.
Default is 4;

=cut
    } elsif ($arg eq "-ecg") {
      $ECgenericitylevel = shift(@arguments);


=pod

=item	B<-gd group descriptor>

Give a group descriptor. a prefix name to teh output files.

=cut
    } elsif ($arg eq "-gd") {
      $group_descriptor = shift(@arguments);


=pod

=item	B<-g Graph file >

Graph file 

=cut
    } elsif ($arg eq "-g") {
      $infile{graph} = shift(@arguments);
=pod

=item	B<-dir true/false>

true if the graph is directed 

=cut
    } elsif ($arg eq "-d") {
      $directed =1;

=pod

=item	B<-o output Directory>

If no output file is specified, the current directory is used.

=cut
    } elsif ($arg eq "-o") {
      $dir{output} = shift(@arguments);

=pod

=item	B<-p temp Directory>

If no output file is specified, the current directory is used.

=cut
    } elsif ($arg eq "-p") {
      $dir{temp} = shift(@arguments);
=pod

=item	B<Pathway inference arguments>

=cut
      
    } elsif (grep(/$arg/ ,@pioptions)) { #if Pathway inference option add it to hash
      if (grep(/$arg/ ,@piflags)){
	$otherPIoptions{$arg}= " ";
      }else{
      	$otherPIoptions{$arg}= shift(@arguments);
      }
#       $dir{temp} = shift(@arguments);
    } else {
      
       &FatalError(join("\t", "Invalid pathway_extractor option", $arg));

    }
  }
#GetOptionsFromArray(\@arguments,\%otherPIoptions)
#getopts("CnHf:b:q:O:E:a:y:p:F:Z:m:w:t:l:T:W:P:e:d:u:x:k:U:B:r:D:M:I:N:G:X:A:K:S:R:j:J:Q:L:Y:v:h:V:o:p:g:i:g:",\%otherPIoptions);
#&FatalError(join("\t", "Invalid pathway_extractor option", $ARGV[0])) if $ARGV[0];
      
=pod

=back

=cut

}
################################################################
## Verbose message
sub Verbose {
    print $out "; template ";
    &RSAT::util::PrintArguments($out);
    printf $out "; %-22s\t%s\n", "Program version", $program_version;
    if (%infile) {
	print $out "; Input files\n";
	while (my ($key,$value) = each %infile) {
	  printf $out ";\t%-13s\t%s\n", $key, $value;
	}
    }
    if (%outfile) {
	print $out "; Output files\n";
	while (my ($key,$value) = each %outfile) {
	  printf $out ";\t%-13s\t%s\n", $key, $value;
	}
    }
}


__END__
