README

   1 NAME
   2     perlcyc - A Perl interface for Pathway Tools software for UNIX-based
   3     systems.
   4
   5 SYNOPSIS
   6     perlcyc is a Perl interface for Pathway Tools software. Pathway Tools
   7     software needs to run a special socket server program for this module to
   8     work (see below).
   9
  10     "use perlcyc;"
  11
  12     "my $cyc = perlcyc -> new("ARA");" "my @pathways = $cyc ->
  13     all_pathways();"
  14
  15 PATHWAY TOOLS REQUIREMENTS
  16     To use the Perl module, you also need the socket_server.lisp program. In
  17     Pathway Tools version 8.0 or later, the server program can be started
  18     with the command line option "-api". On earlier versions, the server
  19     daemon needs to be loaded manually, as follows: start Pathway-Tools with
  20     the -lisp option, at the prompt, type: (load
  21     "/path/to/socket_server.lisp"), then start the socket_server by typing
  22     (start_external_access_daemon :verbose? t). The server is now ready to
  23     accept connections and queries.
  24
  25 DESCRIPTION
  26     perlcyc.pm is a Perl module for accessing internal Pathway-Tools
  27     functions. For the description of what the individual functions do,
  28     please refer to the Pathway Tools documentation at
  29     http://bioinformatics.ai.sri.com/ptools .
  30
  31     In general, the Lisp function name has to be converted to something
  32     compatible with Perl: Dashes have to be replaced by underlines, and
  33     question marks with underline p (_p).
  34
  35     Note that the optional parameters of all functions are not supported in
  36     perlcyc, except for all_pathways() which can use the optional arguments
  37     :all T to get the base pathways only (no super-pathways).
  38
  39    Limitations
  40     Perlcyc does not run on Windows, because perlcyc creates a file system
  41     socket that is not supported in Windows. It should run in Solaris,
  42     Linux, MacOSX and other UNIX-like operating systems.
  43
  44     Perlcyc does not implement the GFP objects in Perl; it just sends
  45     snippets of code to Pathway-Tools through the file socket connection.
  46     Because of this, only one such connection can be openend at any given
  47     time.
  48
  49     Given that the objects are not implemented in Perl, only object
  50     references are supported.
  51
  52    Available functions:
  53       Object functions:
  54
  55        new
  56        Parameters: The knowledge base name. Required!
  57
  58       GFP functions:
  59       More information on these functions can be found at:
  60       http://www.ai.sri.com/~gfp/spec/paper/node63.html
  61
  62    get_slot_values
  63        get_slot_value
  64        get_class_all_instances
  65        instance_all_instance_of_p
  66        member_slot_value_p
  67        fequal
  68        current_kb
  69        put_slot_values
  70        put_slot_value
  71        add_slot_value
  72        replace_slot_value
  73        remove_slot_value
  74        coercible_to_frame_p
  75        class_all_type_of_p
  76        get_instance_direct_types
  77        get_instance_all_types
  78        get_frame_slots
  79        put_instance_types
  80        save_kb
  81        revert_kb
  82
  83   Pathway-tools functions:
  84       More information on these functions can be found at:
  85       http://bioinformatics.ai.sri.com/ptools/ptools-fns.html
  86
  87        select_organism
  88        all_pathways
  89        all_orgs
  90        all_rxns
  91        genes_of_reaction
  92        substrates_of_reaction
  93        enzymes_of_reaction
  94        reaction_reactants_and_products
  95        get_predecessors
  96        get_successors
  97        genes_of_pathway
  98        enzymes_of_pathway
  99        compounds_of_pathway
 100        substrates_of_pathway
 101        transcription_factor_p
 102        all_cofactors
 103        all_modulators
 104        monomers_of_protein
 105        components_of_protein
 106        genes_of_protein
 107        reactions_of_enzyme
 108        enzyme_p
 109        transport_p
 110        containers_of
 111        modified_forms
 112        modified_containers
 113        top_containers
 114        reactions_of_protein
 115        regulon_of_protein
 116        transcription_units_of_protein
 117        regulator_proteins_of_transcription_unit
 118        enzymes_of_gene
 119        all_products_of_gene
 120        reactions_of_gene
 121        pathways_of_gene
 122        chromosome_of_gene
 123        transcription_unit_of_gene
 124        transcription_unit_promoter
 125        transcription_unit_genes
 126        transcription_unit_binding_sites
 127        transcription_unit_transcription_factors
 128        transcription_unit_terminators
 129        all_transported_chemicals
 130        reactions_of_compound
 131        full_enzyme_name
 132        enzyme_activity_name
 133        find_indexed_frame
 134        create-instance
 135        create-class
 136        create-frame
 137
 138        pwys-of-organism-in-meta
 139        enzymes-of-organism-in-meta
 140        lower-taxa-or-species-p org-frame
 141        get-class-all-subs
 142
 143       added 5/2008 per Suzanne's request:
 144        genes-regulating-gene
 145        genes-regulated-by-gene
 146        terminators-affecting-gene
 147        transcription-unit-mrna-binding-sites
 148        transcription-unit-activators
 149        transcription-unit-inhibitors
 150        containing-tus
 151        direct-activators
 152        direct-inhibitors
 153
 154
 155
 156       not supported:
 157        get_frames_matching_value (why not?)
 158
 159       Internal functions:
 160
 161    parselisp
 162        send_query
 163        retrieve_results
 164        wrap_query
 165        call_func
 166        debug
 167        debug_on
 168        debug_off
 169
 170       Deprecated functions
 171        parse_lisp_list
 172
 173 EXAMPLES
 174     Change product type for all genes that are in a pathway to 'Enzyme'
 175
 176      use perlcyc;
 177
 178      my $cyc = perlcyc -> new ("ARA");
 179      my @pathways = $cyc -> all_pathways();
 180
 181      foreach my $p (@pathways) {
 182        my @genes = $cyc -> genes_of_pathway($p);
 183        foreach my $g (@genes) {
 184          $cyc -> put_slot_value ($g, "Product-Types", "Enzyme");
 185        }
 186      }
 187
 188     Load a file containing two columns with accession and a comment into the
 189     comment field of the corresponding accession:
 190
 191      use perlcyc;
 192      use strict;
 193
 194  my $file = shift;
 195
 196      my $added=0;
 197      my $recs =0;
 198
 199      open (F, "<$file") || die "Can't open file\n";
 200
 201      print STDERR "Connecting to AraCyc...\n";
 202      my $cyc = perlcyc -> new("ARA");
 203
 204      print STDERR "Getting Gene Information...\n";
 205      my @genes = $cyc -> get_class_all_instances("|Genes|");
 206
 207      my %genes;
 208
 209      print STDERR "Getting common names...\n";
 210      foreach my $g (@genes) {
 211        my $cname = $cyc -> get_slot_value($g, "common-name");
 212        $genes{$cname}=$g;
 213      }
 214
 215      print STDERR "Processing file...\n";
 216      while (<F>) {
 217        my ($locus, $location, @rest) = split /\t/;
 218        $recs++;
 219        if (exists $genes{$locus}) {
 220            my $product = $cyc -> get_slot_value($genes{$locus}, "product");
 221              if ($product) {
 222              $cyc -> add_slot_value($product, "comment", "\"\nTargetP location: $location\n\"");
 223               #print STDERR "Added to description of frame $product\n";
 224              $added++;
 225            }
 226          }
 227      }
 228
 229      close (F);
 230
 231      print STDERR "Done. Added $added descriptions. Total lines in file: $recs. \n";
 232
 233     Add a locus link to the TAIR locus page for each gene in the database
 234
 235      use strict;
 236      use perlcyc;
 237
 238      my $added =0;
 239      my $genesprocessed=0;
 240
 241      print "Connecting to AraCyc...\n";
 242      my $cyc = perlcyc -> new ("ARA");
 243
 244      print "Getting Gene Information...\n";
 245      my @genes = $cyc -> get_class_all_instances ("|Genes|");
 246
 247      print "Adding TAIR links...\n";
 248      foreach my $g (@genes) {
 249        $genesprocessed++;
 250        my $common_name = $cyc -> get_slot_value($g, "common-name");
 251        if ($common_name && ($common_name ne "NIL")) {
 252          $cyc -> put_slot_value ($g, "dblinks", "(TAIR \"$common_name\")");
 253          $added++;
 254        }
 255        if ((!$genesprocessed ==0) && ($genesprocessed % 1000 == 0)) { print "$genesprocessed ";}
 256      }
 257
 258      print "Done. Processed $genesprocessed genes and added $added links. Thanks!\n";
 259      $cyc -> close();
 260
 261 TROUBLESHOOTING
 262     If your program terminates with the following error message: "connect:
 263     No such file or directory at perlcyc.pm line 166." then the
 264     lisp_server.lisp module in Pathway Tools is not running. Refer to
 265     http://aracyc.stanford.edu for more information on how to run the server
 266     program.
 267
 268     Please send bug reports and comments to lam87@cornell.edu
 269
 270 LICENSE
 271     According to the MIT License,
 272     http://www.opensource.org/licenses/mit-license.php
 273
 274     Copyright (c) 2002 by Lukas Mueller, The Arabidopsis Information
 275     Resource (TAIR) and the Carnegie Institution of Washington.
 276
 277     Permission is hereby granted, free of charge, to any person obtaining a
 278     copy of this software and associated documentation files (the
 279     "Software"), to deal in the Software without restriction, including
 280     without limitation the rights to use, copy, modify, merge, publish,
 281     distribute, sublicense, and/or sell copies of the Software, and to
 282     permit persons to whom the Software is furnished to do so, subject to
 283     the following conditions:
 284
 285     The above copyright notice and this permission notice shall be included
 286     in all copies or substantial portions of the Software.
 287
 288     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 289     OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 290     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 291     IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 292     CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 293     TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 294     SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 295
 296 AUTHOR
 297     Lukas Mueller <lam87@cornell.edu>
 298
 299 ACKNOWLEDGMENTS
 300     Many thanks to Suzanne Paley, Danny Yoo and Thomas Yan.
 301