Report Comparisons

The reporting engine supports comparisons between two versions of a block model, based on a Report Specification. The versions are referred to as follows:

• The "from" version. This is the baseline from which changes will be calculated relative to.
• The "to" version. This is the version to be compared.

The "from" version can be newer than the "to" version, if desired.

The comparison subsystem consists of three parts:

1. Requesting a Report Comparison Job.
2. The Report Comparison Job.
3. The Report Comparison Result.

Requesting a Report Comparison Job

You may request for a comparison based on a given Report Specification via a POST to the Run a Report Comparison Job endpoint for that Report Specification, with a from_version_uuid and a to_version_uuid.

The response depends on whether the Report Results for both of the requested versions are available (for the current Report Specification revision).

If both Report Results are available

If both Report Results are already available, the response will contain the UUIDs for them.

{
    "job_url": null,
    "from_result_uuid": "ebc3a4d5-fe5b-49c4-ba1c-39733bbf7023",
    "to_result_uuid": "72adad30-c07c-465d-a1fe-2f2dfac950a4"
}

These can then be used in the Report Comparison Result endpoint.

If one or both Report Results are not available

If either or both of the Report Results are not available for the current Report Specification revision, the reporting system will create a Report Comparison Job, and return its URL.

{
    "job_url": "https://example.seequent.com/blockmodel/orgs/{org_uuid}/workspaces/{workspace_uuid}/block-models/{bm_uuid}/jobs/{job_uuid}"
    "from_result_uuid": null,
    "to_result_uuid": null
}

Report Comparison Job life cycle

A Report Comparison Job represents the compute activity of producing the required results for the comparison. The job_url can be polled via a GET request to retrieve the current status of the job. The server's response is largely determined by the value of the job_status field.

Job status: QUEUED or PROCESSING

• QUEUED: This means that the job is currently queued and waiting to be picked up for processing.
• PROCESSING: This means that production of the Report Results is in progress.

{
    "job_status": "QUEUED" | "PROCESSING" 
}

Job status: COMPLETE

The means that the job has finished and the Report Results are available.

{
    "job_status": "COMPLETE",
    "payload": {
        "report_specification_uuid": "16863251-b9de-461f-bbad-07663eab1a92",
        "from_version_uuid": "802cde30-b9e8-431d-b5f6-c84eef70735f",
        "to_version_uuid": "44dc0124-8d7b-441b-b46b-50f300b50e20",
        "from_result_uuid": "bf857aa3-503e-41be-a46d-7b9ed353ad96",
        "to_result_uuid": "f8eb302e-6727-41a7-ada5-eefad14bb69a"
    }
}

The from_result_uuid and to_result_uuid can then be used in the Report Comparison Result endpoint.

Job status: FAILED

This means that the job failed during processing. If the failure is due to a 500 error, a support ticket should be raised.

{
    "job_status": "FAILED",
    "payload": {
        "status": 500,
        "title": "Internal Service Error",
        "detail": "A service error occurred when processing this job",
        "type": "https://seequent.com/error-codes/block-model-service/compute-service-error"
    }
}

Report Comparison Result

The Get a comparison between two Report Results endpoint does the actual comparison of Report Results. You need to supply the following query parameters:

• from: This is the base Report Result UUID to compare.
• to: This is the Report Result UUID to compare to.

The output includes, among other details:

• from_result: This is information about the result and version that is being used as the baseline. This includes when and by who the version was created, and the details of the columns used (in the referenced_columns list). Note that the referenced columns can differ between the "from" and "to" version, as the source unit for a column may have changed.
• to_result: This is information about the result and version that is being compared, as above.
• categories: This provides information on the category columns used in the report. For each category, the label and col_id is provided.
• value_columns: This provides information on the value columns output in the report. For each, the label, col_id, and output unit_id is provided. The first two entries are for the system-calculated columns Volume and Mass, whose col_id will be null.
• result_sets: the result sets for each cut-off value.
• warnings: This is information on any warning conditions encountered, including handling of null and negative values in the data. This is structured with the following properties:
  • from_result: These are warnings that occurred in generating the "from" result.
  • to_result: These are warnings that occurred in generating the "from" result.
  • comparison: These are warnings that occurred during the comparison operation.

Result sets

The result_sets list contains a result set for each cut-off value requested, in ascending order. If no cut-off is requested, the list will contain a single entry, with a cutoff_value of null.

Each result set is a comparison of the equivalent result set in the "to" result to that in the "from" result. It has a list of rows, each representing the comparisons for a particular category value, plus a "Totals" row. Each row contains:

• categories: This is the category value(s) that this row is calculated for. The values correspond to the columns described in the categories list.
• values: This is the comparison for the value_columns. Each contains the following:
  • from_value: This is the value in the "from" result
  • to_value: This is the value in the "to" result
  • difference: This is the difference in value
  • percent: This is the percent change, relative to the "from" value.

For category values that exist in only one of the two result sets being compared, the values for the row on the missing side are treated as zero.

When calculating the percent change $p$ between a from_value $V_{from}$ and a matching to_value $V_{to}$, the formula used is as follows.

$$p = \frac{V_{to} - V_{from}} {100 |V_{from}|}$$

Note that for negative values, this formula produces valid percentages, but the results can sometimes be counterintuitive. Percentage change for negative "from" values does not have a rigorous mathematical definition.

If from_value is 0 (or missing), percent will be null.

Rounding in Report Comparison Results

The Get a comparison between two Report Results endpoint supports an optional query parameter decimal_places. If specified, values in comparisons are rounded to the specified number of decimal places after the comparison. This can be helpful in suppressing small differences in value due to floating point rounding in Report Results.