Introduction to Writing Pathway Tools Queries in Lisp

Queries to Pathway/Genome Databases stored within the Pathway Tools software system are written using the Common Lisp language. Learning enough Common Lisp to write Pathway Tools queries is typically no more different than learning enough SQL to query relational databases, but Lisp is ultimately a much more powerful environment in which to write DB queries because of the tight coupling between the language and the database.

You would typically begin a query session by starting the Pathway Tools or EcoCyc (depending on which software configuration you have installed) in a mode in which it enters the Lisp interpreter on startup, rather than entering the Pathway/Genome Navigator interface. Use the command

pathway-tools -lisp

ecocyc -lisp

Sample Session

You can now write queries to the Lisp prompt, as shown in the following sample session. User input is shown in bold.

% pathway-tools -lisp

[Lisp started at 17:08:59 on Tue Oct 23, 2001]

;   Loading /home/swami1/pkarp/lisp/misc.lisp
;   Loading /home/hapuna1/biogrp/lisp/meta.lisp

[changing package from "COMMON-LISP-USER" to "ECOCYC"]

;; Select E. coli as the current organism

EC(1): (select-organism :org-id 'ecoli)
ECOLI

;; Count the number of genes in the KB.

EC(1): (length (get-class-all-instances '|Genes|))
4425

;; Find all genes whose nucleotide position on the chromosome is
;; less than 10,000.

EC(3):  (loop for x in (get-class-all-instances '|Genes|)
for pos = (get-slot-value x 'left-end-position)
when (and pos (< pos 10000))
collect x)
(EG11512 EG11555 EG10998 EG11000 EG10999 EG11556
 EG11511 G6081 EG10011 EG11277)

;; Set variable g to the previous result.

EC(4): (setq g *)
(EG11512 EG11555 EG10998 EG11000 EG10999 EG11556
 EG11511 G6081 EG10011 EG11277)

;; Load the example.lisp file from the PTools web site, which
;; defines various additional functions.  You can write you own
;; additional functions in such files.

EC(5): (load "~/examples")
;; Loading ~/examples.lisp

;; Print the previously generated list of genes as a table.

EC(6): (object-table g)
EG11512                             b0010
EG11555                             b0007
EG10998                             thrA
EG11000                             thrC
EG10999                             thrB
EG11556                             talB
EG11511                             mog
G6081                               b0005
EG10011                             b0006
EG11277                             thrL
NIL

;; End our session

EC(7): (exit)
; killing "Initial Lisp Listener"
; Exiting Lisp

Storing Queries in Files

You can create a .lisp file containing functions that you define that store queries and associated functions so that you can reuse them in the future. The file will define one or more Lisp functions (procedures). For example, the following file defines a function that counts the number of monomers present in the current DB. All lisp files you create for use with the Pathway Tools should begin with the line (in-package :ecocyc) to select the proper Lisp package (namespace).

(in-package :ecocyc)

(defun num-monomers ()
  (length (get-class-all-instances '|Polypeptides|))
  )

To define or redefine this function within your Lisp session, load the file using the Lisp load function. If the preceding file was called monomers.lisp in your home directory, you could load it into your session by typing:

(load "~/monomers")