[Bioperl-l] [RFC] Interolog::Walk

Giuseppe Gallone G.Gallone at sms.ed.ac.uk
Thu Aug 19 06:45:36 EDT 2010


Hi Dave,

thank you very much for your helpful comments.

Regarding the module name: I will follow your advice and avoid to 
propose a new root during the module registration. As for the second 
level, I haven't been able to find anything related to 
homology/orthology, therefore I'm not sure whether I should go for

Bio::Orthology::InterologMap
or
Bio::Homology::InterologMap

The first one being maybe a bit more specific. I might also expand 
further as in

Bio::Orthology::Interolog::Map,

just in case somebody else finds other interesting applications for the 
Interolog concept and would like to "plug in" their own contribution. 
Would this make any sense?

I also appreciate your comments on the documentation. The one I provided 
is actually not the full pod I was planning to include, but rather an 
extract. What I have at the moment is a description, for each method, in 
the following form:

=====================================
    remove_duplicate_rows
      Usage     : $RC = InterologMap::remove_duplicate_rows(input_handle 
    => $dbh,
 
output_handle   => $out_data,
                                                            header 
     => 'standard',
                                                            );
      Purpose   : This is used to clean up a TSV data files of duplicate 
entries. Occasionally,  Intact can return duplicate
                  entries. This routine will make sure no such 
duplicates are kept. A new datafile is built.
                  The number of unique data rows is updated.
      Returns   : success/error
      Argument  : database handle to input file, filehandle to 
outputfile, header type. Header type is one of the following:
                  - "standard": when the routine is used to clean up an 
interolog walk file (the header will be longer)
                  - "direct":   when the routine is used to clean up a 
file of real db interaction (the header is shorter)
                  - no field provided: default is standard
      Throws    : -
      Comment   : Sample


     See Also :
=======================================

On top of that, there is a DESCRIPTION, USAGE, and SYNOPSIS. The 
synopsis has some code with an example of typical usage of the module. 
Please take a look at this (attached below) and tell me what you think.

You mention that the description contains a lot of background 
information. Would you recommend reducing it, or placing it elsewhere?
I was considering to write a little tutorial in latex as soon as 
possible anyway, to provide a "centralised" source of information to 
familiarise with the module. Does this respect the CPAN regulations?

As for your question on the structure of the module: you are indeed 
right, the idea when running the "orthology walk" is to create a 
pipeline of subroutines: there's a core set of subroutines meant to work 
in strict sequentiality.
Each of these subroutines expects, as input, the output of the previous 
one. The input/output dataset is currently in the form of a TSV text 
file, which I process with the help of the DBI module (to be more 
specific, I use DBD::CSV).

While there's a certain flexibility regarding how to use the module, one 
core idea remains: in order to get the set of putative interactors, the 
user would have to call at least three basic routines:

(A)
=================
1)get_forward_orthologies(): this queries the initial gene list against 
one or more Ensembl dbs (using the Ensembl Perl Api) and retrieves their 
orthologues, plus a number of ancillary data fields (mainly conservation 
data, eg dn/ds ratio,distance from ancestor,orthology type, etc)

2)get_interactors(): this queries the orthology list built in the 
previous stage against a PSICQUIC-enabled PPI db using Rest (at the 
moment I only query the EBI Intact DB, but it should be easy to expand 
this and query all PSICQUIC compatible PPI dbs transparently). This step 
will "fatten" the dataset built in (1) with the interactors of those 
orthologues, plus ancillary data (including lots of parameters 
describing the quality, nature, origin of the annotated interaction)

3)get_backward_orthologies(): this queries the interactor list built in 
the previous stage against one or more Ensembl dbs to find orthologues 
*back* in the original species. It also adds a number of supplementary 
information just like in (1).
==================

At the end of this procedure the user will have a TSV files where each 
row contains a binary putative interaction plus (currently) 37 
supplementary data fields.

One can then scan these results to check for duplicates, to compute 
counts, to see if we have discovered new gene ids that were not present 
in the original dataset (hopefully we have :) ).

Most importantly, one can then further process these results to do one 
or more of the following:
(B) compute a global confidence score to assess the reliability of the 
each binary putative interaction
(C) extract the binary putative PPIs from the dataset and save them in a 
format compatible with Cytoscape: this helps providing a visual quality 
to the result: one can then apply network analysis tools to discover 
motifs, clusters, etc. The format I use is currently .SIF + attributes, 
as detailed in
http://cytoscape.wodaklab.org/wiki/Cytoscape_User_Manual/Network_Formats
(D) given the same initial gene list, one can also build a dataset of 
REAL, experimentally-obtained PPIs,(without mapping through orthologies 
in other species). One can then compare this dataset with the Putative 
dataset to see if/where the two overlap, what's the intersection or the 
differences, etc.


In order to suggest ways of using the module I have written 4 sample 
scripts and I will include them in the module. Each script utilises the 
module and uses/reuses subroutines in a pipeline fashion, and does the 
following:

1)doInterologWalk.pl: runs the basic pipeline in (A)
2)doScores.pl: computes and adds confidence scores as explained in (B)
3)doNetworks.pl: computes SIF network + attributes as in (D)
4)getRealInteractions.pl: runs a pipeline to obtain real PPIs from the 
inital gene set.

Hope I didn't make this too confusing. I would love to hear back from 
you and from anybody else that would like to provide feedback.

Cheers
Giuseppe

On 18/08/10 17:52, Dave Messina wrote:
> Hi Giuseppe,
>
> Sounds really interesting — thanks for posting this.
>
>> Bio::Orthology::InterologWalk
>
> I vote for this name, or in any case something with Bio:: as the top-level namespace since it's a biology-related package.
>
> I like that you're providing a lot of background and information about the project in the documentation. However, the USAGE section should give information about how to use the module, with example code. You can look at other modules on CPAN (or in BioPerl) to see the conventions for writing documentation.
>
> Also, from what you wrote, it sounds like this might be a pipeline or a script rather than a module per se, or perhaps a script and a set of modules. It would be helpful to clarify in your documentation (if you haven't already) how exactly things are organized (and of course example code will help with that, too).
>
>
> Hope that's helpful, and let us know when you've got it up on CPAN so we can try it out!
>
>
> Dave
>
>

NAME
     Interolog::Walk - Retrieve, score and visualize putative 
Protein-Protein
     Interactions through the orthology-walk method

SYNOPSIS
       use Interolog::Walk;

     First, obtain Intact Interactions for the dataset (see example in
     "getDirectInteractions.pl"):

       #get a registry from Ensembl
       my $registry = InterologMap::setup_ensembl_adaptor(connect_to_db 
  => $ensembl_db,
                                                          source_species 
=> $sourceorg,
                                                          verbose 
  => 1
                                                          );


       #query actual interactions
       $RC = InterologMap::Direct::get_direct_interactions(registry 
     => $registry,
 
source_species   => $sourceorg,
                                                           input_path 
     => $in_path,
                                                           output_path 
     => $out_path,
                                                           url 
     => $url,
                                                           );

     do some postprocessing (see "do_counts()" and "extract_unseen_ids()" )
     and then do the actual interolog walk on the dataset with the following
     sequence of three methods.

     get orthologues of starting set:

       $RC = InterologMap::get_forward_orthologies(registry        => 
$registry,
                                                   ensembl_db      => 
$ensembl_db,
                                                   input_path      => 
$in_path,
                                                   output_path     => 
$out_path,
                                                   source_org      => 
$sourceorg,
                                                   dest_org        => 
$destorg,
                                                   );

     add interactors of orthologues found by "get_forward_orthologies()":

       $RC = InterologMap::get_interactions(input_path    => $in_path,
                                            output_path   => $out_path,
                                            url           => $url,
                                            url_global    => $url_global,
                                            );

     add orthologues of interactors found by "get_interactions()":

       $RC = InterologMap::get_backward_orthologies(registry    => 
$registry,
                                                    ensembl_db  => 
$ensembl_db,
                                                    input_path  => $in_path,
                                                    output_path => 
$out_path,
                                                    error_path  => 
$err_path,
                                                    source_org  => 
$sourceorg,
                                                    );

     do some postprocessing (see "remove_duplicate_rows()", "do_counts()",
     "extract_unseen_ids()") and then optionally compute a composite score
     for the putative interactions obtained:

        $RC = InterologMap::Scores::compute_scores(input_path      => 
$in_path,
                                                   score_path      => 
$score_path,
                                                   output_path     => 
$out_path,
                                                   term_graph      => 
$onto_graph,
                                                   M_IT_SCORE      => $M_IT,
                                                   M_DM_SCORE      => $M_DM,
                                                   M_ME_DM_SCORE   => 
$M_MDM,
                                                   M_ME_TAXA_SCORE => 
$M_MTAXA
                                                   );

     get some networks and network attributes which you can then visualise
     with cytoscape

        $RC = InterologMap::Networks::do_network(registry            => 
$registry,
                                                    db               => 
$ensembl_db,
                                                    input_path       => 
$in_path,
                                                    output_path      => 
$out_path,
                                                    source_org       => 
$sourceorg,
                                                    orthology_type   => 
$orthtype,
                                                    );

        $RC = InterologMap::Networks::do_attributes(registry      => 
$registry,
                                                    input_path    => 
$in_path,
                                                    output_path   => 
$out_path,
                                                    source_org    => 
$sourceorg,
                                                    label_type    => 
'external name'
                                                    );

     *The synopsis above only lists the major methods and parameters.*

DESCRIPTION
     A common activity in computational biology is to mine protein-protein
     interactions from publicly available databases to build 
*Protein-Protein
     Interaction* (PPI) datasets. In many instances, however, the number of
     experimentally obtained annotated PPIs is very scarce and it would be
     helpful to enrich the experimental dataset with high-quality,
     computationally-inferred PPIs. Such computationally-obtained 
dataset can
     extend, support or enrich experimental PPI datasets, and are of crucial
     importance in high-throughput gene prioritization studies, i.e. to 
drive
     hypotheses and restrict the dimensionality of functional discovery
     problems. This Perl Module, Interolog::Walk, is aimed at building
     putative PPI datasets on the basis of a number of comparative biology
     paradigms: the module implements a collection of computational biology
     algorithms based on the concept of "orthology projection". If
     interacting proteins A and B in organism X have orthologs A' and B' in
     organism Y, under certain conditions one can assume that the 
interaction
     will be conserved in organism Y, i.e. the A-B interaction can be
     "projected through the orthologies" to obtain a putative A'-B'
     interaction. The pair of interactions (A-B) and (A'-B') are named
     "Interologs".

     Interolog::Walk collects, analyses and collates gene orthology data
     provided by the Ensembl Consortium as well as PPI data provided by EBI
     Intact. It provides the user with the possibility of rating the quality
     and reliability of the putative interactions collected, by means of
     confidence scores, and optionally outputs network representations 
of the
     datasets, compatible with the biological network representation
     standard, Cytoscape.

BASIC USAGE
   Rationale behind "Interolog::Walk".
                                   \EBI Intact API/
              .--------------.            |             .-------------.
          (2) | A(e.g. mouse)|<------------------------>|   B(mouse)  |  (3)
              `--------------'          <PPI>           `-------------'
                     ^                                         |
        /Ensembl\    | <Orthology>                 <Orthology> | \ Ensembl /
       / Compara \   |                                         |  \Compara/
      /    Api    \  |                                         |   \ Api /
                     |                                         |
              .--------------.                           .-------------.
          (1) | A'(e.g. fly) |. . . . . . . . . . . . .  |   B'(fly)   | (4)
              `--------------'     [SCORED]PUTATIVE PPI  `-------------'
                              (Output of Interolog::Walk)

     In order to carry out an interolog walk we start with a set of gene
     identifiers in one organism of interest (1). We query those ids against
     a number of comparative biology databases to retrieve a list of
     orthologues for the gene id of interest, in one or more species (2). In
     the next step we rely instead on PPI databases to retrieve the list of
     available interactors for the protein ids obtained in (2). The 
output at
     this stage consists of a list of interactors of the orthologues of the
     initial gene set, plus several fields of ancillary data (whose
     importance will be explained later) (3). In the last step of this
     process we will need to project the interactions in (3) - again using
     orthology data - back to the original species of interest. The 
output of
     the process is a list of PUTATIVE INTERACTORS of the initial gene set,
     plus several fields of ancillary data.

     "Interolog::Walk" provides three main functions to carry out the basic
     walk, "get_forward_orthologies()", "get_interactions()" and
     "get_backward_orthologies()". These functions must be called strictly
     sequentially in your script, as the process, analyse and attach data to
     the output in a pipeline-like fashion, i.e. processing the output 
of the
     preceding function.

     get_forward_orthologies
     get_interactions
     get_backward_orthologies

SCORING THE PUTATIVE INTERACTIONS
BUILDING PUTATIVE INTERACTION NETWORKS
BUGS
     Please report any you find

SUPPORT
     TODO

AUTHOR
     Giuseppe Gallone <ggallone at cpan.org>

     CPAN ID: GGALLONE

     University of Edinburgh

COPYRIGHT
     The Interolog::Walk module is Copyright (c) 2010 Giuseppe Gallone All
     rights reserved.

     You may distribute under the terms of either the GNU General Public
     License or the Artistic License, as specified in the Perl 5.10.0 README
     file.

SEE ALSO


-- 
The University of Edinburgh is a charitable body, registered in
Scotland, with registration number SC005336.


More information about the Bioperl-l mailing list