Metrics Syntax Reference

We recommend using hCore's fully featured wizards to define metrics and generate plots. If you would like to define them manually for any reason, you can reference the below for an explanation of the structure and syntax of the analysis.json file.

The analysis.json file contains two items within it: an "outputs" object and a "plots" list.

Metrics

Metrics are defined as an object collection of JSON objects of the form:

"outputs": {
    "metric_1": [
        {
            operation
        },
        {
            operation
        }
        ...
    ],
    "metric_2": [
    ...
    ]
}

The “metric” is referenced by plot definitions, and will correspond to an array of data (or array of arrays). The "operations" are objects corresponding to those described in the Analysis page, with all of the same fields that are described there. Chaining operations works identically to the wizard.

Operations must have an "op" field which designates their type. Some operations have additional arguments. The valid types and additional arguments are listed below:

Operator Name	Additional Arguments	Operator Description
"filter"	"field""comparison" "value"	Filter the current output with the given comparison and value on the given field of each element
"count"	n/a	Count the number of agents in the current output
"get"	"field"	Retrieve the field value from each agent in the current output
"sum"	n/a	Sum over the elements of the current output
"min"	n/a	Return the minimum of the elements in the current output
"max"	n/a	Return the maximum of the elements in the current output
"mean"	n/a	Return the mean of the elements in the current output

For example, if you have a collection of agents with an age attribute, you might want to count the number over age 50. You would chain together operations like so:

"outputs": {
   "over_fifty": [
   {
       "op": "filter",
       "field": "age",
       "comparison": "gte",
       "value": "50"
     },
     { "op": "count"}
   ],
   ...
}

Plots

The "plots" list contains objects which define the different plots that visualize the outputs. The basic configuration of a plot includes a title, data, type, layout, and position field:

  "plots": [{
     "title": "title",
     "layout": {
       "width": "100%", // % of analysis view width
       "height": "50%" // % of analysis view height
     },
     "position": {
     //top left corner of plot
       "x": "0%",
       "y": "0%"
     },
     //type of chart
     "type": "timeseries", // "histogram", "barplot", etc...
     "data": [
       {
         "y": "component_1",
         "name": "component_1_name"
         // ...
       },
       {
         "y": "component_2_name",
         "name": "component_2_name"
         //...
       {
     ]
   },
   //...
   ]

By default the x-axis represents the step of the simulation. You can use line, bar, or area charts, among others.

As a shortcut you may replace the "data" and "type" field with a "timeseries" array. Any outputs you place in the array will be plotted as lines.

"plots": [{
     "title": "title",
     "layout": { "width": "100%", "height": "50%" },
     "position": { "x": "0%", "y": "0%" },
     // Timeseries shortcut
     "timeseries": ["timeseries1", "timeseries2"]
}]

HASH uses Plotly behind the scenes to render charts and graphs. As such, the platform supports any valid value it supports for layout, type, and data as documented in their API.

Examples

Below are a few snippets of outputs and plots.

Model Market

Link to Simulation

{
   "outputs":{
      "recent_sales":[
         {
            "op":"filter",
            "field":"color",
            "comparison":"eq",
            "value":"green"
         },
         {
            "op":"count"
         }
      ],
      "no_recent_sales":[
         {
            "op":"filter",
            "field":"color",
            "comparison":"eq",
            "value":"skyblue"
         },
         {
            "op":"count"
         }
      ]
   },
   "plots":[
      {
         "title":"Shop Status",
         "timeseries":[
            "no_recent_sales",
            "recent_sales",
            "closed"
         ],
         "layout":{
            "width":"100%",
            "height":"40%"
         },
         "position":{
            "x":"0%",
            "y":"0%"
         }
      }
   ]
}

Civil Unrest

{
  "outputs": {
    "active": [
      {
        "op": "filter",
        "field": "active",
        "comparison": "eq",
        "value": true
      },
      { "op": "count" }
    ],
    "arrested": [
      {
        "op": "filter",
        "field": "jail_time",
        "comparison": "gt",
        "value": 0
      },
      { "op": "count" }
    ]
  },
  "plots": [
    {
      "title": "Active agents",
      "timeseries": ["active"],
      "layout": { "width": "100%", "height": "33%"},
      "position": { "x": "0%", "y": "0%"}
    },
    {
      "title": "Arrested agents",
      "timeseries": ["arrested"],
      "layout": { "width": "100%", "height": "33%"},
      "position": { "x": "0%", "y": "68%"}
    },
    {
      "title": "Active Agents Histogram",
      "layout": { "width": "100%", "height": "33%" },
      "position": { "x": "0%", "y": "34%" },
      "type": "histogram",
      "data": [
        {
          "x": "active"
        }
      ]
    }
  ]
}