Report Specifications

A Report Specification is specific to a block model. BMS provides endpoints for creating, updating, listing, and viewing Report Specifications.

Various parts of the Report Specification refer to units and unit types.

Creating and updating Report Specifications

The following is an example request body for creating and updating Report Specifications.

{
    "name": "Block Model Resource Report Specification Name",
    "description": "Report Specification description",
    "autorun": true,
    "bbox": {
        "i_minmax": {
            "min": 0,
            "max": 3
        },
        "j_minmax": {
            "min": 0,
            "max": 3
        },
        "k_minmax": {
            "min": 0,
            "max": 3
        }
    },
    "categories": [
        {
            "col_id": "11111111-2222-3333-4444-555555555555",
            "label": "Lithography"
        }
    ],
    "columns": [
        {
            "col_id": "11111111-2222-3333-4444-555555555555",
            "output_unit_id": "t",
            "aggregation": "SUM",
            "label": "Column label"
        }
    ],
    "cutoff_col_id": "11111111-2222-3333-4444-555555555555",
    "cutoff_values": [0, 1, 2, 3],
    "density_col_id": "11111111-2222-3333-4444-555555555555",
    "density_unit_id": "kg/m3",
    "density_value": 2.5,
    "mass_unit_id": "t",
    "negative_values_policy": "IGNORE_BLOCK",
    "null_values_policy": "IGNORE_BLOCK"
}

Definitions of payload fields as follows:

• name (Required)
• description (Optional)
• autorun (Optional)
• bbox (Optional)
• categories (Optional)
• columns (Required)
• Cut-offs (Optional)
• Density Information (Required)
• mass_unit_id (Required)
• Value policies (Optional)

name (Required)

The human-readable label used to identify the Report Specification. Report Specifications for a block model cannot share the same name.

description (Optional)

A free text description of the report.

autorun (Optional)

If the autorun flag property is set, BMS will automatically trigger a Reporting Job for this Report Specification whenever a new version of the block model is published.

bbox (Optional)

The field bbox refers to an optional bounding box to be used for the report, and can either be defined in terms of IJK or XYZ. If you do not provide this, all blocks in the version are considered.

IJK bounding box

When using an IJK (block index) bounding box, it should be of the following form.

{
    "i_minmax": {
        "min": "int",
        "max": "int"
    },
    "j_minmax": {
        "min": "int",
        "max": "int"
    },
    "k_minmax": {
        "min": "int",
        "max": "int"
    }
}

• An IJK bounding box must be in bounds of the index extents of the model, and must make a non-empty selection of blocks to be considered valid by the server.
• The corners of the bounding box defined by min_corner = (i_min, j_min, k_min) and max_corner = (i_max, j_max, k_max) must follow min_corner <= max_corner to result in a non-empty selection of blocks.
• The index extents of a block model are defined in terms of the n_blocks of the model dx, dy, and dz, and refer to the range of valid integer values an I, J, or K index can have. For example, if we have dx = 10, dy = 5, and dz = 7 for some block model, then the valid range of values for i, j, k min/maxes are as follows:
  • 0 <= i_min < dx or 0 <= i_min <= 10 - 1
  • 0 <= j_min < dy or 0 <= j_min <= 5 - 1
  • 0 <= k_min < dz or 0 <= k_min <= 7 - 1

XYZ bounding box

An XYZ (centroid coordinate) bounding box should be of the following form.

{
    "x_minmax": {
        "min": "float",
        "max": "float"
    },
    "y_minmax": {
        "min": "float",
        "max": "float"
    },
    "z_minmax": {
        "min": "float",
        "max": "float"
    }
}

• An XYZ bounding box should be model aligned. If the model is rotated, then the XYZ bounding box should also be rotated.
• An XYZ bounding box must have min < max.
• An XYZ bounding box can exceed the bounds of the model, as we select centroids based on whether they are encapsulated by the bounding box or not.
• For more details on XYZ bounding boxes, see XYZ bounding boxes and rotations.

categories (Optional)

Categories are used to configure the rows to output in each result table. Each entry has a property col_id, which is the column in the block model to use. The values property is reserved for future use, and is currently ignored.

Initially, a maximum of one entry in the categories list will be supported. If provided, the tables in the Report Result will use this as the first column.

In addition to the category-value rows, a "Totals" row will be added, summarising across all the rows. If categories is not provided, only the "Totals" row will exist, summarising all blocks that pass the bounding box and cut-off.

Examples

Given that the following block model data (for 1-metre cube blocks, with density=3000 kg/m³) is within the bounds of the bounding box and cut-off values provided.

i	j	k	Rock type	Gold (ppm)
0	0	0	quartz	10
0	0	1	granite	25
0	1	0	Quartz	20
0	1	1	Slate	15
1	0	0	quartz	10
1	0	1	granite	35
1	1	0	Quartz	25
1	1	1	Quartz	15

A Report Specification with no categories (and a single sum column "Gold") would produce a table per cut-off with no category columns and a single "Totals" row.

Mass (t)	Gold (g)
24	465

A Report Specification with a category with a col_id matching that for "Rock type" and no values would produce an output with rows for "quartz", "granite", "Slate", and "Totals".

Rock Type	Mass (t)	Gold (g)
quartz	15	240
granite	6	180
Slate	3	45
Totals	24	465

columns (Required)

Columns are used to configure the output columns in the Report Result. Each represents a summary of a column in the block model.

The following two output columns are automatically calculated:

• Volume: The total volume for all included blocks, calculated using the block model's block size (and block information for sub-blocks).
• Mass: The total mass of material for all included blocks, calculated using the block volume and density. This will be in the unit specified in mass_unit_id.

Configurable columns consist of the following:

• col_id: The ID of the source column in the block model. The column must be of a numeric data type, and have a unit configured.
• label: The column label in the Report Result.
• aggregation: How the summarisation should be computed. This must be one of SUM and MASS_AVERAGE (see below).
• output_unit_id: The output unit. This must be consistent with the source column's unit_id and the aggregation.

Aggregation calculations

• SUM: The the total for the column. The calculation depends on the unit type of the source column:
  • For absolute unit types (such as MASS), this is a simple sum.
  • For x_PER_MASS unit types, this will be the sum of the content for each block, calculated using the block density and volume.
  • For x_PER_VOLUME unit types, this will be the sum of the content for each block, calculated using the block volume.
• MASS_AVERAGE: The arithmetic mean per unit mass for the column. Again, the calculation depends on the unit type of the source column:
  • For absolute unit types, this will be the sum divided by the value in the Mass column.
  • For x_PER_MASS and x_PER_VOLUME unit types, density and volume information will be used to calculate the sum as for SUM, then this will be divided by the value in the Mass column.

Output units

The reporting system will automatically convert results to the unit specified in output_unit_id, using standard conversion factors. To ensure that this can be done, the API will validate that the output_unit_id is consistent with the unit_id of the source column, and the aggregation.

SUM

For the SUM aggregation, the output unit must be of an absolute type (LENGTH, MASS, VOLUME, or VALUE).

• For absolute values (such as where the unit type is MASS), the output unit should have the same unit type as the source unit.
• For relative values (i.e. where the column's unit is a x_PER_y type):
  • The source column's unit type denominator y must be MASS or VOLUME
  • The output type should have the same unit type as the numerator x

Examples given below:

• A column with unit lbm (unit type MASS) can be output as t (also MASS).
• A column with unit $/tn (unit type VALUE_PER_MASS) can be output as $ (unit type VALUE).

MASS_AVERAGE

For the MASS_AVERAGE aggregation, the output unit must be a relative unit with a unit type that adheres to the following:

• The numerator type is:
  • For absolute values (such as where the source unit type is MASS), the same as the source unit type
  • For relative values, the same as the source unit's numerator type
• The denominator type is MASS

Examples given below:

• A column with unit lbm (unit type MASS) can be output as g/t (unit type MASS_PER_MASS).
• A column with unit $/tn (unit type VALUE_PER_MASS) can be output as $/t (also VALUE_PER_MASS).

Cut-offs (Optional)

The cutoff_col_id and cutoff_values properties allow configuration of cut-offs of the report. The Report Result will include a result table for each entry in cutoff_values, or a single table if no cut-off is configured.

The cutoff_values are minimum values for the column referenced in cutoff_col_id. Blocks (that are within bbox if provided) will be included in the given cut-off value's table if they have a value for the cut-off column that is greater or equal to the value.

Example

{
    ...
    "cutoff_col_id": "ed19712e-f420-4003-8e28-8cf0fdf027a8",
    "cutoff_values": [0.5, 1.5],
    ...
}

The result will contain a table for blocks where the cut-off column is greater or equal to 0.5, and another where the cut-off column is greater or equal to 1.5. The blocks in the second will be a subset of those in the first.

Density information (Required)

To calculate mass and correctly summarise, the reporting system requires information about block material density. This can be configured in two ways:

• Using density_col_id. This should be the ID of a column in the model which contains the density for each block. The column must have a numeric data type, and a unit of type MASS_PER_VOLUME.
• Using density_value and density_unit_id. This provides a value to use across all blocks in the model.
  • density_value must be greater than 0.
  • density_unit_id must be the ID of a unit of type MASS_PER_VOLUME.

Both approaches can be used together, in which case the value in the column referenced by density_col_id will be used if it is non-null, positive and non-zero, else density_value will be used.

mass_unit_id (Required)

The ID of the unit to use for the Mass column. This unit must be of unit type MASS.

Value policies (Optional)

The policy fields negative_values_policy and null_values_policy can be used to control how reporting treats negative and null values in blocks. For more information, see Negative and null values in cut-off and value columns.

Query parameter (Optional)

Both the Create a Report Specification and Update a Report Specification endpoints accept an optional run_now query parameter. When you set it to true, a Reporting Job is created for the new revision and is run against the latest version of the block model. By default, or if you set it to false, no Reporting Job is created during the create or update Report Specification operation.