### Scheme Example: Batch Word Pair Processing

Source: https://github.com/opencog/matrix/blob/master/README.md

A reference to a Scheme implementation for batch processing word pairs, demonstrating the practical application of the described APIs.

```scheme
#| Example file: scm/batch-word-pair.scm
   (This is a placeholder for actual code content)
   (load "object-api.scm")
   (load "eval-pair.scm")
   (define (process-word-pairs data)
     (let* ((api (make-word-pair-api data))
            (support-api (add-support-api api))
            (freq-api (add-pair-freq-api api))
            (compute-api (add-support-compute api)))
       ;; Example usage:
       (display "Total pairs: ") (display (N-star-star support-api)) (newline)
       (display "Row sums: ") (display (N-x-star support-api 'word1)) (newline)
       (display "Column sums: ") (display (N-star-y support-api 'word2)) (newline)
       ;; ... further computations and reporting ...
       ))
```

--------------------------------

### Scheme API for Matrix Creation

Source: https://github.com/opencog/matrix/blob/master/README.md

Provides an example of how to define a matrix structure using Scheme, specifically referencing the `make-edge-pair-api` function for setting up matrix views from EdgeLinks.

```Scheme
;; Conceptual Scheme code for defining a matrix view
;; from an EdgeLink structure in the AtomSpace.

;; Assume 'atom-space' is a handle to the AtomSpace.
;; Assume 'edge-link-node' is a node representing an EdgeLink.

;; Function to create a matrix view from an EdgeLink
;; Parameters:
;;   atom-space: The AtomSpace instance.
;;   edge-link-node: The EdgeLink node to process.
;;   row-atom-type: The type of atom to use for rows (e.g., 'WordNode').
;;   col-atom-type: The type of atom to use for columns (e.g., 'WordNode').
;;   predicate-name: The name of the PredicateNode identifying the pair (e.g., "word-pair").
;;   value-extractor: A function to extract the numeric value (e.g., count) from the EdgeLink.

(define (make-edge-pair-api atom-space edge-link-node row-atom-type col-atom-type predicate-name value-extractor)
  ;; ... implementation details ...
  ;; This function would identify all EdgeLinks matching the predicate,
  ;; extract the left/right atoms, and use the value-extractor
  ;; to populate a matrix representation.
  (let* [
    (matrix-definition (list 'matrix
                           (list 'source 'edgelink)
                           (list 'predicate predicate-name)
                           (list 'row-type row-atom-type)
                           (list 'column-type col-atom-type)))
    ;; ... further processing to build the matrix ...
  ]
    ;; Return a representation of the matrix or a handle to it
    matrix-definition))

;; Example Usage:
;; (define my-word-matrix (make-edge-pair-api atom-space my-edgelink-node 'WordNode 'WordNode "word-pair" (lambda (node) (get-attribute node 'count))))
```

--------------------------------

### Setup AsMatrix CMake Package Configuration

Source: https://github.com/opencog/matrix/blob/master/cmake/CMakeLists.txt

This CMake script generates the necessary configuration files (AsMatrixConfig.cmake and AsMatrixConfigVersion.cmake) for the AsMatrix package. It allows users to integrate AsMatrix into their projects using `find_package(AsMatrix REQUIRED 2.0.0)`. The script sets the package version and defines the installation destination for the configuration files.

```CMake
# CMake boilerplate that allows users to do
#    find_package(AsMatrix REQUIRED 2.0.0)
# and have it work.

include(CMakePackageConfigHelpers)

set(ConfigPackageLocation lib/cmake/AsMatrix)

#install(EXPORT AsMatrixTargets
#	FILE AsMatrixTargets.cmake
#	DESTINATION ${ConfigPackageLocation}
#)

SET(SEMANTIC_VERSION 2.0.0)

configure_package_config_file(AsMatrixConfig.cmake.in
	${CMAKE_CURRENT_BINARY_DIR}/AsMatrixConfig.cmake
	INSTALL_DESTINATION ${ConfigPackageLocation}
	PATH_VARS CMAKE_INSTALL_PREFIX
)

write_basic_package_version_file(
	"${CMAKE_CURRENT_BINARY_DIR}/AsMatrixConfigVersion.cmake"
	VERSION ${SEMANTIC_VERSION}
	COMPATIBILITY SameMajorVersion
)

INSTALL(FILES
	${CMAKE_CURRENT_BINARY_DIR}/AsMatrixConfigVersion.cmake
	${CMAKE_CURRENT_BINARY_DIR}/AsMatrixConfig.cmake
	DESTINATION ${ConfigPackageLocation}
)
```

--------------------------------

### Enable Testing and Include CxxTest

Source: https://github.com/opencog/matrix/blob/master/tests/CMakeLists.txt

Configures CMake to enable testing and includes the CxxTest framework for unit testing. This is a common setup for projects using CxxTest.

```cmake
ENABLE_TESTING()
INCLUDE(AddCxxtest)
```

--------------------------------

### Scheme Implementation Example (Conceptual)

Source: https://github.com/opencog/matrix/blob/master/design/Design-similarity.md

Illustrates the conceptual structure of the original matrix API as implemented in Scheme, highlighting its object-oriented design and data storage.

```scheme
;; Conceptual example of the original matrix API structure in Scheme

;; Base class definition (conceptual)
(define-class matrix-api-base
  (methods
    ('left-type (lambda (edge) ...))
    ('right-type (lambda (edge) ...))
    ('pair-type (lambda (edge) ...))
    ('left-element (lambda (edge) ...))
    ('right-element (lambda (edge) ...))
    ('get-all-edges (lambda () ...))
    ('get-edges-from-storage (lambda (node) ...))
    ('delete-all-edges (lambda () ...))
    ('left-basis (lambda () ...))
    ('right-basis (lambda () ...))
    ('in-left-basis? (lambda (atom) ...))
    ('in-right-basis? (lambda (atom) ...))
    ('left-duals (lambda (atom) ...))
    ('right-duals (lambda (atom) ...))))

;; Example of adding decorations
(define (add-pair-stars api-instance) ...)

;; Concrete example usage (hypothetical)
(define my-matrix-api (make-instance 'matrix-api-base))
(define first-edge (car (send my-matrix-api 'get-all-edges)))
(define left-v (send my-matrix-api 'left-element first-edge))
(define left-basis-set (send my-matrix-api 'left-basis))
```

--------------------------------

### Include OpenCog CMake Modules

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Includes several custom CMake modules provided by OpenCog. These modules likely contain common configurations for GCC options, library options, installation paths, and build summaries.

```cmake
include(OpenCogGccOptions)
include(OpenCogLibOptions)
include(OpenCogInstallOptions)
include(Summary)
```

--------------------------------

### Find AtomSpace Postgres Support

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Searches for AtomSpace's PostgreSQL support package. If found, it prints a status message and defines a preprocessor macro. This support is noted as being needed for unit tests.

```cmake
# Needed for unit tests
FIND_PACKAGE(AtomSpacePgres)
IF (ATOMSPACE_PGRES_FOUND)
	MESSAGE(STATUS "AtomSpace Postgres found.")
	ADD_DEFINITIONS(-DHAVE_ATOMSPACE_PGRES)
	SET(HAVE_ATOMSPACE_PGRES 1)
ELSE (ATOMSPACE_PGRES_FOUND)
	MESSAGE(STATUS "AtomSpace Postgres missing: needed for unit tests.")
ENDIF (ATOMSPACE_PGRES_FOUND)
```

--------------------------------

### Configure Build Type Options

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Allows users to select the build type (e.g., Release, Debug, Coverage, Profile, RelWithDebInfo). If no build type is explicitly set, it defaults to 'Release'. The selected build type is then printed to the console.

```cmake
# Uncomment to be in Release mode [default].
# SET(CMAKE_BUILD_TYPE Release)

# Uncomment to build in debug mode.
# SET(CMAKE_BUILD_TYPE Debug)

# Uncomment to be in coverage testing mode.
# SET(CMAKE_BUILD_TYPE Coverage)

# Uncomment to build in profile mode.
# SET(CMAKE_BUILD_TYPE Profile)

# Uncomment to build in release mode with debug information.
# SET(CMAKE_BUILD_TYPE RelWithDebInfo)

# default build type
IF (CMAKE_BUILD_TYPE STREQUAL "")
	SET(CMAKE_BUILD_TYPE Release)
ENDIF (CMAKE_BUILD_TYPE STREQUAL "")

MESSAGE(STATUS "Build type: ${CMAKE_BUILD_TYPE}")
```

--------------------------------

### Add CMake Definitions

Source: https://github.com/opencog/matrix/blob/master/tests/CMakeLists.txt

Adds preprocessor definitions to the build process. This snippet defines `PROJECT_SOURCE_DIR` and `PROJECT_BINARY_DIR` for use during compilation.

```cmake
ADD_DEFINITIONS(-DPROJECT_SOURCE_DIR="${CMAKE_SOURCE_DIR}"
                -DPROJECT_BINARY_DIR="${CMAKE_BINARY_DIR}")
```

--------------------------------

### CMake: Summary Information

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Displays summary information about found packages and configured features, such as Doxygen and CXXTEST, to inform the user about the build configuration.

```cmake
FIND_PACKAGE(Doxygen)

SUMMARY_ADD("Matrix" "AtomSpace Sparse Matrix Tools" HAVE_ATOMSPACE)
SUMMARY_ADD("Doxygen"    "Code documentation" DOXYGEN_FOUND)

IF (HAVE_ATOMSPACE_PGRES)
	SUMMARY_ADD("Unit tests" "Unit tests" CXXTEST_FOUND)
ELSE (HAVE_ATOMSPACE_PGRES)
	IF (CXXTEST_FOUND)
		SUMMARY_ADD("Unit tests" "Some but not all unit tests (atomspace-pgres missing)" CXXTEST_FOUND)
	ELSE (CXXTEST_FOUND)
		SUMMARY_ADD("Unit tests" "Unit tests" CXXTEST_FOUND)
	ENDIF (CXXTEST_FOUND)
ENDIF (HAVE_ATOMSPACE_PGRES)

SUMMARY_SHOW()
```

--------------------------------

### OpenCog Matrix Operations Overview

Source: https://github.com/opencog/matrix/blob/master/README.md

This section outlines the core matrix operations and analytical tools provided by the OpenCog matrix library. These tools enable users to perform statistical analysis, similarity computations, and data transformations on data represented as matrices within the AtomSpace.

```APIDOC
Matrix Operations in OpenCog AtomSpace:

This library exposes portions of the AtomSpace as matrices, facilitating analysis of relationships between atoms. Data is structured as ordered pairs (x,y) with associated values, typically observation counts N(x,y), which can be normalized to frequencies p(x,y).

Core Functionalities:

- Row and column subtotals (marginals): Compute sums across rows or columns.
- Frequency computation and caching: Calculate and store normalized frequencies from observation counts.
- Mutual Information (MI) computation and caching:
  - For pairs: Calculate MI for individual (x,y) pairs.
  - Marginal MI: Calculate MI based on marginal probabilities.
  - Between rows/columns: Calculate MI between entire rows or columns.
- Similarity measures:
  - Cosine similarity: Compute similarity between rows or columns based on vector dot products.
  - Jaccard similarity: Compute similarity based on set overlap for rows or columns.
- Matrix concatenation (direct sum): Combine dissimilar matrices.
- Principal Component Analysis (PCA): Perform dimensionality reduction on the matrix.
- Data filtering and removal (cuts):
  - Filter: Hide unwanted rows, columns, or entries.
  - Remove: Delete unwanted entries from the AtomSpace.

Usage Example (Conceptual):

To define a matrix from an EdgeLink structure:
Use `make-edge-pair-api` to specify atom types for rows/columns and the PredicateNode identifier.

Example of a word-pair observation:
```
    EdgeLink   (count=6789)
        PredicateNode "word-pair"
        ListLink
            WordNode "foo"
            WordNode "bar"
```
This indicates the pair ('foo', 'bar') was observed 6789 times. The library can process such structures to build matrices for analysis.
```

--------------------------------

### Low-Level API and Basic Definitions

Source: https://github.com/opencog/matrix/blob/master/README.md

Defines the fundamental low-level API requirements for objects that describe pairs and their associated counts. It introduces notation for pair counts N(x,y) and describes classes for reporting marginal sums and frequencies.

```APIDOC
Low-Level API:
  Requires implementation of an object that describes pairs and provides methods to retrieve them and their associated counts.

Notation:
  N(x,y): Observed count on the pair of atoms (x,y).

add-support-api:
  Provides methods to report partial sums N(x,*) = sum_y N(x,y) and N(*,y) = sum_x N(x,y), as well as the total N(*,*) = sum_x sum_y N(x,y).

add-pair-freq-api:
  Provides methods to report frequencies p(x,y) = N(x,y)/N(*,*), and partial sums p(x,*) = sum_y p(x,y) and p(*,y) = sum_x p(x,y).

add-report-api:
  Provides methods to report summary information about the matrix, including dimensions, total non-zero entries, left entropy, right entropy, and mutual information.
```

--------------------------------

### Find and Configure AtomSpace Dependency

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Searches for the AtomSpace package, requiring version 5.0.3. If found, it prints a status message and defines a preprocessor macro. If not found, it halts the build with a fatal error.

```cmake
# AtomSpace
FIND_PACKAGE(AtomSpace 5.0.3 CONFIG REQUIRED)
IF (ATOMSPACE_FOUND)
	MESSAGE(STATUS "AtomSpace found.")
	ADD_DEFINITIONS(-DHAVE_ATOMSPACE)
	SET(HAVE_ATOMSPACE 1)
ELSE (ATOMSPACE_FOUND)
	MESSAGE(FATAL_ERROR "AtomSpace missing: it is needed!")
ENDIF (ATOMSPACE_FOUND)
```

--------------------------------

### Support Set and Wildcard Pair Methods

Source: https://github.com/opencog/matrix/blob/master/README.md

Details methods for accessing support sets and wildcard representations of pairs within the matrix. These are useful for iterating over rows and columns.

```APIDOC
add-pair-stars:
  Methods to fetch:
    - left-support-set: The set {x | the atom x occurs in some pair (x,y)}.
    - right-support-set: The set {y | the atom y occurs in some pair (x,y)}.
    - right-star: The set of wildcard pairs (x,*) = {(x,y) | x is fixed and y is any atom in the pair}.
    - left-star: The set of wildcard pairs (*,y) = {(x,y) | y is fixed and x is any atom in the pair}.
```

--------------------------------

### General Tensor Query Structure

Source: https://github.com/opencog/matrix/blob/master/design/Design-similarity.md

Presents the general structure for a tensor query, including variable lists, AND links (patterns), and rewrite rules for defining marginals.

```Atomese
(Query
    (VariableList VAR-1 VAR-2 ... VAR-N)
    (AndLink PATTERN-TERM-1 PATTERN-TERM-2 ... PATTERN-TERM-K)
    REWRITE-1
    REWRITE-2
    ...
    REWRITE-M)
```

--------------------------------

### Add Project Definitions

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Adds preprocessor definitions to be used by the compiler. These definitions provide the build system's source and binary directories to the compiled code.

```cmake
ADD_DEFINITIONS(-DPROJECT_SOURCE_DIR="${CMAKE_SOURCE_DIR}"
                -DPROJECT_BINARY_DIR="${CMAKE_BINARY_DIR}")
```

--------------------------------

### Query for Word Pairs

Source: https://github.com/opencog/matrix/blob/master/design/Design-similarity.md

Demonstrates how to query for all word pairs. It defines variables for the left and right words and specifies the pattern to match the 'word-pair' edge structure.

```Atomese
(Query
   (VariableList
      (TypedVariable (Variable "$left") (Type 'Word))
      (TypedVariable (Variable "$right") (Type 'Word)))
   (Present
      (Edge (Predicate "word-pair")
         (List (Variable "$left") (Variable "$right"))))
   (Edge (Predicate "word-pair")
      (List (Variable "$left") (Variable "$right"))))
```

--------------------------------

### Find and Configure CogUtil Dependency

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Searches for the CogUtil package, requiring version 2.0.1. If found, it prints the version and defines a preprocessor macro. If not found, it halts the build with a fatal error.

```cmake
# Cogutil
FIND_PACKAGE(CogUtil 2.0.1 CONFIG REQUIRED)
IF (COGUTIL_FOUND)
	MESSAGE(STATUS "CogUtil version ${COGUTIL_VERSION} found.")
	ADD_DEFINITIONS(-DHAVE_COGUTIL)
	SET(HAVE_COGUTIL 1)
ELSE (COGUTIL_FOUND)
	MESSAGE(FATAL_ERROR "CogUtil missing: it is needed!")
ENDIF (COGUTIL_FOUND)
```

--------------------------------

### Set Default Include Directories

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Configures the default include paths for the project. It adds the project's source directory and the include directories from CogUtil and AtomSpace, making their headers accessible during compilation.

```cmake
# Set default include paths.
INCLUDE_DIRECTORIES(${PROJECT_SOURCE_DIR}
	${COGUTIL_INCLUDE_DIR} ${ATOMSPACE_INCLUDE_DIR})
```

--------------------------------

### CMake Include and Link Directories

Source: https://github.com/opencog/matrix/blob/master/tests/matrix/CMakeLists.txt

Configures include directories and library search paths for the project using INCLUDE_DIRECTORIES and LINK_DIRECTORIES commands. These paths are essential for the compiler and linker to find necessary header files and libraries during the build process.

```cmake
INCLUDE_DIRECTORIES (
	${PROJECT_SOURCE_DIR}/opencog/atomspace
	${PROJECT_SOURCE_DIR}/opencog/guile
	${PROJECT_SOURCE_DIR}/opencog/util
)

LINK_DIRECTORIES(
	${PROJECT_BINARY_DIR}/opencog/atomspace
	${PROJECT_BINARY_DIR}/opencog/guile
	${PROJECT_BINARY_DIR}/opencog/util
)
```

--------------------------------

### CMake: Add Subdirectories and Configure Build

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Configures the build by adding subdirectories for the project and its components. It conditionally includes test subdirectories based on CXXTEST availability, setting up the overall build structure.

```cmake
ADD_SUBDIRECTORY(cmake)
ADD_SUBDIRECTORY(opencog)

IF (CXXTEST_FOUND)
	ADD_SUBDIRECTORY(tests EXCLUDE_FROM_ALL)
ENDIF (CXXTEST_FOUND)
```

--------------------------------

### CMake: Include Build Directory

Source: https://github.com/opencog/matrix/blob/master/opencog/CMakeLists.txt

Configures CMake to include the binary directory in the search path for include files. This is essential for locating generated header files during the build process.

```cmake
INCLUDE_DIRECTORIES(${CMAKE_BINARY_DIR})
```

--------------------------------

### Find CxxTest for Unit Tests

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Searches for the CxxTest testing framework, which is required for running unit tests. If CxxTest is not found, a status message is printed, but the build does not necessarily fail.

```cmake
# Needed for unit tests

FIND_PACKAGE(Cxxtest)
IF (NOT CXXTEST_FOUND)
	MESSAGE(STATUS "CxxTest missing: needed for unit tests.")
ENDIF (NOT CXXTEST_FOUND)
```

--------------------------------

### Original Matrix API Methods

Source: https://github.com/opencog/matrix/blob/master/design/Design-similarity.md

Details methods from the original matrix API, designed for working with word-pairs and sparse vectors. These methods formed the base class for higher analysis layers.

```APIDOC
Original Matrix API Methods:

1. Get Vertex/Edge Types:
   - `'left-type`: Get the type of the left vertex.
   - `'right-type`: Get the type of the right vertex.
   - `'pair-type`: Get the type of the edge.

2. Get Vertices from Edge:
   - `'left-element`: Given an edge, get the left vertex.
   - `'right-element`: Given an edge, get the right vertex.

3. Matrix Wildcards (Marginals):
   - Get left wild-cards (edges with left vertex replaced by wildcard).
   - Get right wild-cards (edges with right vertex replaced by wildcard).

4. List All Edges:
   - Provides a list of all edges.

5. Get Edges from StorageNode:
   - Ability to retrieve all edges associated with a StorageNode.

6. Delete All Edges:
   - Deletes all edges and their corresponding entries from a StorageNode.

7. Basis Elements:
   - `'left-basis`: Lists the left basis elements (set of all x such that (x,y) exists for some y).
   - `'right-basis`: Lists the right basis elements (set of all y such that (x,y) exists for some x).

8. Basis Size:
   - Size of the left basis.
   - Size of the right basis.

9. Basis Membership Predicates:
   - `'in-left-basis?`: True if an Atom appears in the left basis set.
   - `'in-right-basis?`: True if an Atom appears in the right basis set.

10. Duals of an Atom:
    - `'left-duals`: List of left duals for a given Atom Y (set of x such that (x,Y) is fixed for Y).
    - `'right-duals`: List of right duals for a given Atom Y (set of y such that (Y,y) is fixed for Y).

Additional API:

- `add-pair-stars`: Adds decorations needed by most higher layers.
```

--------------------------------

### Include OpenCog Macros and Guile Configuration

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Includes additional custom CMake modules for common OpenCog macros and Guile-specific configurations. These modules likely provide utility functions and settings for integrating Guile with the project.

```cmake
INCLUDE(OpenCogMacros)
INCLUDE(OpenCogGuile)
```

--------------------------------

### CMake: Configure Debian Package (CPack)

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Configures CPack to generate a Debian package for the project. It sets package metadata, dependencies, and specific Debian options like section and homepage.

```cmake
EXECUTE_PROCESS(COMMAND  dpkg --print-architecture
	OUTPUT_VARIABLE PACKAGE_ARCHITECTURE
	OUTPUT_STRIP_TRAILING_WHITESPACE)
STRING(TIMESTAMP UTC_DATE "%Y%m%d" UTC)
FILE(WRITE "${PROJECT_BINARY_DIR}/install_manifest.txt")

SET(CPACK_GENERATOR "DEB")
SET(CPACK_PACKAGE_CONTACT "opencog@googlegroups.com")
SET(CPACK_PACKAGE_DESCRIPTION_FILE "${CMAKE_CURRENT_SOURCE_DIR}/README.md")
SET(CPACK_PACKAGE_DIRECTORY "${CMAKE_BINARY_DIR}/packages")
SET(CPACK_PACKAGE_DESCRIPTION_SUMMARY "The AtomSpace Matrix Toolset")
SET(CPACK_PACKAGE_NAME "atomspace-matrix-dev")
SET(CPACK_PACKAGE_VENDOR "opencog.org")
SET(CPACK_PACKAGE_VERSION "${SEMANTIC_VERSION}-${UTC_DATE}")
SET(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE")
SET(CPACK_PACKAGE_FILE_NAME
	"${CPACK_PACKAGE_NAME}_${CPACK_PACKAGE_VERSION}_${PACKAGE_ARCHITECTURE}")
SET(CPACK_PACKAGING_INSTALL_PREFIX "/usr/local")

SET(DEPENDENCY_LIST
	"guile-3.0-dev (>= 3.0.0)"
	"libstdc++6 (>= 7.0)"
	"libcogutil-dev (>= 2.0.2)"
	"atomspace-dev (>= 5.0.3)"
)

STRING(REPLACE ";" ", " MAIN_DEPENDENCIES "${DEPENDENCY_LIST}")
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "${MAIN_DEPENDENCIES}")
SET(CPACK_DEBIAN_PACKAGE_SECTION "libdevel")
SET(CPACK_DEBIAN_PACKAGE_HOMEPAGE "http://opencog.org")
INCLUDE(CPack)
```

--------------------------------

### Filtering with Rule and FilterLink

Source: https://github.com/opencog/matrix/blob/master/design/Design-similarity.md

Demonstrates how to extract specific elements (e.g., the left element) from a pattern using a combination of Rule and FilterLink, limiting the search space to an input vector.

```Atomese
(Filter
      (Rule
         (VariableList
            (TypedVariable (Variable "$left") (Type 'Word))
            (TypedVariable (Variable "$right") (Type 'Word)))
         (Edge (Predicate "word-pair")
            (List (Variable "$left") (Variable "$right")))
         (Variable "$left"))
      (List
         (Edge (Predicate "word-pair")
            (Word "some") (Word "thing"))))
```

--------------------------------

### CMake: Generate Cscope Database

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Creates a custom target 'cscope' to generate a cscope database for code navigation. It finds relevant source and header files and then invokes the 'cscope' command.

```cmake
ADD_CUSTOM_TARGET(cscope
	COMMAND find opencog examples tests -name '*.cc' -o -name '*.h' -o -name '*.cxxtest' -o -name '*.scm' > ${CMAKE_SOURCE_DIR}/cscope.files
	COMMAND cscope -b
	WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
	COMMENT "Generating CScope database"
)
```

--------------------------------

### Matrix Data Representation in AtomSpace

Source: https://github.com/opencog/matrix/blob/master/README.md

Explains how data, particularly observed pairs of atoms, is structured and represented as matrices within the OpenCog AtomSpace, including the role of observation counts and frequencies.

```APIDOC
AtomSpace Matrix Structure:

Data in the AtomSpace can be viewed as a matrix where:
- Rows correspond to identifiable 'left' atoms or sub-parts.
- Columns correspond to identifiable 'right' atoms or sub-parts.
- Each pair (row, column) has an associated numeric value, N(x,y).

Commonly, N(x,y) represents an observation count of the pair (x,y).
This count can be used to compute:
- Normalized frequency p(x,y) = N(x,y) / TotalObservations.

These counts and frequencies form a sparse correlation matrix.

Example Data Structure (Word Pairs):

```
    EdgeLink   (count=N)
        PredicateNode "predicate-type"
        ListLink
            LeftAtomType "left-atom"
            RightAtomType "right-atom"
```

Here, 'N' is the observation count for the pair ('left-atom', 'right-atom') under the 'predicate-type'. The library allows generic identification of such structures to build matrices.
```

--------------------------------

### Tuple Math for Rows and Columns

Source: https://github.com/opencog/matrix/blob/master/README.md

The `add-tuple-math` class enables applying arbitrary functions to sets of rows or columns. It allows defining new matrix entries based on tuples of underlying matrix elements, facilitating operations like sums, differences, min/max, and custom aggregations.

```APIDOC
add-tuple-math:
  Description: Applies arbitrary functions to sets of rows or columns.
  Functionality:
    Defines new matrix entries based on tuples (pairs, triples, etc.) of underlying matrix elements.
    Example: For an entry (x, [y,z,w]), the value is (x, f((x,y), (x,z), (x,w))),
    where 'f' is a user-defined function.
  Supported Operations:
    Summing and differencing columns.
    Element-wise min or max of a set of columns.
    Counting entries non-zero across sets of columns.
    Arbitrary function application to tuples of matrix elements.
```

--------------------------------

### Find Guile Support

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Includes a custom CMake module to find Guile, a Scheme interpreter. This is part of the configuration process for projects that integrate with Guile.

```cmake
# Is guile installed?

include(OpenCogFindGuile)
```

--------------------------------

### Rcpp Integration for R

Source: https://github.com/opencog/matrix/blob/master/README.md

Describes how Rcpp facilitates interfacing C++ code with R. It provides C++ classes that map directly to R data types, simplifying data transfer and manipulation between the two environments.

```APIDOC
Rcpp Package Description:

The Rcpp package provides C++ classes that greatly facilitate interfacing C or C++ code in R packages using the `.Call()` interface provided by R.

Key Features:

- **Data Type Mapping**: Rcpp provides matching C++ classes for a large number of basic R data types. This allows package authors to keep their data in normal R data structures without worrying about translation or transferring to C++.

- **Bidirectional Data Transfer**: The mapping of data types works in both directions. It is straightforward to pass data from R to C++, as it is to return data from C++ to R.

- **Ease of Use**: Data structures can be accessed as easily at the C++ level and used in the normal manner.

- **Usage**: Typically used within R packages to leverage C++ performance for computationally intensive tasks.

Reference:
- http://dirk.eddelbuettel.com/code/rcpp.html
```

--------------------------------

### Pair Iteration and Computation Methods

Source: https://github.com/opencog/matrix/blob/master/README.md

Describes methods for iterating over matrix elements and computing various statistical measures like partial sums, frequencies, and mutual information.

```APIDOC
add-loop-api:
  Provides methods for iterating over non-zero pairs:
    - for-each-pair: Invokes a function on each pair (x,y).
    - map-pair: Returns a list of results from invoking a function on each pair (x,y).
  (Note: Suggests merging with batch-similarity and loop-upper-diagonal).

add-support-compute:
  Methods to compute and cache:
    - Partial sums N(*,y) and N(x,*).
    - Number of non-zero entries in each row or column.
    - Column 'length' (l_p norm): len(y) = sqrt(sum_x N^2 (x,y)).

make-compute-freq:
  Methods to compute and cache frequencies:
    - P(x,y) = N(x,y)/N(*,*)
    - P(*,y) = sum_x P(x,y)
    - P(x,*) = sum_y P(x,y)

make-batch-mi:
  Methods to compute fractional mutual information for all pairs:
    - MI(x,y) = +log_2 P(x,y) / (P(x,*) * P(*,y))

batch-all-pair-mi:
  A convenience class that orchestrates the computation of row/column counts, frequencies, and mutual information for a dataset.
```

--------------------------------

### Set Guile Load Path

Source: https://github.com/opencog/matrix/blob/master/tests/CMakeLists.txt

Configures the `GUILE_LOAD_PATH` variable, specifying the directory where Guile Scheme modules should be loaded from. This is crucial for projects integrating Guile.

```cmake
SET(GUILE_LOAD_PATH "${PROJECT_BINARY_DIR}/opencog/scm")
```

--------------------------------

### Matrix Toolset - Core Functionalities

Source: https://github.com/opencog/matrix/blob/master/README.md

Details the specific analytical functions available for matrix manipulation, including statistical measures, similarity calculations, and dimensionality reduction techniques.

```APIDOC
Matrix Analysis Functions:

- Marginals: Calculate row and column subtotals.
- Frequencies: Compute and cache frequencies from raw counts.
- Mutual Information:
  - `MI(x,y)`: Mutual information between specific pairs.
  - `MarginalMI(x,y)`: Mutual information using marginal probabilities.
  - `RowMI(row_a, row_b)`: Mutual information between two rows.
  - `ColMI(col_a, col_b)`: Mutual information between two columns.
- Similarity:
  - `CosineSimilarity(row_a, row_b)`: Cosine similarity between rows.
  - `JaccardSimilarity(row_a, row_b)`: Jaccard similarity between rows.
- Matrix Operations:
  - `DirectSum(matrix_a, matrix_b)`: Concatenates matrices.
  - `PCA(matrix)`: Performs Principal Component Analysis.
- Filtering/Cutting:
  - `FilterRows(matrix, condition)`: Hides rows based on a condition.
  - `FilterCols(matrix, condition)`: Hides columns based on a condition.
  - `FilterEntries(matrix, condition)`: Hides specific entries.
  - `RemoveRows(matrix, condition)`: Deletes rows from the AtomSpace.
  - `RemoveCols(matrix, condition)`: Deletes columns from the AtomSpace.
  - `RemoveEntries(matrix, condition)`: Deletes specific entries from the AtomSpace.
```

--------------------------------

### Word-Pair Representation

Source: https://github.com/opencog/matrix/blob/master/design/Design-similarity.md

Illustrates the fundamental structure for representing a pair of words. It uses an Edge with a 'word-pair' predicate and a List containing the individual words.

```Atomese
(Edge (Predicate "word-pair") (List (Word "some") (Word "thing")))
```

--------------------------------

### Scheme Matrix Access Object API

Source: https://github.com/opencog/matrix/blob/master/README.md

Defines a minimalist object-oriented API for custom matrix-access objects in Scheme. Users provide methods to specify atom types for rows, columns, and pairs, along with a method to retrieve pair counts.

```APIDOC
Scheme Matrix Access Object API:

This API defines a set of methods that a custom matrix-access object must implement to interact with the OpenCog matrix library.

Methods:

- `'left-type`
  - Description: Returns the atom type of the rows (left-hand side) of the matrix.
  - Parameters: None
  - Returns: An atom type identifier.

- `'right-type`
  - Description: Returns the atom type of the columns (right-hand side) of the matrix.
  - Parameters: None
  - Returns: An atom type identifier.

- `'pair-type`
  - Description: Returns the atom type of the pairs (elements) within the matrix.
  - Parameters: None
  - Returns: An atom type identifier.

- `'pair-count`
  - Description: Returns the count of elements for a given pair (row, column).
  - Parameters:
    - pair: The specific pair (e.g., a tuple or list representing row and column identifiers).
  - Returns: The count associated with the given pair.
```

--------------------------------

### CMake Test Configuration

Source: https://github.com/opencog/matrix/blob/master/tests/matrix/CMakeLists.txt

Configures and adds tests to the build system. It conditionally adds C++ unit tests using ADD_CXXTEST if HAVE_ATOMSPACE_PGRES is defined, and adds Guile tests using ADD_GUILE_TEST.

```cmake
IF (HAVE_ATOMSPACE_PGRES)
	ADD_CXXTEST(VectorAPIUTest)
ENDIF (HAVE_ATOMSPACE_PGRES)

ADD_GUILE_TEST(MarginalTest marginal-test.scm)
```

--------------------------------

### CMake: Run Tests with CTest

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Defines custom targets for running tests, including a general 'check' target that runs tests based on the build type (e.g., with coverage). It also includes specific targets for 'test_mono' and 'test_multi'.

```cmake
IF (CXXTEST_FOUND)
	ADD_CUSTOM_TARGET(tests)

	IF (CMAKE_BUILD_TYPE STREQUAL "Coverage")
		ADD_CUSTOM_TARGET(check
			WORKING_DIRECTORY tests
			COMMAND ${CMAKE_CTEST_COMMAND} --force-new-ctest-process --output-on-failure $(ARGS)
			COMMENT "Running tests with coverage..."
		)
	ELSE (CMAKE_BUILD_TYPE STREQUAL "Coverage")
		ADD_CUSTOM_TARGET(check
			DEPENDS tests
			WORKING_DIRECTORY tests
			COMMAND ${CMAKE_CTEST_COMMAND} --force-new-ctest-process --output-on-failure $(ARGS)
			COMMENT "Running tests..."
		)
	ENDIF (CMAKE_BUILD_TYPE STREQUAL "Coverage")

	ADD_CUSTOM_TARGET(test_mono
		DEPENDS tests
		WORKING_DIRECTORY tests/persist/monospace
		COMMAND ${CMAKE_CTEST_COMMAND} $(ARGS)
		COMMENT "Running Monospace tests..."
	)

	ADD_CUSTOM_TARGET(test_multi
		DEPENDS tests
		WORKING_DIRECTORY tests/persist/matrix
		COMMAND ${CMAKE_CTEST_COMMAND} $(ARGS)
		COMMENT "Running Multispace tests..."
	)
ENDIF (CXXTEST_FOUND)
```

--------------------------------

### CMake Library Linking

Source: https://github.com/opencog/matrix/blob/master/tests/matrix/CMakeLists.txt

Specifies libraries to link against, including project-specific libraries and dependencies like ATOMSPACE_LIBRARIES and COGUTIL_LIBRARY. This ensures that the compiled code can resolve symbols from these libraries.

```cmake
LINK_LIBRARIES(
	# persist-sql
	${ATOMSPACE_LIBRARIES}
	${COGUTIL_LIBRARY}
)
```

--------------------------------

### Execute Left Element Extraction

Source: https://github.com/opencog/matrix/blob/master/design/Design-object-atomese.md

Demonstrates the execution of a pre-defined method to extract the left element from a matrix-like structure. It shows how to provide input data and retrieve the result.

```opencog-lisp
(cog-execute!
	(ExecutionOutputLink
		(DefinedMethodLink
			(Predicate "*-Basic Pairs Matrix-*")
			(Predicate "*-left-element-*"))
		(EvaluationLink
			(Predicate "word pairs matrix")
			(List
				(Word "blue")
				(Word "sky")))))
```

--------------------------------

### Add CogUtil CMake Directory to Search Path

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Appends the 'cmake' directory from the found CogUtil package to CMake's module search path. This allows CMake to find other configuration files or macros provided by CogUtil.

```cmake
# add the 'cmake' directory from cogutil to search path
list(APPEND CMAKE_MODULE_PATH  ${COGUTIL_DATA_DIR}/cmake)
```

--------------------------------

### Add Module Search Path

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Appends the 'lib' directory from the project's source directory to CMake's module search path. This allows CMake to find custom modules located in this directory.

```cmake
list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/lib/")
```

--------------------------------

### Configure CMake Policies

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Sets specific CMake policy behaviors to 'NEW' to ensure consistent behavior across different CMake versions. This is crucial for avoiding warnings and ensuring the script functions as intended.

```cmake
IF (COMMAND CMAKE_POLICY)
	# These must be explicitly set, as otherwise warnings are printed.
	CMAKE_POLICY(SET CMP0003 NEW)
	CMAKE_POLICY(SET CMP0037 NEW)
	CMAKE_POLICY(SET CMP0045 NEW)
ENDIF (COMMAND CMAKE_POLICY)
```

--------------------------------

### Required Atomese Matrix Object Methods

Source: https://github.com/opencog/matrix/blob/master/design/Design-object-atomese.md

Specifies essential methods that every Atomese matrix object must implement to support generic matrix computations. These include methods for accessing matrix elements.

```APIDOC
APIDOC:
  Required Atomese Matrix Object Methods

  Description:
  To facilitate generic matrix computations, all Atomese matrix objects must define a standard set of methods. These methods allow for accessing the structural components of matrix elements, typically the 'left' and 'right' indices or values.

  Mandatory Methods:
  - `(Predicate "*-left-element-*")`: Returns the left element of a matrix entry.
  - `(Predicate "*-right-element-*")`: Returns the right element of a matrix entry.

  Additional Methods:
  The `object-api.scm` file provides a starter set of methods for various matrix operations. These may include methods for constructing triplets from elements or other data access functions.

  Example Matrix Element Form:
  (EvaluationLink
    (Predicate "name of some matrix")
    (List
      (Atom "left or row index")
      (Atom "right or column index")))

  Example Method Implementation (Conceptual):
  (DefineLink
    (DefinedMethodLink
      (Predicate "*-Basic Pairs Matrix-*")
      (Predicate "*-left-element-*"))
    (Lambda
      (Variable "$matrix-entry") ; Represents the EvaluationLink
      (ElementOf $matrix-entry 1))) ; Accesses the first element in the List
```

--------------------------------

### Entropy and Mutual Information Computation

Source: https://github.com/opencog/matrix/blob/master/README.md

The `add-entropy-compute` class provides methods for calculating entropy and mutual information. It supports computing column entropy (left-entropy), fractional entropy, mutual information, total entropy, and left/right entropies based on probability distributions.

```APIDOC
add-entropy-compute:
  Description: Computes entropy and mutual information of rows and columns.
  Methods:
    h_left(y):
      Computes the column entropy (left-entropy) for a given column y.
      Formula: -sum_x P(x,y) log_2 P(x,y)
    fractional_entropy_left(y):
      Computes the fractional entropy for column y.
      Formula: h_left(y) / P(*,y)
    mi_left(y):
      Computes the mutual information for column y.
      Formula: sum_x P(x,y) log_2 MI(x,y)
      where MI(x,y) = +log_2 P(x,y) / (P(x,*) P(*,y))
    H_tot():
      Computes the total entropy of the matrix.
      Formula: sum_x sum_y P(x,y) log_2 P(x,y)
    H_left():
      Computes the left entropy of the matrix.
      Formula: sum_y P(*,y) log_2 P(*,y)
    H_right():
      Computes the right entropy of the matrix.
      Formula: sum_x P(x,*) log_2 P(x,*)
  Dependencies: Requires probability distributions P(x,y), P(x,*), P(*,y).
```

--------------------------------

### Left-Wildcard Representation

Source: https://github.com/opencog/matrix/blob/master/design/Design-similarity.md

Shows a representation using a 'left-wildcard' placeholder for the left element of a word-pair. This is an alternative to using a variable.

```Atomese
(Edge (Predicate "word-pair")
   (List (Any "left-wild") ITEM))
```

--------------------------------

### Atomese OO Method Definition

Source: https://github.com/opencog/matrix/blob/master/design/Design-object-atomese.md

Defines a method for an object class in Atomese, specifying the method name and its implementation using a LambdaLink. This structure allows for generic programming patterns within Atomese.

```APIDOC
APIDOC:
  Object-Oriented Atomese Method Definition

  Syntax:
  (DefineLink
    (DefinedMethodLink
      (PredicateNode "<classname>")
      (PredicateNode "<methodname>"))
    (LambdaLink
      (VariableList ...)
      ... atomese ...))

  Description:
  This structure defines a method associated with a specific class in Atomese. The `DefinedMethodLink` links the class name and method name, while the `LambdaLink` contains the method's logic.

  Parameters:
  - `<classname>`: The name of the object class.
  - `<methodname>`: The name of the method being defined.
  - `VariableList`: A list of variables representing method parameters.
  - `atomese`: The Atomese code implementing the method.

  Note: A `ListLink` can also be used instead of `DefinedMethodLink` for basic functionality.
```

--------------------------------

### CMake: Add Subdirectory

Source: https://github.com/opencog/matrix/blob/master/opencog/CMakeLists.txt

Adds a subdirectory to the build. This directive tells CMake to process the build instructions within the specified subdirectory, typically containing its own CMakeLists.txt file.

```cmake
ADD_SUBDIRECTORY (matrix)
```

--------------------------------

### Query Caching Mechanism

Source: https://github.com/opencog/matrix/blob/master/design/Design-similarity.md

Explains how query results are cached using the query itself as the key. The `cog-value` function is used to retrieve these cached results.

```Atomese
(cog-value q q)
```

--------------------------------

### Conditional Subdirectory for Matrix Tests

Source: https://github.com/opencog/matrix/blob/master/tests/CMakeLists.txt

Conditionally adds the 'matrix' subdirectory to the build if the CxxTest framework is found. This ensures tests are only compiled when the testing environment is available.

```cmake
IF (CXXTEST_FOUND)

	ADD_SUBDIRECTORY (matrix)

ENDIF (CXXTEST_FOUND)
```

--------------------------------

### Set Minimum CMake Version

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Specifies the minimum version of CMake required to build the project. This ensures compatibility with CMake features used in the script and prevents execution with older CMake versions.

```cmake
CMAKE_MINIMUM_REQUIRED(VERSION 3.0.2)
```

--------------------------------

### Matrix with Rewrites for Marginals

Source: https://github.com/opencog/matrix/blob/master/design/Design-similarity.md

Defines a matrix structure that includes rewrites to explicitly specify marginals, such as the diagonal and left/right marginals, for a word-pair relationship.

```Atomese
(Query
      (VariableList
         (TypedVariable (Variable "$left") (Type 'Word))
         (TypedVariable (Variable "$right") (Type 'Word)))
      (Present
         (Edge (Predicate "word-pair")
            (List (Variable "$left") (Variable "$right"))))
      (Edge (Predicate "word-pair")
         (List (Variable "$left") (Variable "$right")))
      (Edge (Predicate "word-pair")
         (List (Any "left-wild") (Variable "$right")))
      (Edge (Predicate "word-pair")
         (List (Variable "$left") (Any "right-wild"))))
```

--------------------------------

### Direct Sum Matrix Combination

Source: https://github.com/opencog/matrix/blob/master/README.md

The `direct-sum` class facilitates combining two matrices into a single matrix. It handles concatenation of rows or columns, creating an object that behaves like a single matrix with a union of basis elements.

```APIDOC
direct-sum:
  Description: Combines two matrices by concatenating their rows or columns.
  Functionality:
    Creates a single matrix object from two component matrices.
    The left and right basis elements are the set-union of the component bases.
    Matrices can be placed side-by-side (concatenating rows) or above-below (concatenating columns).
    Assumes distinct types for either rows or columns to ensure unambiguous union.
    The total number of non-zero entries is the sum of entries in component matrices.
  Note:
    This differs from the conventional definition of direct sum which results in a block-diagonal matrix.
    This implementation uses set-union of basis elements, prioritizing explicit labels.
```

--------------------------------

### Define Project Name

Source: https://github.com/opencog/matrix/blob/master/CMakeLists.txt

Declares the project name for CMake. This name is used internally by CMake for various purposes, such as generating build targets and internal variables.

```cmake
PROJECT(matrix)
```