Docs
`/`

# API elements

No matching results

# Sections and content

No matching results

- `Enter` to go to the highlighted result.
- `↑` and `↓` to change highlight.
- `Tab` to switch between result lists.
- `Esc` to hide the results.

# 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:

- label list, enabled in Lingo4G by default.

- document embeddings, which need to be enabled by setting the `documents.embedding.enabled` Lingo4G request parameter to `true`.

- document clusters, which need to be enabled by setting the `documents.arrangement.enabled` Lingo4G request parameter to `true`.

###
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.

previous article
Lingo4G plugin API
next article
Releases