/

Lingo4G v1 plugin API

This reference describes the API of the Lingo4G v1 plugin.

The Lingo4G plugin makes it easy to display 2d embeddings produced by Lingo4G. The Lingo4GDocumentMapV1 plugin creates the layers required to display a 2d document embedding produced by Lingo4G. 

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

// Fetch results from Lingo4G (pseudo code below)
const lingo4GApiUrl = "https://yourserver.com/lingo4g/api/v1";
const result = await fetch(lingo4GApiUrl + "/spec={}&async=false");

const dotAtlas = DotAtlas.with(Lingo4GDocumentMap).embed({
  "element": document.querySelector("#visualization"),
  "lingo4g:result": result
});

When you provide a new lingo4g:result, the Lingo4GDocumentMapV1 plugin creates three layers:

elevation layer

The plugin derives point coordinates on the elevations layer from the 2d document coordinates returned by Lingo4G.

The plugin derives elevation values from the document's similarity to the cluster exemplar, which should highlight the "importance" of each document and create a naturally-looking map.

markers layer

Point coordinates on the markers layer represent the 2d document coordinates returned by Lingo4G, marker size depends on the similarity to the cluster exemplar. Marker color represents the cluster the document belongs to.

The plugin uses a heuristic to compute a marker size scaling factor that makes the visualization legible regardless of the number of documents being visualized. You can use the lingo4g:baseMarkerSize property to fine-tune the size of markers produced by this plugin.

labels layer

Coordinates and text of labels will represent the label part of the embedding produced by Lingo4G.

See the lingo4g:result documentation for a list of Lingo4G JSON response elements required to build the layers. To customize the layers created by this plugin, use the lingo4g:customize:layers callback.

Note that ti get a naturally-looking map, you usually need an embedding with at least a few thousands of documents.

Properties

lingo4g:result

The result JSON obtained from Lingo4G API.

For the plugin to work, the response must contain the following parts:

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)`;
    });
  }
});

lingo4g:layer:elevations

The elevations layer object created by this plugin.

You can use this property to change the visual properties of the layer, register event listeners or call layer-specific methods. 

const elevations = dotAtlas.get("lingo4g:layer:elevations");
elevations.set("lightAzimuth", Math.PI);

lingo4g:layer:markers

The markers layer object created by this plugin. Use this property to get and set properties of the markers layer.

lingo4g:layer:labels

The labels layer object created by this plugin. Use this property to get and set properties of the labels layer.