Submit a request
Submit a request

Columns Reference for Large Group Reporting

This page describes the various types of columns (and other related types) that can be used in configuring the display of data in aggregate reports.

Columns may be specified as a list of ColumnDefinition objects. Each ColumnDefinition has a type (matching one of the column types listed) and a set of additional properties specific to that type. The available properties for each type are documented here.

A type of column that represents the name of the group for each row in a group-level dataset.

This column type is only applicable in group-level columns configuration. It will automatically obtain its value from the group_name field in the dataset. In addition to rendering each group's name, this column type can be used for navigating down the group hierarchy to view the data for that group.

This type supports the use of the displayNameListener() callback. Using this will replace the on-screen value for each cell in the column. The value that is passed to the callback for each row is the group_name.

Type object
Property Description
type
string

Required. Indicates the type of column. Must be "group_name".

label
string

The display label to use as the column header. By default, the label is taken from the label_bundle based on the column type.

Default: null

{
    type: "group_name"
}

A type of column that represents the identifier or name of a user for each row in a user-level dataset.

This column type is only applicable in user-level columns configuration. It will automatically obtain its value from the user_id field in the dataset.

This type supports the use of the displayNameListener() callback. Using this will replace the on-screen value for each cell in the column. The value that is passed to the callback for each row is the user_id.

Type object
Property Description
type
string

Required. Indicates the type of column. Must be "user_id".

label
string

The display label to use as the column header. By default, the label is taken from the label_bundle based on the column type.

Default: null

{
    type: "user_id",
    label: "Student"
}

A type of column that represents a simple numeric value. Useful for rendering fields from the dataset containing numeric values.

Type object
Property Description
type
string

Required. Indicates the type of column. Must be "numeric".

field
string

Required. The field in the dataset from which to obtain the value.

decimals
number

Rounds values to the specified number of decimal places.

Default: null

label
string

The display label to use as the column header. By default, the label is taken from the label_bundle based on the column type.

Default: null

{
    type: "numeric",
    field: "score",
    decimals: 2
}

A type of column that allows plotting a variety of graphical elements (chart components) in a cell to represent 1-dimensional values and ranges.

Type object
Property Description
type
string

Required. Indicates the type of column. Must be "1d_plot".

elements
array<object>

Required. An array of PlotElementDefinition objects, each representing a component to plot in the cells of this column.

Each element must be any one of the following types: ScaleBracketBoxPlotWhiskerPlotShadingPlotLinePlot or ScorePlot.

Cannot be an empty array.

max
number

Defines the upper bound of the range of values to show in the 1D plot cell. The specified maximum is inclusive.

Default: 100

min
number

Defines the lower bound of the range of values to show in the 1D plot cell. The specified minimum is inclusive.

Default: 0

label
string

The display label to use as the column header. By default, the label is taken from the label_bundle based on the column type.

Default: null

{
    type: "1d_plot",
    label: "Results",
    elements: [
        {
            type: "shading_plot",
            source: "ancestor_1",
            shape: "area",
            min: "lowest_percent",
            max: "highest_percent",
            class: "shading-outer-quartile"
        },
        {
            type: "score_plot",
            shape: "down_chevron",
            source: "row",
            score: "median_percent",
            label: true,
            label_y: "top"
        }
    ]
}

This section lists the types of plot elements that can be used in the 1DPlot column type.

Represents a scale bracket in a 1D-plot cell.

Type object
Property Description
type
string

Required. Indicates the type of element. Must be "scale_bracket".

source
ElementSource

Required. The data source used to supply this element's score values. See: ElementSource

min
number | GroupField | UserField

Minimum end of the scale bar. Specify a fixed numeric value, or the string name of the field to use from the specified source.

Default: column.min

max
number | GroupField | UserField

Maximum end of the scale bar. Specify a fixed numeric value, or the string name of the field to use from the specified source.

Default: column.max

labels
boolean

Specifies whether the min and max points should be labeled with their numeric score value.

Default: true

{
    type: "scale_bracket",
    labels: false
}

Represents the box component of a box-and-whisker in a 1D-plot cell. Use the optional middle property to plot a vertical line at a given score within the box.

Type object
Property Description
type
string

Required. Indicates the type of element. Must be "box_plot".

source
ElementSource

Required. The data source used to supply this element's score values. See: ElementSource

min
number | GroupField | UserField

Required. Minimum end of the box. Specify a fixed numeric value, or the string name of the field to use from the specified source.

max
number | GroupField | UserField

Required. Maximum end of the box. Specify a fixed numeric value, or the string name of the field to use from the specified source.

middle
number | GroupField | UserField

Score at which to plot a vertical line within the box. Specify a fixed numeric value, or the string name of the field to use from the specified source, or null to omit the vertical line.

Default: null

labels
boolean

Specifies whether the min, max and middle points should be labeled with their numeric score value.

Default: true

{
    type: "box_plot",
    source: "row",
    min: "p25_percent",
    max: "p75_percent",
    middle: "median_percent",
    labels: true
}

Represents the whisker component of a box-and-whisker in a 1D-plot cell.

Type object
Property Description
type
string

Required. Indicates the type of element. Must be "whisker_plot".

source
ElementSource

Required. The data source used to supply this element's score values. See: ElementSource

min
number | GroupField | UserField

Required. Minimum end of the whisker. Specify a fixed numeric value, or the string name of the field to use from the specified source.

max
number | GroupField | UserField

Required. Maximum end of the whisker. Specify a fixed numeric value, or the string name of the field to use from the specified source.

labels
boolean

Specifies whether the min and max points should be labeled with their numeric score value.

Default: true

{
    type: "whisker_plot",
    source: "row",
    min: "lowest_percent",
    max: "highest_percent"
}

Represents a lightly shaded area taking the full height of a 1D-plot cell.

Type object
Property Description
type
string

Required. Indicates the type of element. Must be "shading_plot".

source
ElementSource

Required. The data source used to supply this element's score values. See: ElementSource

min
number | GroupField | UserField

Minimum end of the shading area. Specify a fixed numeric value, or the string name of the field to use from the specified source.

Default: column.min

max
number | GroupField | UserField

Maximum end of the shading area. Specify a fixed numeric value, or the string name of the field to use from the specified source.

Default: column.max

class
string

Specifies a custom CSS class to be added to the shaded area element.

Default: null

{
    type: "shading_plot",
    source: "ancestor_1",
    min: "p25_percent",
    max: "p75_percent",
    class: "shading-inner-quartile"
}

Represents a vertical line taking the full height of a 1D-plot cell.

Type object
Property Description
type
string

Required. Indicates the type of element. Must be "line_plot".

source
ElementSource

Required. The data source used to supply this element's score values. See: ElementSource

score
number | GroupField | UserField

Required. Score at which to plot the score line. Specify a fixed numeric value, or the string name of the field to use from the specified source.

class
string

Specifies a custom CSS class to be added to the line plot element.

Default: null

{
    type: "line_plot",
    source: "ancestor_1",
    score: "median_percent",
    class: "shading-reference-percentile",
    label: false
}

Represents a point (defined by a numeric score) along the plane of a 1D-plot cell.

Type object
Property Description
type
string

Required. Indicates the type of element. Must be "score_plot".

source
ElementSource

Required. The data source used to supply this element's score values. See: ElementSource

score
number | GroupField | UserField

Score at which to plot the shape. Specify a fixed numeric value, or the string name of the field to use from the specified source.

One of either score or percent are Required.

percent
Array[number | GroupField | UserField]

Specifies that the shape should be plotted as a percentage value, instead of raw scores. Pass an array of exactly two values:

  • The first value is the numerator of the percentage (eg. "score").
  • The second value is the denominator of the percentage (eg. "max_score").

Each value can be either a fixed numeric literal, or the string name of the field to use from the specified source.

One of either score or percent are Required.

shape
string

Specifies which shape should be plotted. Should be one of "circle""vertical_line" or "down_chevron".

The "circle" shape will be vertically centred within the cell, while the "line" and "chevron" are designed to align with the box-plot element.

Default: "circle"

radius
number

The radius of the "circle" shape, in pixels.

Default: 5

class
string

Specifies a custom CSS class to be added to the score plot element.

Default: null

label
boolean

Specifies whether the score plot should be labeled with its numeric score value.

Default: true

label_y
string

Location of the label. Can be one of "top" or "above".

Setting to "top" will render the label at the top of the cell, while "above" will render it just above the rendered shape.

Default: "above"

Example of ScorePlot using a score parameter.

{
    type: "score_plot",
    source: "row",
    score: "median_percent",
    shape: "down_chevron",
    class: "reference-percentile-marker",
    label_y: "top"
}

A second example using percent to plot a user's score as a percentage of the maximum score.

{
    type: "score_plot",
    source: "row",
    percent: ["score", "max_score"],
    shape: "circle",
    class: "score-marker",
    label_y: "top"
}

Other Types

This section lists other important type definitions that occur commonly throughout columns configurations.

The name of a raw data field that exists in the group-level data of the report dataset.

This type is used by plot elements to reference specific group data values in the dataset (e.g. mean_scorestddev_percent) from a given data source.

 

Type string
// The score property in the object below specifies a sample GroupField
// "median_percent" as its value:
{
    type: "score_plot",
    source: "ancestor_1",
    score: "median_percent"
}

The name of a raw data field that exists in the user-level data of the report dataset.

This type is used by plot elements to reference specific user data values in the dataset (e.g. scoremax_score) from a given data source.

 

Type string
// The score property in the object below specifies a sample UserField
// "max_score" as its value:
{
    type: "line_plot",
    source: "row",
    score: "max_score"
}

Enumerated string value, used to identify which data source should supply the score values for a plot element.

Valid ElementSource values are "row""parent", or "ancestor_n".

 

  • row: retrieve score values from this row's data (ie. the group data represented by this row, or the student scores represented by this row).
  • parent: retrieve score values from the parent group of this row.
  • ancestor_n: retrieve score values from the nominated ancestor row n, where 0 represents the root group of the aggregate report.

 

Type string
// The source property in the object below specifies an ElementSource of
// "row", meaning that the data should come from the current row:
{
    type: "score_plot",
    source: "row"
}
Was this article helpful?
0 out of 0 found this helpful