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.
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.
Accessing Projection Data in the Component Script
Now that you know how to add projections with the component editor and how to access them in the dataflow, you need to learn how to make use of projections in component scripts. Accessing projection data is a simple process, but it is a bit different for each language domain.
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.