Style `graph`

The style graph is wrapper for the library Plotly.js which allows to use collected data from SelfHelp to render graphs. For simple bar or pie graphs it is recommend to use the styles graphBar or graphPie, respectively, as they are much easier to configure. For Sankey diagrams it is recommended to use the style graphSankey as it is much easier to set up and offers options which are not achievable with the base graph style.

The style fields config and layout expect a JSON object which corresponds to the configuration object and the layout object passed to the graph library, respectively.

The style field traces expects a JSON list of trace objects. This corresponds to the data array which is passed to the graph library. However, in order to link SelfHelp data to graphs, each trace object is extended with a special key data_source (Refer to the cards below for more information and examples). All other keys are dependent on the type of figure to be drawn and can be referred to in the Plotly.js documentation.

The style field data_config expects a JSON list. In the JSON, we can define how we would like to extract some data from DB and load into the traces. JSON Structure:

 [
    {
        "type": "static|dynamic",
        "table": "table_name | #url_param1",
        "retrieve": "first | last | all",
        "fields": [
            {
                "field_name": "name | #url_param2",
                "field_holder": "@field_1",
                "not_found_text": "my field was not found"              
            }
        ]
    }
]

Example:

 [
    {
        "type": "static",
        "table": "my_table",
        "retrieve": "first",
        "fields": [
            {
                "field_name": "my_field",
                "field_holder": "@field_holder",
                "not_found_text": "my field was not found"              
            }
        ]
    }
]

It means that the code will search the first row in table my_table and it will get the value of field my_field. Then the value will be assigned and if keyword @field_holder is used in traces, it will be replaced with the found value. If no value was found it will return the predefined string not_found_text.

The data to be used to render the graphs can be of either of the two following types.

dynamic: The data is collected through the selfhelp style formUserInput or mermaidForm. A data collection corresponds to all data points collected through one specific form. A data set corresopnds to all data points collected through a specific input field of a form.
static: The data was collected through other means than SelfHelp and was uploaded to the SelfHelp platform as a CSV file. A data collection corresponds to all data points within a CSV file. A data set corresponds to one column of a CSV file.

Unknown Style styleSignature

Trace Data Sources

The key data_source of a trace object expects a JSON object with the following keys:

name: the name of the data collection.
map: the association of the data points to plotly trace keys. Each key is a dot-separated string which will produce an element inside the trace object accordingly. For example, the string marker.color will extend the trace object with the key marker. This key will hold an object with the key color which will hold a list of data items to be used to color the markers of the trace. The values of the map object can be of the following types:
- string: indicating the data column to be used as values.
- array: an array of operand objects which allow to perform simple operations on data columns and use the results as values.
- object: an object defining how to group values of one data column and how to assign properties to each group.

String Trace Association

This example uses a static data collection (sample_static) with a string trace association to render a scatter plot. Here, two traces are rendered where for each trace all data points from one data set (trace1 and trace2, respectively) are used and assigned to the trace key y.

[{
  "name": "Trace 1",
  "data_source": {
    "name": "sample_static",
    "map": {
      "y": "trace1"
    }
  }
}, {
  "name": "Trace 2",
  "data_source": {
    "name": "sample_static",
    "map": {
      "y": "trace2"
    }
  }
}]

The above JSON list will produce the following list of trace objects to be passed to the graph library:

[{
  "name": "Trace 1",
  "y": [all data from data set `trace1`]
}, {
  "name": "Trace 2",
  "y": [all data from data set `trace2`]
}]

Note that the keys name and y of the trace objects correspond to the plotly trace attributes of a scatter plot.

Unknown Style graph

Array Trace Association

When performing an array association the list must hold operand objects. Each operand object specifies a data set and a mathematical operation which will be performed on all values of the data set. An operand object must have the following keys:

name<string>: the name of the data set
op<string>: one of the following mathematical operations:
- max: returns the maximal value of the data column.
- min: returns the minimal value of the data column.
- sum: returns the sum of all values of the data column.
- avg: returns the average of all values of the data column.

The following example uses a static data collection (sample_static) with an array trace association to render a bar plot. Here, the trace is rendered by applying a mathematical operation on all data points of each data set (trace1, trace2, and trace3, respectively).

[{
  "data_source": {
    "name": "sample_static",
    "map": {
      "y": [
        {"name": "trace1", "op": "max"},
        {"name": "trace2", "op": "avg"},
        {"name": "trace3", "op": "min"}
      ]
    }
  },
  "x": ["max(Trace 1)", "avg(Trace 2)", "min(Trace 3)"],
  "type": "bar"
}]

The above JSON list will produce the following list of trace objects to be passed to the graph library:

[{
  "x": ["max(Trace 1)", "avg(Trace 2)", "min(Trace 3)"],
  "y": [max(trace1), avg(trace2), min(trace3)],
  "type": "bar"
}]

Note that the keys x, y, type of the trace object correspond to the plotly trace attributes of a bar graph.

Unknown Style graph

Object Trace Association

This is the most complex but also the most flexible way to map data collections to a plotly graph. In contrast to the array association, the object association allows to act on separate groups of values within one data set instead of action on all values of the data set. This means that one data set can be reduced to multiple values by applying mathematical operations on groups of values instead of the complete set. The object supports the following keys:

name: Defines the name of the data set.
ignore: Defines a list of value types to ignore when computing the trace value.
options: Allows to define post-process operations on the data set. The following keys are available:
- op: Defines the operation to be used to produce grouping values. The following operations are available:
  - count: Count the occurences of each individual value.
  - idx: Increment per new value type.
  - percent: Count the occurences of each individual value and divide the result by the row count.
  - sum: Accumulate distinct values (i.e. count * value).
  - val: Use the value type.
- range: Allows to define a range to which the trace values will be evenly distributed. The range object must contain the keys min and max to define the minimum and maximum range value, respectively.
- factor: If defined, this number will be multiplied to each value computed with the function defined in op.
- offset: If defined, this number will be added to each value computed with the function defined in op (after multiplying by factor).
- round: Defines the number of digits after the comma to round to. 0 means rounding to an integer.
- suffix: Allows to add a suffix to each value.
order: This defines the trace order and can be of the following types:
- string: Either "asc" or "desc" to order the traces either by ascending values or by descending values, respectively
- array: An array of indices indication the new position of the trace points.
- object: An object with the key vals which holds an ordered list of value types by which the traces will be ordered.
map: This allows to map static data to predefined keys while respecting the post-process options defined above. The keys of the object are dot-seperated strings which will produce an element inside the trace object accordingly. The values are map objects which will map static data to a value type. To use this for labelling value types, the key would be the value type and the value the label to assign to the value type.
children. This allows to map furter data items from the data table to trace object keys while respecting the post-process options defined above. Children are defined by a value-key pair where the key is a dot-seperated string which will produce an element inside the trace object accordingly and the value is an option object as defined by the parameter options.

The following example uses most of the keys described above to produce a bubble chart.

[{
  "data_source": {
    "name": "sample_static",
    "map": {
      "x": {
        "name": "trace1",
        "order": "asc",
        "ignore": ["98", "99"],
        "options": {
          "op": "val"
        },
        "children": {
          "text": {
            "op": "percent",
            "factor": 100,
            "round": 0,
            "suffix": "%"
          },
          "marker.size": {
            "op": "percent",
            "range": { "min": 10, "max": 100 }
          },
          "y": {
            "op": "idx"
          }
        },
        "maps": {
          "hovertext": {
            "1": "Type 1",
            "2": "Type 2",
            "3": "Type 3",
            "4": "Type 4",
            "5": "Type 5",
            "6": "Type 6",
            "7": "Type 7",
            "8": "Type 8",
            "9": "Type 9",
            "10": "Type 10",
            "11": "Type 11",
            "98": "Type 98",
            "99": "Type 99"
          },
          "marker.color": {
            "1": "#EA8571",
            "2": "#DE7C89",
            "3": "#C27C9D",
            "4": "#9C80A7",
            "5": "#6F84A4",
            "6": "#478394",
            "7": "#31807A",
            "8": "#38795D",
            "9": "#496F42",
            "10": "#59632E",
            "11": "#665624",
            "98": "#6D4926",
            "99": "#6E3D2E"
          }
        }
      }
    }
  },
  "textposition": "middle center",
  "textfont": {
    "size": 20
  },
  "mode": "markers+text"
}]

The above JSON list will produce the following list of trace objects to be passed to the graph library:

[{
  "x": [all distinct value types of `trace1`],
  "y": [the index of each value type corresponding to `x`]
  "text": [the computed percentage of each value type in `trace1`,
    post-processed with `factor`, `round`, and `suffix`],
  "marker": {
    "size": [the computed percentage of each value type in `trace1`,
      post-processed with `range`],
    "color": [the colors to be mapped to the value types of x]
  },
  "hovertext": [the labels to be mapped to the value types of x],
  "textposition": "middle center",
  "textfont": {
    "size": 20
  },
  "mode": "markers+text"
}]

Note that the keys of the trace object correspond to the plotly trace attributes of a scatter plot.

Unknown Style graph

Style graph

Style `graph`