Register Reports

TL;DR

A Report is reusable analytics that runs on a job’s output. In Resources → Reports, pick the object type it runs on (Data Element, Feature, Model, Policy), write a Report Definition (Spark, Pandas, or Python) that returns a summary Pandas DataFrame, then add Figures that read that DataFrame (as raw_output) and render it as a table, Plotly chart, Markdown, Excel, or PDF. Optionally add Metrics to track a single number across recurring runs. Select the report when you run a job and it renders as its own tab.

What is it?

A Report is a piece of reusable analytics that runs on a job’s output. For example, a decile report that runs on every model simulation, or a fair-lending report that runs on every policy simulation. You define the calculation once and the platform runs it on every relevant job.

A report has two layers: a Report Definition that computes the statistics and returns a Pandas DataFrame (its return value is called raw_output), and one or more Figures that read raw_output and render it as a table, chart, Excel download, Markdown note, or tracked Metric. The report renders as its own tab in the job results, with all its figures inside.

Registering reports gives you:

• A shared visualization library - build up a catalog of reports with consistent design across every object, instead of re-creating the same charts for each job.
• Reuse across the platform - once configured, a report is available wherever its object type runs (Data Element, Feature, Model, Policy), and from the Notebook.
• Built-in governance - reports move through the same access controls and approval workflow as other registered objects.

Before you start

• Know which object type the report targets (Data Element, Feature, Model, Policy). Each type exposes different columns in the job output, so a report for one type usually won’t work for another.
• If you plan to reuse a calculation across reports, register it first in Resources → Global Functions. See Reuse a calculation with a Global Function.

How to Create a Report

Follow these steps to create a Report.

Open the Create Form

Go to Resources → Reports and click + New Report. Give the report a clear name (for example, Decile Table, ROC Curve and AUC).

Choose what objects the report runs on

Set the Object Type * - the type of object this report runs on, such as Model, Policy, Data Element, or Feature.

Some object types then show an Object Subtype to narrow the report further, and some don’t. It is a multi-select: for a Data Element or Feature you pick one or more feature types; for a Model you pick one or more algorithm types (Binary Classification, Regression, and so on). For types like Policy or Quality Profile, no subtype field appears.

Write the Report Definition (Formula)

There are two optional fields: Resources, to pull in registered Global Functions the definition can call, and Parameters, to accept values the user supplies at run time. Expand for more detail.

A multi-select of registered Global Functions. Each one you select becomes callable in the definition by its alias. Use this when the definition reuses a calculation registered in Resources → Global Functions.

Values the user supplies when running the job, so the report can be reused at different settings instead of hard-coded. Click + Add Parameter; each has a Name, Alias, Is Mandatory, a description, and a Type. Common use: a configurable classification threshold, or a decile count.

The Type decides how the value reaches your definition:

• String - a single text value, resolved by alias (or None if optional and unset).
• Number - a single numeric value, resolved by alias (or None if optional and unset).
• Single Object - a registered object (for example a Data Element or Feature) whose values arrive as a column on data, accessed as data["<alias>"].

Write the Report Definition * in the code editor: the logic that computes the statistics. It must return a Pandas DataFrame, whether you write it in Spark, Pandas, or Python.

Variables you can use in the definition:

• data (PySpark DataFrame): the job’s result data, including every input and output column. It is the same sample results shown in the Job Result section; run a job and open Job Result to see them. Expand below to see how job results look like.

For the full reference, see Understand Job Output.

Each row is one entity, id is the platform key, inputs sit under their own alias, and the result lands in output. The columns follow a consistent naming pattern per object type. Each tab lists the full set of columns, then shows a trimmed sample:

Data Element

Columns:

• id - the platform key.
• the source column - the raw input the Data Element reads.
• output - the Data Element’s value.

The table below shows those columns for a Data Element that reads annual_inc:

id	annual_inc	output
A1001	82000	82000
A1002	54000	54000

Feature

Columns:

• id - the platform key.
• one column per input - each named by its alias.
• output - the Feature’s value.

The table below shows those columns for a Feature with a single input fico:

id	fico	output
A1001	742	A
A1002	605	C

Model

Columns:

• id - the platform key.
• one column per input - each named by its alias.
• one column per transform - if the Model defines any.
• dependent - the target.
• output - the model score.
• explainer - a single column, when a Model Explainer is enabled (a map of contributions or a list of reason codes).

The table below is trimmed to a couple of inputs; a real Model has one column per input:

id	fico	dti	dependent	output
A1001	742	0.31	0	0.08
A1002	605	0.52	1	0.63

Policy

Columns:

• id - the platform key.
• one column per input - each named by its alias.
• <alias> - for each offer-config and framework input, and for each derived variable.
• block-<n> - for each strategy block, where n is the block’s position in the workflow.
• segment-<s>.<n> - for each segment, where s is its strategy block and n is the segment’s position.
• rule-<s>.<n>.<r> - for each rule, where s is the strategy block, n is the segment, and r is the rule’s position.
• output - the policy decision.

Segment and rule columns are booleans (True / False / None); block-<n> and output are outcome strings (Pass / Fail, or a custom outcome). The table below is trimmed to one input, one block, and one rule; a real Policy has a column for every input, block, segment, and rule:

id	fico	block-1	segment-1.1	rule-1.1.1	output
A1001	742	Pass	True	True	Pass
A1002	605	Fail	False	None	Fail

Run a job for the object once and open its Job Result to see the exact columns for your case.

• entity: a Corridor Python object you can query for information about the object the job ran on. For a Model simulation, entity.algorithm_type returns 'Binary Classification', 'Regression', and so on.

• job: a Corridor Python object you can query for information about the job itself. For example, job.job_type returns 'Simulation', 'Monitoring', and so on.

• Selected Global Functions: available by alias.

  Every Global Function you selected under Resources is callable directly, for example a function with alias get_mean is called as get_mean(...). A Global Function is only in scope where you selected it; to use the same one in a figure or metric, select it again under that output’s Resources.

• Report Parameters: available by alias.

  String and Number parameters resolve to a single value (or None if optional and unset). Single Object parameters arrive as a column on data, accessed as data["<alias>"].

Example: an ROC curve summary for a model

This definition reads the model score and the binary dependent, computes the ROC points (false-positive rate, true-positive rate) and the AUC, and returns one Pandas DataFrame with columns fpr, tpr, and auc.

Whatever DataFrame you return here is what Figures and Metrics read, under the name raw_output. They also use its exact column names (fpr, tpr, auc), so if you rename a column in definition, any figure still reading the old name breaks.

import pandas as pd
from sklearn.metrics import roc_curve, roc_auc_score

# 'output' is the model score; 'dependent' is the binary target
pdf = data.select("output", "dependent").toPandas()
scores = pdf["output"].tolist()
labels = pdf["dependent"].tolist()

fpr, tpr, _ = roc_curve(labels, scores)
auc = roc_auc_score(labels, scores)

# one row per ROC point; auc is the same scalar on every row
return pd.DataFrame({"fpr": fpr, "tpr": tpr, "auc": auc})

If a piece of the definition is something you compute in more than one report, register it once as a Global Function and call it by alias instead of copying it. Good candidates are small, reusable statistics, for example an AUC calculation, quantile or summary stats on a score, or binning a variable into deciles. See Reuse a calculation with a Global Function.

Add Figures

The Figures section opens with a Figure 1 block; use Add Figure for more, and drag the grip handle to reorder. For each figure, set its Width *, optionally select Resources (Global Functions to call), and write the Definition that produces the visualization.

A figure’s Definition reads the same raw_output the Report Definition returned and renders it. Depending on what you return, it shows differently:

• Pandas DataFrame - renders as a table.
• Plotly figure - renders interactively.
• Markdown string - renders as formatted text.
• Pandas ExcelWriter - offered as a downloadable Excel file (not shown inline).
• ReportLab Canvas - a PDF.

Inside a figure’s Definition you can access raw_output, entity, and job (the same objects as in the Report Definition), plus any Global Functions you select for this figure and any String or Number Parameters by alias.

Differences from the Report Definition: a figure does not receive data (so Single Object parameters are not accessible), and Global Functions are per-output (select them again under the figure’s Resources).

Continuing the ROC example, raw_output has columns fpr, tpr, and auc. Here is that same result rendered five ways.

Return raw_output (or any DataFrame) to render it as a table.

return raw_output

Return a Plotly figure to render it interactively. This draws the ROC curve.

import plotly.graph_objects as go

auc = raw_output["auc"].iloc[0]

fig = go.Figure()
fig.add_trace(go.Scatter(x=raw_output["fpr"], y=raw_output["tpr"],
                         mode="lines", name=f"ROC (AUC = {auc:.3f})"))
fig.add_trace(go.Scatter(x=[0, 1], y=[0, 1], mode="lines",
                         line=dict(dash="dash"), name="Random"))
fig.update_layout(xaxis_title="False Positive Rate", yaxis_title="True Positive Rate")
return fig

Return a formatted Markdown string, for example a one-line AUC summary.

auc = raw_output["auc"].iloc[0]

return f"**AUC:** {auc:.3f}"

Return a Pandas ExcelWriter to offer the result as an Excel download.

import io
import pandas as pd

writer = pd.ExcelWriter(io.BytesIO())
raw_output.to_excel(writer, sheet_name="ROC")

return writer

The Excel content is not shown inline; the dashboard offers it as a download.

Return a ReportLab Canvas to produce a PDF.

import io
from reportlab.pdfgen import canvas
from reportlab.lib.pagesizes import A4

auc = raw_output["auc"].iloc[0]

c = canvas.Canvas(io.BytesIO(), pagesize=A4)
c.drawString(100, 100, f"AUC: {auc:.3f}")
return c

Each figure also has an optional Enable Custom Comparison toggle, for building a single combined visualization across two jobs instead of showing them side by side. Expand below if you need it.

When you compare two jobs, each figure is shown side by side by default (comparing sim 1 and sim 2, two ROC curves appear next to each other). Turn on Enable Custom Comparison on a figure only when you want a single combined visualization instead, for example both ROC curves on one set of axes.

The figure’s Definition then works against both jobs and exposes:

• base_raw_output, compared_raw_output - the Report Definition output from each job.
• base_entity, compared_entity - the Corridor object for each job.
• base_job, compared_job - the job object for each side.
• Report Parameters by alias (from the base job).

Custom comparison is only available for figures, not metrics, and a custom-comparison figure spans the full dashboard width. Additional figures inherit the same variables (base_raw_output, compared_raw_output, and so on).

Add Metrics (optional)

A Metric is a single numeric value tracked across recurring job iterations: each iteration recomputes it, and the platform generates a trend graph automatically. You set the upper and lower thresholds for alerting later, at job-run time: when you select this report on the job form, a Set Threshold control appears for each metric where you enter the lower and upper bounds.

Click Add Metric to add one. Each metric has its own Resources and Definition. The Definition returns a single number and can access raw_output and job.

Continuing the ROC example, this metric returns the AUC from the same raw_output:

return float(raw_output["auc"].iloc[0])

Return the metric value directly, with no wrapper. Each metric output tracks exactly one number, so to track two (say AUC and KS), add two Metric outputs. No visualization is needed: on each recurring run the platform recomputes the metric and builds a trend report, found under the Tracking tab, so you can watch it drift over time and alert on it.

Fill in Properties and Create

Fill in the Properties (Description, Group, and Keywords), then click Create at the bottom right. The Report is saved as a draft and you land on its details page.

Running the Report

To run a report, select it in the Reports section of the job form when you Run a Simulation. Each selected report runs on the job’s output and renders as its own tab in the results.

To run a report on every job by default, add it to your Default Reports in settings. Default reports are preselected on new jobs for the matching object type.

Reuse a calculation with a Global Function

If a calculation shows up in more than one report, register it once as a Global Function in Resources → Global Functions, then select it under Resources in any report that needs it and call it by its alias. This keeps a single definition of that calculation instead of copies drifting apart across reports.

Small, self-contained statistics are the natural fit. An AUC helper:

from sklearn.metrics import roc_auc_score

def roc_auc(scores, labels):
    return float(roc_auc_score(labels, scores))

Quantile stats on a score:

import numpy as np

def score_quantiles(scores):
    q = np.percentile(scores, [10, 25, 50, 75, 90])
    return {"p10": q[0], "p25": q[1], "p50": q[2], "p75": q[3], "p90": q[4]}

Binning a variable into deciles:

import pandas as pd

def decile_bins(values):
    return pd.qcut(values, 10, labels=False, duplicates="drop")

Once registered and selected, call any of them in a Report Definition (or a figure) by its alias, for example auc = roc_auc(scores, labels).

What’s next

• Run a Simulation with this report selected to see it in action.
• Set up Alerts on a tracked Metric to get notified when it crosses a threshold.