Component Guide 3: Plug-ins

From Nova Documentation
Jump to: navigation, search

Overview

In Nova plug-ins are used to extend the basic component platform with special functionality. In order for plug-ins to function properly we must distinguish 3 different types:

  • display: Some plugins, such as Raster and AgentViewerX, are used for visualization; they will want a post-update strobe to receive the latest data.
  • stateful: A second group have state values that are used to compute the values of Stocks. They need to be updated before any processing of Stocks during the cycle. An example of the latter is the Perceptron plug-in, which models a multiple layer neural network.
  • converter: A third class use the current state to produce the next, like Terms and Flows. These need to be strobed pre-update.

Plug-in type is determined by the plug-in designer and cannot be changed.

Adding a plug-in to your model

Plug-ins appear on the Plug-in Pallet, which has the same form as the Component Pallet. To add a plug-in follow the procedure for adding components to your model.

A plug-in instance in a model work like Graph and Table displays. The Model Canvas contains the plug-in's stub, which includes input and output pins for connecting the plug-in to the rest of the model. On the dashboard the plug-in's face displays any visualization and/or control elements required for it to function. Plug-ins that have no such elements (e.g., Averager) still appear on the Dashboard as small tiles.

Communicating with Plug-ins
Right-clicking on the plug-in stub opens a Connector Dialog, like the ones used by Containers. See Connecting Container Pins for details.
Plug-in menus
Right-clicking on the plug-in's dashboard component generally opens a menu that contains selections for configuring the plug–in (in some cases no configuration is required, and so no such menu appears). The most common menu entry, Properties, opens a dialog in which a set of properties can be selected.

In some cases property or control settings may affect the configuration of input and output pins on the stub.

Standard Plugins

The following plug-ins are included with the Nova distribution. Images show both the plug-in face on the Dashboard and the stub on the Model Canvas. Documentation will soon be provided for all of these plug-ins.

  • AgentViewerX
  • Averager
  • Bar Graph Maker
  • Cascade
  • Form
  • GraphTerm
  • Histogram
  • IMinsky
  • NetAgentViewer
  • NetViewer
  • Perceptron
  • Raster
  • RasterPlot
  • Signal Generator
  • Spy
  • Tableau
  • Tabulator

AgentViewerX

Help plug avx.png

The AgentViewerX (AVX) plug-in is the standard component for viewing the dynamic behavior of an AgentVector or SimWorld. (While it can be used for CellMatrices, the Raster plug-in is preferred). The AVX displays 2 layers; the first, called the matrix layer, is equivalent to the Raster plug-in, showing a cartesian array or hexagonal array (depending on the mode of the input Container) of tiles with each tile corresponding to a cell of the SimWorld's internal CellMatrix, using its row-column mapping. Tile colors correspond to some state parameter of the represented cell's submodel.

The second, agent layer, displays the agents of the SimWorld's internal AgentVector as individual tokens, mapping each agent's current location to the equivalent location in the tile array. The origin of the mapping is in the upper left corner, with positive values extending rightward and downward. Each tile represents a unit distance in horizontal and vertical distance. Values outside the represented space are disregarded unless the SimWorld is operating as a torus, in which case they wrap accordingly. Each agent can display a state value as a color or be randomly colored. An agent can also display a state value through the size of the token.

The user may specify up to 8 colors and corresponding values for coloring cells and agent tokens. Linear interpolation on the color's RGB components is used to determine colors for a value between 2 selectioned colors.

When operating in Interactive Mode the tile and token colors can be set using mouse gestures. These selections can be used to initialize the states of the corresponding cells and agents in advance of a simulation run. Selections are recorded and redisplayed each time the simulation is reset.

Plug-in Menu: Properties
Help plug avx prop.png


I. General
  • Rows, Cols: number of rows and columns in the matrix layer. On reset this will automatically be set to the number of rows of the CellMatrix/AgentVector/SimWorld.
  • Row Height, Column Width: number of pixels used to represent the height and width of the cell. Determines the plug-in's size on the dashboard.
  • Vary Agent Size: if checked, the agent token will vary in size based on the input to the AgentSizeIn pin.
  • Small/Large Agent Value: used to provide a scale for determining how values are mapped to actual agent token size.
  • Initial Cell Value: determines the corresponding default tile color.
  • Background Image: if a file containing an image is entered, this image is used as a background image and tile coloring is disabled. Only useful when displaying an AgentVector.
  • Agent Image: if a file containing an image is entered, this image is used as the token. When used, token coloring is disabled.
  • Agent Icon: A list of supported token types. Supports both agent color and size representation.
  • Interactive: Enables Interactive Mode.
II. Agent
  • Agent Colors Random/Assigned: Random coloring can be used with varying size, if so desired. If Random is selected, the rest of this section becomes disabled.
  • Number: set to the number of agent token colors to be used.
  • Color List: Up to 8 colors can be assigned (all slots beyond the current value of Number are disabled.) Each slot can be assigned a color and a value. (Click on the color to display the Color Chooser dialog.)
  • Reset: Click to reset colors to a standard sequence (Green, Red, Black, Cyan, Magenta, Blue, Yellow, White).
III. Cell
  • Number: set to the number of cell tile colors to be used.
  • Low/High: Set the range of values to be represented by these colors. Values will interpolate linearly across the set of selected colors.
  • Color List: Each slot can be assigned a color analogously to the Agents section.Value points are linearly deterimimed using Low and High.
  • Reset: Click to reset colors to a standard sequence (Green, Red, Black, Cyan, Magenta, Blue, Yellow, White).
  • Plug-in menu: Reset

In Interactive Mode, removes all agent and cell selections made through mouse gestures.

Input Pins

  • AgentColorIn: Connects to the AgentVector/SimWorld pin of the agent output to be displayed as token color.
  • CellColorIn: Connects to the CellMatrix/SimWorld pin of the cell output to be displayed as tile color.
  • AgentSizeIn: Connects to the AgentVector/SimWorld pin of the agent output to be displayed as token size.
  • AgentDataIn: Connects to the AgentVector/SimWorld AData pin, conveying agent position and life cycle data.

Output Pins

  • AgentColorOut: During Interactive Mode, connects to the AgentVector/SimWorld pin of the agent input to be displayed as token color.
  • CellColorOut: During Interactive Mode, connects to the CellMatrix/SimWorld pin of the cell input to be displayed as tile color.
  • AgentSizeOut: During Interactive Mode, connects to the AgentVector/SimWorld pin of the agent input to be displayed as token size.
  • AgentDataOut: During Interactive Mode, connects to the AgentVector/SimWorld Init_Count pin, conveying initial agent position data.
Interactive Mode
  • To change a tile's color left-click on that tile; successive left-clicks will cause the colors to rotate through the Cell Colors pallet defined in Properties. Alternatively, pressing the mouse on a tile and dragging across the matrix will cause the colors of dragged-over tiles to change to the color of the original tile.
  • Note: Interactive Mode requires assigned agent colors. To create an agent token on a cell shift-left-click on that cell. The token will appear in the first color of the Agent Colors pallet defined in Properties. Successive shift-right-clicks will rotate the color through the pallet. A shift-right-click on the last color will delete the agent.

Averager

Help plug averager.png

When connected to an output pin of an aggregator, the Averager plug-in computes and outputs the running average of the pin's value over the elements of the aggregator.
Properties

  • No user-settable properties.

Input Pin

  • The single input pin In must be connected to an aggregator pin.

Output Pin

  • The output pin Out is the running average of the input over the elements of the aggregator.

Bar Graph Maker

Help plug bar.png

The Bar Graph Maker inputs a single model value x over a time sequence and converts it to n outputs, each representing the average of that sequence during m timesteps. Those outputs are expected to be connected to a Graph component and displayed as a bar graph. For example, if n = 6 and m = 5, then x 's value over the first 30 time intervals will be condensed into 6 output values. The first 5 x values will be averaged to produce the first output value; then the next 5 x values will be averaged to produce the second output value, etc.

Controls

  • Size and Width spinners on the plug-in determine, respectively, n (the number of outputs) and m (the number of time intervals averaged for each output).

Properties

  • No user-settable properties.

Input Pin

  • Single input pin In connected to some value-producing component.

Output Pin

  • The number of output pins Out_00 - Out_XX equals the value of Size.

Cascade

Cascade.png

The cascade plug-in computes and outputs values for each entry in count based on entries to the top count - In term - and a specified converting method - Converter term.

Controls

  • The number of entries, Count, in the cascade.

Properties

  • This Plug-in be made Normal or Compact. As of March 16, 2015 always use Compact (all below examples are with Compact).

Input Pins

  • First input pin Initial fills values in cascade for Time() = 0. Can take array of n length where n is the number of counts of the cascade.
  • Second input pin In term is added to count 0 (top entry of cascade). Single value.
  • Third input pin Converter provides method of converting values in cascade. Can take function (example below).

Output Pin

  • Output pin Out contains an array of length n where each element is the value of the corresponding element in the cascade. The length of array is equal to the length of the cascade (n).

Example

Click here for an example.

Graph Term

Gt-icon.png

Graph terms allow you to incorporate real-world data into your models. You can import data in CSV form, use that data to build a function, then use the function in models you build in Nova.

Properties

When you place a graph term on your model canvas, a line graph with a default set of values will show up in your output window. When you right-click on this graph, you will be taken to a menu with 4 different options.
New term just added to Dashboard

The first option, properties, takes you to a window where you can label the graph, determine the number of functions you want to plot, determine the max and min of those functions, and determine the number of data points you want to plot.

Term Properties

Selecting Import allows you to import a CSV file of data points. Once you’ve imported a CSV file, Nova will graph the data in it.

You can also plot data points manually. By clicking on points in the graph, you enter Edit mode where you can change data points in the graph simply by clicking on them, or by clicking on them in the list view on the right side of the graph, then modifying them.

Edit Mode

Once you’ve generated data from your model, you can right click on the graph, select “Export,” and export your data as a CSV file. This allows you to evaluate your data in statistical packages like R.

Minimized Graph

The final option that you get when you right-click on the graph “Minimize” allows you to minimize the graph into a neat little box, so you have more space in your output window.

You can easily get back to the full-size graph by right-clicking and selecting “Maximize.”

Pins

  • When you right-click on the graph term in the modeling canvas, you can change the inputs into the graph, incorporating stocks and terms from your model into the graphical output.


Histogram

Histboth.png

This plug-in inputs a sequence of values, and counts the number of values that fall into specified categories. The categories (called buckets) are a sequence of intervals of a fixed width around a center value. The plug-in’s face contains controls for specifying the number of intervals, the center point and the width of each interval. The value of each bucket (i.e. the number of elements in the input sequence that fall into the interval) is the output on the corresponding pin.

In the example shown at left the histogram creates 15 buckets of width 2 between 35 and 65. The resulting buckets are [35, 36.9999], [37, 38.9999], [39, 40.9999], [41, 42.9999], [43, 44.9999], [45, 46.9999], [47, 48.9999], [49, 50.9999], [51, 52.9999], [53, 54.9999], [55, 56.9999], [57, 58.9999], [59, 60.9999], [61, 62.9999], [63, 64.9999].
Properties

  • There are no other user-settable properties.

Input Pin

  • The single input pin (In) supplies the sequence of values measured by the histogram.

Output:

  • Each output pin (Bkt_n) corresponds to one bucket value. Running from top to bottom the pins represent the increasing sequence of bucket intervals.

Notes

The histogram is generally used to create a bar graph showing the bucket values.

NetViewer

Sample NetViewer.png

This plug-in allows the visualization of a network (i.e. mathematical graph) topology. Networks could either be from NodeNetwork or NetWorld components.
Plug-in Menu: Properties

NetViewer Properties from NetDiffuse in the Model Library
  • Cols: number of columns in viewer (which will determine the number of rows).
  • Row Height, Col Width: number of pixels used to represent the height and width of the nodes. Determines the plug-in's size on the Dashboard.
  • Vary Node Size?: nodes will vary in size based on their values if checked.
  • Node Colors: can vary each node's color based on their Id or their value.

Plug-in menu: Reset

  • In Interactive Mode, removes all node selections made through mouse gestures.

Input Pins

  • NodeColorIn and NodeSizeIn connects to the NodeNetwork/NetWorld pin of the output to be displayed as node color and size, respectively.

Output Pin

  • NodeColorOut can be connected to view the output color of the nodes within the NetViewer.


Example

Click here for an example of using the NetViewer Plug-in along with NetDiffuse in the Model Library.

Raster

Help plug raster.png

The Raster plug-in is the standard component for viewing the dynamic behavior of a CellMatrix. It displays a cartesian or hexagonal array (depending on the mode of the CellMatrix) of tiles with each tile corresponding to a cell of the CellMatrix, using its row-column mapping. Tile colors correspond to some state parameter of the represented cell's submodel.

The user may specify up to 8 colors and corresponding values for coloring cells Linear interpolation on the color's RGB components is used to determine colors for a value between 2 selectioned colors.

When operating in Interactive Mode the tile colors can be set using mouse gestures. These selections can be used to initialize the states of the corresponding cells in advance of a simulation run. Selections are recorded and redisplayed each time the simulation is reset.

Plug-in Menu: Properties

Help plug raster prop.png
  • Rows, Cols: number of rows and columns in the matrix layer. On reset this will automatically be set to the number of rows of the CellMatrix.
  • Row Height, Column Width: number of pixels used to represent the height and width of the cell. Determines the plug-in's size on the dashboard.
  • Interactive: Enables Interactive Mode.
  • Show Values: Displays cell values inside cells when enabled.
  • Number: set to the number of cell tile colors to be used.
  • Low/High: Set the range of values to be represented by these colors. Values will interpolate linearly across the set of selected colors.
  • Color List: Each slot can be assigned a color analogously to the Agents section.Value points are linearly deterimimed using Low and High.
  • Reset: Click to reset colors to a standard sequence (Green, Red, Black, Cyan, Magenta, Blue, Yellow, White).

Plug-in menu: Reset

  • In Interactive Mode, removes all agent and cell selections made through mouse gestures.

Input Pin

  • In connects to the CellMatrix pin of the cell output to be displayed as tile color.

Output Pin

  • During Interactive Mode, Out connects to the CellMatrix/SimWorld pin of the cell input to be displayed as tile color.

Interactive Mode

To change a tile's color left-click on that tile; successive left-clicks will cause the colors to rotate through the Cell Colors pallet defined in Properties. Alternatively, pressing the mouse on a tile and dragging across the matrix will cause the colors of dragged-over tiles to change to the color of the original tile.

RasterPlot

Help plug rasterplot.png

The RasterPlot plug-in is analogous to the Raster for viewing the dynamic behavior of an AgentVector. At each time step it displays a single row or column (depending on the choice of scan direction) with each tile corresponding to an agent based on the agent's id (e.g. agent 0 appears on the left of a row or the top of a column). As with the Raster, tile colors correspond to some state parameter of the represented agent's submodel. As time progresses, the display row (column) moves from top to bottom (left to right) and wraps around; consequently a history of agent values is maintained for length represented by the opposite dimension.

Note: The RasterPlot should only be used in a model with a fixed agent population (i.e. no births or deaths).

The user may specify up to 8 colors and corresponding values for coloring cells Linear interpolation on the color's RGB components is used to determine colors for a value between 2 selectioned colors.

When operating in Interactive Mode the tile colors can be set using mouse gestures. These selections can be used to initialize the states of the corresponding cells in advance of a simulation run. Selections are recorded and redisplayed each time the simulation is reset.

Plug-in Menu: Properties

Help plug rasterplot prop.png
  • Rows, Cols: number of rows and columns in the matrix layer. On reset this will automatically be set to the number of rows of the CellMatrix.
  • Row Height, Column Width: number of pixels used to represent the height and width of the cell. Determines the plug-in's size on the dashboard.
  • Scan Direction: Selects either a left to right or top to bottom scan.
  • Interactive: Enables Interactive Mode.
  • Show Values: Displays cell values inside cells when enabled.
  • Number: set to the number of cell tile colors to be used.
  • Low/High: Set the range of values to be represented by these colors. Values will interpolate linearly across the set of selected colors.
  • Color List: Each slot can be assigned a color analogously to the Agents section.Value points are linearly deterimimed using Low and High.
  • Reset: Click to reset colors to a standard sequence (Green, Red, Black, Cyan, Magenta, Blue, Yellow, White).

Plug-in menu: Reset

  • In Interactive Mode, removes all agent and cell selections made through mouse gestures.

Input Pin

  • In connects to the CellMatrix pin of the cell output to be displayed as tile color.

Output Pin

  • During Interactive Mode, Out connects to the CellMatrix/SimWorld pin of the cell input to be displayed as tile color.

Interactive Mode

To change a tile's color left-click on that tile; successive left-clicks will cause the colors to rotate through the Cell Colors pallet defined in Properties. Alternatively, pressing the mouse on a tile and dragging across the matrix will cause the colors of dragged-over tiles to change to the color of the original tile.

Signal Generator

Siggen.png

The Signal Generator plug-in outputs a value that is specified by its control.

Properties

  • Low/High: determines range of spinner; Decimal places: determines precision of spinner.

Output Pin

  • value shown in the control.

Spy

Spy.png

The Spy plug-in displays its input as a numerical value.

Properties

  • No user-settable properties.

Input Pin

  • The single input pin (In) provides the value displayed. This must be a number.

Output Pin

  • The output pin (Out) duplicates the input for convenience (i.e. when the Spy is placed inline between 2 components).

Example

Click here for an example of using the Spy plug-in with the Cascade plug-in.

Tableau

Tableau.png

The Tableau plug-in allows 2 dimensional array (or matrix) input.

Tableau properties.png

Properties

  • User can set number of Rows, Columns, Row Height, and Column Width.

Output Pin

  • The single output pin (m) stores the array structure.

Example

An example of user input into the Tableau plug-in. This example has a single row with 4 columns. The output, m, has the following indexes and values:
Tableau real example.png
Matrix values:
m(0,0) = 10
m(0,1) = 20
m(0,2) = 30
m(0,3) = 40


Click here for an example of using the Tableau plug-in.