lingo4g:result

The result JSON returned by the Lingo4G analysis API v2.

For the plugin to work, the response must contain results of the following analysis stages:

By default, the plugin expects the stages to be named as listed in the Stage name column of the table. You can customize the stage names using the lingo4g:result:stageName:* properties of this plugin.

The following figure shows an example Lingo4G analysis request JSON that generates all the data required for the plugin to display a 2d map of documents. See Lingo4G documentation for more information about building Lingo4G analysis request JSONs.

{
  "name": "Document 2d embedding with labels and clusters by embedding similarity",
  "comment": "Puts documents on a 2d map based on the multidimensional document embedding similarity. Additionally, computes 2d coordinates of labels to describe specific areas of the map and clusters documents based on their 2d embedding distance.",
  "variables": {
    "query": {
      "name": "Query",
      "comment": "Selects documents to arrange into a 2d map.",
      "value": "clustering"
    },
    "maxDocuments": {
      "name": "Max documents",
      "comment": "Maximum number of documents to include in the 2d map.",
      "value": 5000
    },
    "maxLabels": {
      "name": "Max labels",
      "comment": "Maximum number of labels to put on the 2d map.",
      "value": 500
    }
  },
  "stages": {
    "documents": {
      "type": "documents:byQuery",
      "query": {
        "type": "query:string",
        "query": {
          "@var": "query"
        }
      },
      "limit": {
        "@var": "maxDocuments"
      }
    },
    "labels": {
      "type": "labels:fromDocuments",
      "maxLabels": {
        "type": "labelCount:fixed",
        "value": {
          "@var": "maxLabels"
        }
      }
    },
    "documentEmbeddings2d": {
      "type": "embedding2d:lv",
      "matrix": {
        "type": "matrix:knnVectorsSimilarity",
        "vectors": {
          "type": "vectors:precomputedDocumentEmbeddings"
        }
      }
    },
    "labelEmbeddings2d": {
      "type": "embedding2d:lvOverlay",
      "matrix": {
        "type": "matrix:keywordLabelDocumentSimilarity",
        "labels": {
          "type": "labels:reference",
          "use": "labels"
        }
      },
      "embedding2d": {
        "type": "embedding2d:reference",
        "use": "documentEmbeddings2d"
      }
    },
    "documentClusters": {
      "type": "clusters:ap",
      "matrix": {
        "type": "matrix:knn2dDistanceSimilarity",
        "embedding2d": {
          "type": "embedding2d:reference",
          "use": "documentEmbeddings2d"
        },
        "maxNearestPoints": 96
      },
      "softening": 0.2,
      "inputPreference": -10000
    },
    "documentClusterLabels": {
      "type": "labelClusters:documentClusterLabels"
    }
  },
  "output": {
    "stages": [
      "documents",
      "documentEmbeddings2d",
      "documentClusters",
      "documentClusterLabels",
      "labels",
      "labelEmbeddings2d"
    ]
  },
  "tags": [
    "2D Embeddings"
  ]
}

lingo4g:result:stageName:labels

Name of the stage that provides the labels to display, labels by default.

lingo4g:result:stageName:labelEmbeddings2d

Name of the stage that provides the 2d embeddings of the labels, labelEmbeddings2d by default.

lingo4g:result:stageName:documentEmbeddings2d

Name of the stage that provides the 2d embeddings of the documents to display, documentEmbeddings2d by default.

lingo4g:result:stageName:documentClusters

Name of the stage that provides the clusters of documents to display, documentClusters by default.

lingo4g:result:stageName:documentClusterLabels

Name of the stage that provides the labels of the document clusters, documentClusterLabels by default.

lingo4g:baseMarkerSize

A base value used to compute the size of document markers, 5.0 by default.

The size of markers created by this plugin is proportional to lingo4g:baseMarkerSize. To make the markers smaller or larger, decrease or increase this property.

lingo4g:customize:layers

A function called before the layers created by this plugin are displayed in dotAtlas. You can use this callback to customize the properties or data points of the automatically created layers.

The provided value must be a function with the following signature:

const customizeLayers = function (layersMap, context) { };

The function will be called with the following parameters:

layersMap

A map of layers ready to be displayed.

The map will contain the following keys: elevations, markers, labels. Under each key there is the layer object representing the specific layer. Use the Elevation layer API, Marker layer API and Labels layer API, respectively, to tune the layers as required.

result

The lingo4g:result for which the layers were created.

Below is an example customization function that displays the labels in italic, derives marker color from point elevation and "sharpens" elevations.

import { DotAtlas, Lingo4GDocumentMap } from "@carrotsearch/dotatlas";


const dotAtlas = DotAtlas.with(Lingo4GDocumentMap).embed({
  "element": document.querySelector("#visualization"),
  "lingo4g:result": { /* Lingo4G result here */ },
  "lingo4g:customize:layers": ({ markers, elevations, labels }, result) => {
    labels.set("labelFontStyle", "italic");
    elevations.get("points").forEach(p => p.elevation = Math.pow(p.elevation, 2))
    markers.get("points").forEach(p => {
      p.color = `rgb(${(255 * p.elevation).toFixed(0)}, 0, 0)`;
    });
  }
});