Information

Pathway Tools Overview Pathway Tools Testimonials
Publications
Release Note History
Contributions
Pathway Tools Blog
Technical Datasheet
Fact Sheet
Pathway Tools Testimonials
Contact Us

Licensing

Academic Licenses Commercial Licenses

Technical Specs

Web Services
Pathway Tools APIs
Installation Guide
Ontologies
Operations
File Formats

Support

Submitting Bug Reports
Tutorials
FAQs
Webinars
Pathway Tools Internal Lisp Functions

Pathway Tools Internal Lisp Functions

Table of Contents

See also these documents:

Introduction

This document describes many important Lisp functions for retrieving information from Pathway Tools (PTools), and for updating Pathway/Genome Databases (PGDBs).

The lower-level API for directly querying PGDBs, called the Generic Frame Protocol (GFP), is described in two separate documents listed just above.

Many of these functions return a plurality of values, for example, function all-rxns returns all reactions in the current PGDB. Unless otherwise stated, you can assume these values are returned as a list of frames.

Usually each frame returned by PTools will be a frame object, but in some cases symbol or string frame IDs will be returned.

Organism Operations

Function: all-orgs (&optional (verbose? t) org-ids?)
Returns: A list of kb defstructs for all organisms currently known to Pathway Tools. That list of organisms is determined by the software at startup time by enumerating the "*cyc" directories present in the aic-export/ecocyc/ directory.
Arguments: Verbose?: If T, the function also prints the species name, strain name, and organism identifier for each known organism.
Org-IDs?: If T, the function returns a list of orgIDs rather than a list of kb defstructs.

Function: select-organism (&key org-id org version dbms-type)
Returns: NIL
Side Effects: Selects the PGDB whose organism identifier is Org-ID as the currently selected organism within the Pathway Tools, such as by making the Ocelot KB for this organism the currently selected KB. Subsequent KB operations (such as GFP operations) will by default refer to the KB for that organism.
Arguments: Org-ID: An organism identifier, which must be a Lisp symbol. The organism identifier is usually the identifer at the front of the "*cyc" directory name for the PGDB.
Org: A kb defstruct. Either the Org or Org-ID arguments must be supplied to specify what PGDB is to be opened.
Version: A string specifying what version of the PGDB to open; if omitted, the version specified in the file called default-version in the PGDB directory will be opened.
DBMS-Type: The type of database management system in which the PGDB will be opened from. Recognized values are :FILE and :MYSQL. Defaults to the type specified in the file organism.dat in the PGDB inputs directory.
Examples: (select-organism :org-id 'ecoli)
(select-organism :org-id 'meta :version "28.0" :dbms-type :file)

Function: find-pgdbs (&optional substring)
Returns: A list of PGDBs (kb defstructs) for all organisms whose genus, species, or strain name contains the specified substring. If no substring is specified, this function returns all PGDBs. Searching is case-insensitive, and spaces and punctuation characters are ignored.
Arguments: substring: a string

Reaction Operations

Function: all-rxns (&optional (type :smm))
Returns: All reaction frames in the current PGDB. The Type arg determines exactly which reactions are returned.
Arguments: Type can be one of: :all = All reactions. :smm = All reactions whose substrates are all small molecules, plus all reactions that are members of pathways of small- molecule metabolism. Note that :smm will often return more reactions than does :small-molecule because some pathways of small-molecule metabolism contain reactions involving macromolecules, e.g., ACP. :small-molecule = All reactions whose substrates are all small molecules, as opposed to macromolecules. :enzyme = All enzyme-catalyzed reactions (instances of classes EC-Reactions or Unclassified-Reactions). :transport = All transport reactions. :dna = All DNA Binding Reactions.

Function: genes-of-reaction (rxn)
Returns: All gene frames that code for enzymes (or subunits of enzyme complexes) that catalyze the reaction Rxn. If multiple enzymes catalyze Rxn, genes encoding all of the enzymes are returned.
Arguments: Rxn: A reaction frame.

Function: substrates-of-reaction (rxn)
Returns: All substrates of the reaction Rxn, meaning the union of the reactants and products of Rxn. A list of frames is returned.
Arguments: Rxn: A reaction frame.

Function: enzymes-of-reaction (rxn)
Returns: All enzymes that catalyze the reaction Rxn.
Arguments: Rxn: A reaction frame.

Function: reaction-reactants-and-products (rxn &key pwy direction)
Returns two values: the reactants of Rxn, and the products of Rxn. The reactants and products are those determined according to either the direction of Rxn in Pwy, or the direction specified by the Direction arg (which should be either :L2R or :R2L). In other words, either the Pwy or the Direction arg should be specified, but not both.
Arguments: Rxn: A reaction frame.
Pwy: A pathway frame.
Direction: :L2R (left to right) or :R2L (right to left)

Function: reaction-type? (rxn type)
Returns: T if Rxn is of type Type.
Arguments: Rxn: A reaction frame.
Type: Either :small-molecule (meaning all substrates must be small molecules rather than macromolecules) or :transport (meaning the reaction is already a child of class Transport-Reactions, or that some substrate of the reaction appears as both a reactant and a product of the reaction, but on different sides of the reaction).

Function: transported-chemicals (rxn)
Returns: Those compounds in the transport reaction Rxn that change compartments (meaning a compound is in one compartment as a reactant and is in a different compartment as a product).
Arguments: Rxn: A reaction frame.

Function: get-predecessors (rxn pwy)
Returns: A list of all reactions that are direct predecessors of Rxn in Pwy, meaning those reactions produce some reactant of Rxn and thus come just before Rxn in the pathway.
Arguments: Rxn: A reaction frame.
Pwy: A pathway frame.

Function: get-successors (rxn pwy)
Returns: A list of all reactions that are direct successors of Rxn in Pwy.
Arguments: Rxn: A reaction frame.
Pwy: A pathway frame.

Pathway Operations

Function: all-pathways (&optional (selector :all) base?)
Returns: All pathways in the current PGDB, as determined by the arguments.
Arguments: Selector: :all -- Returns all base pathways. :small-molecule -- Returns all small-molecule metabolism base pathways.
Base: T means base pathways only, NIL means also include superpathways.

Function: genes-of-pathway (pwy)
Returns: All genes that code for enzymes (or subunits of enzymes) that catalyze a reaction in the pathway Pwy. The returned list does not include genes coding for proteins that are substrates in the pathway (if any).
Arguments: Pwy: A pathway frame.

Function: enzymes-of-pathway (pwy)
Returns: All enzymes that catalyze a reaction in the pathway Pwy.
Arguments: Pwy: A pathway frame.

Function: compounds-of-pathway (pwy)
Returns: Returns all substrates (meaning reactants and products) of reactions of Pwy, with duplicates removed.
Arguments: Pwy: A pathway frame.

Function: substrates-of-pathway (pwy)
Returns four values: (1) The list of all reactant compounds (compounds occurring on the left side of some reaction in Pwy). (2) The list of proper reactants (the subset of reactants that are not also products). (3) The list of all products. (4) The list of proper products. This function does take into account the proper direction of each reaction within Pwy.
Arguments: Pwy: A pathway frame.

Protein Operations

Function: all-transcription-factors (&key (allow-modified-forms? t))
Returns: All transcription factors in the current PGDB (computed as any protein that is a substrate in a binding reaction where another substrate is a DNA site).
Arguments: If Allow-modified-forms? is nil, we return unmodified forms of the proteins only.

Function: transcription-factor? (protein)
Returns: T if Protein is a transcription factor in the current organism. Definition: Protein is a transcription factor if it is a reactant of a binding-reaction, and another reactant of the same binding reaction is a DNA-Binding-Site.
Arguments: Protein: An instance of class Proteins.

Function: all-cofactors ()
Returns: All cofactors used by enzymes in the current PGDB.

Function: all-modulators ()
Returns: All modulators (activators and inhibitors) that enzymes in the current PGDB are sensitive to.

Function: monomers-of-protein (p)
Returns: A list of the monomers (instances of class Polypeptides) that are subunits of protein P. If P is itself a monomer, the function returns P.
Arguments: P: An instance of class Proteins.

Function: components-of-protein (p &optional coefficient)
Returns: This function recursively computes all of the components of a protein P. It returns two values: a list of components (including P) and a list of their coefficients.
Arguments: P: An instance of class Proteins.

Function: genes-of-protein (p)
Returns: All genes that code for protein P and all of the subunits of P.
Arguments: P: An instance of class Proteins.

Function: reactions-of-enzyme (e)
Returns: All reactions that enzyme E is linked to via enzymatic reactions.
Arguments: E: An instance of class Proteins.

Function: enzyme? (protein &optional (type :any))
Returns: Predicate that decides whether a specified protein is an enzyme or not; returns T or NIL, respectively.
Arguments: Protein: An instance of class Proteins. Type [optional]: Can have one of four values to select more precisely what is meant by an enzyme: :any -- Any protein that catalyzes a reaction is considered an enzyme; :chemical-change -- If the reactants and products of the catalyzed reaction differ (not just cellular location), the protein is considered an enzyme; :small-molecule -- If the reactants of the catalyzed reaction differ and are all small molecules, the protein is considered an enzyme; :non-transport -- exclude all proteins that only catalyze transport reactions.

Function: transporter? (protein)
Returns: T if Protein is a transporter.
Arguments: Protein: An instance of class Proteins.

Function: containers-of (protein &optional exclude-self?)
Returns: All containers of Protein, including itself (unless Exclude-self? is T). Follows the Component-Of slot.
Arguments: Protein: An instance of class Proteins.
Exclude-Self?: Boolean indicating whether Protein should be included in the returned list.

Function: modified-forms (protein &optional exclude-self?)
Returns: A list of the modified forms of Protein (including Protein, unless Exclude-self? is T). Follows the Modified-Forms slot.
Arguments: Protein: An instance of class Proteins.
Exclude-Self?: Boolean indicating whether Protein should be included in the returned list.

Function: modified-containers (protein)
Returns: Both all containers of a protein (meaning protein complexes of which this protein is a part) including itself, and all modified forms of a protein.
Arguments: Protein: An instance of class Proteins.

Function: top-containers (protein)
Returns: Those containers of a protein (meaning protein complexes of which this protein is a part) that themselves have no containers.
Arguments: Protein: An instance of class Proteins.

Function: reactions-of-protein (p)
Returns: All reactions catalyzed by P or by subunits of P.
Arguments: Protein: An instance of class Proteins.

Function: regulon-of-protein (protein)
Returns: The list of transcription units regulated by any modified or unmodified form of Protein.
Arguments: Protein: An instance of class Proteins.

Function: transcription-units-of-protein (protein)
Returns: The list of transcription units activated or inhibited by the supplied protein or modified protein frame (does not consider other modified or unmodifed forms of Protein as does regulon-of-protein).
Arguments: Protein: An instance of class Proteins.

Function: regulator-proteins-of-transcription-unit (tu)
Returns: All proteins that bind to binding sites within TU.
Arguments: TU: An instance of class Transcription-Units.

Function: full-enzyme-name (enzyme)
Returns: A string describing the full name of enzyme, as the concatenation of the common name of the protein followed by the common names of its enzymatic reactions. Note that two enzrxns for the same enzyme could have the same common name, so we avoid including the same name twice.
Arguments: Enzyme: An instance of class Proteins.

Function: enzyme-activity-name (enzyme &optional reaction)
Returns: A string describing the name of an enzyme -- an enzyme-activity name. If Reaction is non-nil, then we compute the name of the enzyme in the context of that reaction, otherwise we return the full enzyme name, which describes all of the reactions that it catalyzes. If Reaction is NIL, this function is equivalent to full-enzyme-name.
Arguments: Enzyme: An instance of class Proteins.
Reaction: An instance of class Reactions.

Gene Operations

Function: enzymes-of-gene (gene)
Returns: All enzymes coded for by Gene (meaning both a monomer product of Gene, and complexes that contain such monomers), meaning proteins that catalyze some reaction.
Arguments: Gene: An instance of class Genes.

Function: all-products-of-gene (gene)
Returns: All gene products of Gene (including modified forms and complexes), including those that are not enzymes.
Arguments: Gene: An instance of class Genes.

Function: reactions-of-gene (gene)
Returns: All reactions catalyzed by proteins that are products of Gene (meaning both monomer products of Gene, and complexes that contain such monomers).
Arguments: Gene: An instance of class Genes.

Function: pathways-of-gene (gene)
Returns: All pathways containing reactions that are catalyzed by proteins that are produts of Gene (meaning both monomer products of Gene, and complexes that contain such monomers).
Arguments: Gene: An instance of class Genes.

Function: chromosome-of-gene (gene)
Returns: The chromosome on which Gene resides.
Arguments: Gene: An instance of class Genes.

Function: transcription-units-of-gene (gene)
Returns: A list of transcription units that form the operon containing gene.
Arguments: Gene: An instance of class Genes.

Function: genes-regulating-gene (gene)
Returns: A list of genes that regulate transcription or translation of gene
Arguments: Gene: An instance of class Genes.

Function: genes-regulated-by-gene (gene)
Returns: A list of genes whose transcription or translation is regulated by the product of gene.
Arguments: Gene: An instance of class Genes.

Function: terminators-affecting-gene (gene)
Returns: A list of terminators that are in the same transcription-unit as gene and are upstream of gene. Anything that regulates these terminators (i.e. by attenuation) can be assumed to regulate transcription of gene.
Arguments: Gene: An instance of class Genes.

Function: get-gene-sequence (gene)
Returns: A string containing the nucleotide sequence for the gene (if available).
Arguments: Gene: An instance of class Genes.

Function: nucleotide->protein-sequence (sequence &optional (code-num 1))
Returns: A string containing the translated sequence.
Arguments: Sequence: A string representing a nucleotide sequence (such as might be returned by get-gene-sequence).
Code-num: The number of the genetic code to use (an integer from 1 to 15). Defaults to the standard genetic code.

Transcription-Unit Operations

Function: transcription-unit-promoter (tu)
Returns: The promoter of the transcription unit TU.
Arguments: TU: An instance of class Transcription-Units.

Function: transcription-unit-genes (tu)
Returns: A list of the genes within the transcription unit TU.
Arguments: TU: An instance of class Transcription-Units.

Function: transcription-unit-binding-sites (tu)
Returns: A list of the DNA binding sites within the transcription unit TU.
Arguments: TU: An instance of class Transcription-Units.

Function: transcription-unit-mrna-binding-sites (tu)
Returns: A list of the mRNA binding sites within the transcription unit TU.
Arguments: TU: An instance of class Transcription-Units.

Function: transcription-unit-transcription-factors (tu)
Returns: A list of the transcription factors that control the transcription unit TU.
Arguments: TU: An instance of class Transcription-Units.

Function: binding-site-transcription-factors (bsite)
Returns: A list of the transcription factors that bind to the DNA binding site Bsite.
Arguments: Bsite: An instance of class DNA-Binding-Sites.

Function: transcription-unit-terminators (tu)
Returns: A list of the transcription terminator(s) within the transcription unit TU.
Arguments: TU: An instance of class Transcription-Units.

Function: transcription-unit-activators (tu)
Returns: A list of the transcription factors or other regulators (e.g. small RNAs) that activate transcription or translation of the transcription unit TU. This does not include regulators of attenuation (because they regulate only the portion of a transcription unit downstream of the terminator).
Arguments: TU: An instance of class Transcription-Units.

Function: transcription-unit-inhibitors (tu)
Returns: A list of the transcription factors or other regulators (e.g. small RNAs) that inhibit transcription or translation of the transcription unit TU. This does not include regulators of attenuation (because they regulate only the portion of a transcription unit downstream of the terminator).
Arguments: TU: An instance of class Transcription-Units.

Function: containing-tus (site)
Returns: A list of transcription units containing site.
Arguments: Site: An instance of any of the following classes: Genes, Promoters, Terminators, DNA-Binding-Sites, mRNA-Binding-Sites, Transcription-Units.

Compound Operations

Function: all-transported-chemicals ()
Returns: All chemicals that are transported by the set of all defined transport reactions in the current PGDB.
Arguments: None.

Function: reactions-of-compound (cpd)
Returns: The reactions in which Cpd occurs as a reactant or a product.
Arguments: Cpd: An instance of class Chemicals.

Regulation Operations

Function: direct-activators (item)
Returns: The list of entities (e.g. protein, RNA, small molecule) that directly activate item.
Arguments: Item: any frame that can be regulated, e.g. an instance of Enzymatic-Reactions, Transcription-Units, Promoters, Terminators, etc.

Function: direct-inhibitors (item)
Returns: The list of entities (e.g. protein, RNA, small molecule) that directly inhibit item.
Arguments: Item: any frame that can be regulated, e.g. an instance of Enzymatic-Reactions, Transcription-Units, Promoters, Terminators, etc.

General Operations

Function: create-instance-w-generated-id (class)
Side Effects: Creates a new instance of Class whose frame ID is generated automatically.
Returns: The created frame (either its frame name or the frame object).
Arguments: Class: The parent class of the instance to be created.
Example: (create-instance-w-generated-id '|Genes|)

Function: get-name-string (item &key (rxn-eqn-as-name? t) direction name-slot strip-html?)
Returns: A string name for the frame Item. This is the standard function for computing the biological name of a frame. Exact operation depends on what type of entity Item is. For genes, for example, the fn simply retrieves the value of the common-name slot, or else the frame ID, if the common-name slot has no value. For other entities, name generation is more complex.
Arguments: Item: The frame whose name is to be computed.
Rxn-eqn-as-name?: Influences how names are computed for reaction frames. When T, the reaction equation is returned; else the EC number (or frame name if there is no EC number) is returned.
Direction: Influences how names are computed for reaction frames. Possible values: :r2l or :l2r.
Name-slot: Overrides use of common-name slot as the slot from which the name is retrieved.
Strip-Html?: When T causes this fn to strip HTML tags from the resulting names, which by default will sometimes contain HTML tags such as italics or subscripts.