Exaptive's Cognitive City Learning Center

Projections allow a Xap builder to specify how their data will get mapped onto the channels of a visualization or algorithm in their Xap. This article aims to teach you how to create projection ports for your Component, so that a Xap builder can take advantage of that functionality. 

For more on what Projections are and how they work in Xaps, check out Projections, the Concept.

---

Creating a Projection Port

To create a projection data input in a component, go to the Component Editor. Check the "Projection" check box in the input editor. 

After checking the "Projection" box, you'll see a new row label, "Projection" and the option to "ADD TARGET." A target is the element of the component to which you want to enable the xap builder to project their data. Suppose you're creating a scatter plot component. The target might be the points in the plot.

You then want to define the channels of that target, like x-axis position.

You could then go ahead and define other channels of the points, like y-axis position, size, color, and label.  

NOTE: It's best in the current version to name targets and inputs without spaces or hyphens. Otherwise the layout of the input names will be messed up when you use the component in the dataflow.

So, as you create this targets and channels, what's going on under the hood here looks like this, an entity with attributes, value types, and a default value: 

 

{
"projection": {
        "points": [
          {
            "name": "x",
            "valueType": "string"
          },
          {
            "name": "y",
            "valueType": "string"
          },
          {
            "name": "size",
            "valueType": "float"
          },
          {
            "name": "color",
            "valueType": "string"
          },
          {
            "name": "label",
            "valueType": "string"
          },
          {
            "name": "borderColor",
            "valueType": "string"
          }
        ]
      }
}

  

If you require more than one data target in your projection, you can add them by clicking "ADD TARGET" again. A new prototype target will appear with a name and channel.

Now, when the component is added to a xap, all top-level inputs will be visible for collapsed components. To view the projection inputs, double click on the component to expand it. Then, select the projection input to expand it and select a desired target to view the channel inputs.

The examples below illustrate how a user can access projection using any of Exaptive's language domains. Each example references a projection input named 'data' with a 'nodes' target and an 'x' channel. The output for each code snippet will be a duffle of entities. Every entity will contain a projected Id and the projection channels that you have defined.

Javascript

let state = this.api.inputState.export();
let target = state.data.nodes;

this.api.output('data', target)

Python

data = self.api.inputstate.export()['data']
target = data['nodes'];

self.api.output('data', target)

R

state <- v_export(self$api$inputstate)
nodes <- state$data$nodes

self$api$output(name = "data", value = v_multiset(nodes))

Creating and Using Projected Ports

Projected ports, as opposed to projection ports, allow users to work with data coming from a projection port. For example, consider that you have created a scatter plot with a duffle of entities. You have set the projection input so that channels map properties on each entity to attributes of the scatter plot (x, y, size, etc.). A projected input on the scatter plot would accept data in the same format as the primary projection input and with the added benefit of mapping objects to the same unique projected id used for the primary projection input. Projected outputs work in the opposite manner by allowing the user to transform the output format using a projection. 

You can learn about creating projected ports and how to use projected ports in a xap.