pair-api.scm

;
; pair-api.scm
;
; Define a matrix-API object for accessing word pairs.
;
; Copyright (c) 2013, 2014, 2017 Linas Vepstas
;
; ---------------------------------------------------------------------
; OVERVIEW
; --------
; The object below defines an API to access pairs of natural language
; word-pairs, stored in the AtomSpace, as a rank-2 matrix, i.e. as a
; matrix of (left, right) word pairs.  This provides exactly the API
; needed for use with the `(use-modules (opencog matrix))` statistical
; analysis subsystem.
;
; The specific Atomese uses this structure:
;
;     EdgeLink
;         BondNode "ANY"
;         ListLink
;             WordNode "left-word"
;             WordNode "right-word"
;
; The above is meant to be a special case of a general, generic form
; of item pairs; for example:
;
;     EvaluationLink
;         PredicateNode "*-Item pairs-*"
;         ListLink
;             ItemNode "left item"
;             ItemNode "right item"
;
; The generic form can be created with the `make-evaluation-pair-api`
; object. The special-case form is used because EdgeLinks require less
; RAM than EvaluationLinks.
; ---------------------------------------------------------------------
;
(use-modules (srfi srfi-1))
(use-modules (opencog))
(use-modules (opencog matrix))

; ---------------------------------------------------------------------

(define-public (make-any-link-api)
"
  make-any-link-api -- Word-pair access methods.

  This implements a word-pair object, where the two words are connected
  with a BondNode \"ANY\", in an EdgeLink.

  That is, a word pair is represented as:

    EdgeLink
       BondNode \"ANY\"
       ListLink
          WordNode \"word\"
          WordNode \"bird\"

  The above provides a location for storing various counts, frequencies,
  entropies, etc pertaining to this particular pair.

  The 'get-pair method returns the above EdgeLink, if it exists.
  The 'make-pair method will create it, if it does not exist.

  Left-side counts, frequencies, etc. such as N(*,y) P(*,y) or
  log_2 P(*,y) will be placed on the left-marginal, which is returned
  by the 'left-wildcard method:

    EdgeLink
       BondNode \"ANY\"
       ListLink
          AnyNode \"left-word\"
          WordNode \"bird\"

  The corresponding N(x,*) P(x,*) etc are hung on the right-marginal,
  returned by the 'right-wildcard method:

    EdgeLink
       BondNode \"ANY\"
       ListLink
          WordNode \"word\"
          AnyNode \"right-word\"

  Finally, the 'left-type and 'right-type methods return the type
  of the the two sides of the pair.
"
	; Just use the generic code to implement the above.
	(make-edge-pair-api
		'EdgeLink
		(BondNode "ANY")
		'WordNode
		'WordNode
		(AnyNode "left-word")
		(AnyNode "right-word")
		"ANY"
		"Link Grammar ANY link Word Pairs")
)

; ---------------------------------------------------------------------