(in-package :ecocyc)

;;  This file contains example Lisp functions for querying Pathway Tools
;;  databases and for generating tables from the results.

;;  This file contains two sections:
;; 1. Example Table-Generating Fuctions -- Describes utilities that are
;;    useful for displaying query results.
;; 2. Example Queries -- Lists a number of example queries

;; ======================================================================

;;                 1. Example Table-Generating Functions
;;
;; The functions in this first section are useful for displaying query results.
;; Typically (but not necessarily) a query returns a list of object identifiers.
;; This functions print a more meaningful description of each object, one per line.


;; Given a list of frame names, prints a table of frame names and human-readable
;; names.  The optional Format argument selects among different ways of formatting
;; the two columns: :Columns prints fixed-width columns, :Tab separates the
;; columns with a single tab, and :Space separates the columns with a single space.

(defun object-table (object-list &optional (format :columns))
  (loop for x in object-list
      for fname = (get-frame-name x)
      do
	(ecase format
	  (:columns (format t "~35A ~A~%" fname (get-name-string x)))
	  (:tab     (format t "~A	~A~%" fname (get-name-string x)))
	  (:space   (format t "~A ~A~%" fname (get-name-string x)))
	  ) )
  )


;; Print a list of genes in table form containing, on each line:
;;   ecocyc-gene-id  ecocyc-gene-name  b-number  product-name
;;
;; Example usage:  (gene-table (find-gene-by-substring "trp"))

(defun gene-table (gene-list)
  (loop for g in gene-list
      for fname = (get-frame-name g)
      for prod = (get-slot-value g 'product)
      for bn = (blattner-gene-id g)
      do
	(format t "~20A ~20A ~20A ~A~%"
		fname
		(get-slot-value g 'common-name)
		(or bn "")
		(if prod (get-name-string prod) "")
		)
	) )


;; This macro sends all output generated by Body that would normally go
;; to the terminal to the file named by Filename.
;;
;;   Example usage:
;;      (tofile "~/genes.dat" (gene-table (find-gene-by-substring "trp")))

(defmacro tofile (filename &body body)
  `(with-open-file (file ,filename
		    :direction :output
		    :if-exists :supersede)
     (let ((*standard-output* file))
       ,@body) )
  )



;; ======================================================================

;;                 2. Example Queries

;; To run these sample queries, invoke the Pathway Tools from Unix as:
;;
;;    pathway-tools -lisp
;;
;; The next prompt obtained will be the Lisp listener, to which you can
;; type Lisp expression such as:
;; 
;;    (load "examples.lisp")
;;
;; which will load all of the functions in this file.  You can then run
;; a given query by running a function by typing, for example,
;;    (atp-inhibits)
;;
;; Each example query returns a list of object identifiers.  The results
;; are typically printed using a function such as object-table, or else
;; are viewed using the Answer List within the Pathway/Genome Navigator.
;; For example:   
;;    (replace-answer-list (oxidoreductases))
;;    (eco)
;;    [click on Next-Answer]


;;    Find all oxidoreductases
;;    The query iterates through all instances of the EcoCyc class for
;;  the Enzyme Commission class 1, which is oxidoreductases, and uses a
;;  built-in function that returns all enzymes that catalyze each of those
;;  reactions, and appends together the results.

(defun oxidoreductases ()
  (loop for x in (get-class-all-instances 'EC-1)
      append (enzymes-of-reaction x) )
  )


;;   Find all enzymes for which pyruvate is a substrate
;;   The query iterates through all instances of the class Reactions;
;;  for those instances whose substrates slot contains pyruvate,
;;  the query appends together the enzymes that catalyzes those reactions.

(defun pyrsubs ()
    (loop for x in (get-class-all-instances '|Reactions|)
	when (member-slot-value-p x 'substrates 'pyruvate)
	append (enzymes-of-reaction x) )
  )



;;   Find all enzymes for which ATP is an inhibitor

(defun atp-inhibits ()
    (loop for x in (get-class-all-instances '|Regulation-of-Enzyme-Activity|)
	when (and (member-slot-value-p x 'regulator 'atp)
		  (member-slot-value-p x 'mode "-" :test #'fequal) )
	collect (get-slot-value (get-slot-value x 'regulated-entity) 'enzyme) )
  )


;;   Find all enzymes for which pyridoxal phosphate is a prosthetic group.

(defun pp-prosthetic ()
    (loop for x in (get-class-all-instances '|Enzymatic-Reactions|)
	when (member-slot-value-p x 'prosthetic-groups 'Pyridoxal_Phosphate)
	collect (get-slot-value x 'enzyme) )
  )


;;   Find all enzymes in the TCA cycle

(defun tca-enzymes ()
    (loop for x in (get-slot-values 'TCA 'reaction-list)
	append (enzymes-of-reaction x) )
  )


;;   Find all transporters for L-lysine

(defun lysine-transporters ()
    (loop for x in (all-rxns :transport)
	when (member-slot-value-p x 'substrates 'Lys)
	append (enzymes-of-reaction x) )
  )


;;   Find all enzymes that accept glutamine and ammonia as
;;  alternative substrates

(defvar *enzymes*)

(defun gltamm-subs ()
  (setq *enzymes* nil)
  (loop for x in (get-class-all-instances '|Enzymatic-Reactions|)
      do (loop for item in (get-slot-values x 'alternative-substrates)
	     when (or (and (fequal 'AMMONIA (first item))
			   (find 'GLN (rest item)) )
		      (and (fequal 'GLN (first item))
			   (find 'AMMONIA (rest item)) ) 
		      )
	     do (push (get-slot-value x 'enzyme) *enzymes*)
		) )
  )


;;  Find all genes that contain a given name as their common name or
;; as a synonym:

(defun find-gene-by-name (name)
  (loop for g in (get-class-all-instances '|Genes|)
      when (member-slot-value-p g 'names name)
      collect g)
  )


;;  Find all that genes that contain a given substring within their
;;  common name or synonym list.  The use of the string-equal test
;;  ensures case-insensitve matching.  The result variable is used
;;  because if we use a collect within the second loop, its result
;;  will not be collected by the first loop.

(defun find-gene-by-substring (substring)
  (let (result)
    (loop for g in (get-class-all-instances '|Genes|)
	do
	  (loop for name in (get-slot-values g 'names)
	      when (search substring name :test #'string-equal)
	      do (pushnew g result)
		 ) )
    result
    ) )