DecCF./ˈdɛk.ɛf/

Dashboard presentation widgets

Use these widgets in the portal's Presentation editor after the calculation has published the required records or metrics. They display actual calculation results and respond to the selected scenario. The dashboard widgets accept title as text or false, visible as true, false or "auto", and the usual scenario selection ("active", "all", a name, an index or an array of selections).

Money is displayed as whole currency units throughout calculation results, including cards, tables, chart axes and hover descriptions. For example, 1234.56 SEK is shown as 1,235 SEK in English and 1 235 SEK in Swedish. This rounds only the displayed text; calculation values, Monte Carlo summaries, and downloadable calculation records retain their precision. Percentages, ratios, years and probability densities keep their own numeric formatting.

Histogram scenario comparisons

Histogram draws the actual exported distribution bins for the selected metric. Its default scenario selection is the active result. Use scenario:"all" for an overlay, and optionally set maxScenarios to a positive safe integer. When the number of scenarios exceeds that limit, only the active scenario is shown; changing the active scenario updates the diagram without recalculating it. Omitting the limit preserves the existing unlimited all-scenario comparison. The limit applies only to scenario:"all"; explicit named/index selections keep their usual meaning. Invalid limits are rejected. Missing distribution bins remain unavailable; a constant outcome is shown as an observed point.

For example, this compares up to three retirement scenarios and follows the selected scenario when there are four or more:

metric is an actual published metric selector or its exported name. Without one, the first available exported distribution is selected. shape:"bins" draws bins; omission uses the smooth density profile. The diagram retains each scenario's exported probabilities and separates incompatible units/currencies.

Native financial series

Use RecordTable({series}) and RecordChart({series}) to display existing account, flow and metric observations over time. Each entry is {source, label?, key?}. source is a declared account or flow, a results.metric("name") selector, or an existing native series identifier such as "account.bank.balance" or "flow.sales". The optional label names its table column or chart curve. An omitted label uses the published result label; an omitted key uses the entry's position. Explicit keys must be safe, nonempty and unique. These widgets do not need a separate published calculation or a separate metric for each date or age.

In this mode, omit the top-level custom-record source, columns, xKey, highlightKey and record-based uncertainty options. Existing custom-record presentations continue to use their original options. Charts support the same kind, horizontal, normalize, showPoints and numeric unit:"percent" settings described under RecordChart. Tables display all selected temporal rows; charts include an accessible table with their exact observed values. Missing cells display a dash and break curves; zero remains zero. Selected sources must have matching units, currencies and valuation. The widgets do not convert money or recalculate financial values.

period defaults to "months"; "monthly" is an alias. "years" (or "yearly") selects native annual results: flows sum the observed booked amounts, account balances use the endpoint, and metrics use their declared annualAggregation and fiscalYearStartMonth. Ordinary annual storage keeps its actual stored dates and covered periods. Sampled series retain their own full dates and matching deterministic observations, so changing the storage grain does not change the sampled chart. Partial years remain partial. Do not interpret an annual sum as a monthly amount.

Omit percentile to show deterministic observations. An integer from 0 to 100 selects that exported temporal percentile after Monte Carlo. The selected standard series must be included in the calculation's monteCarlo.series selection. Annual percentiles come from each trial's annual aggregation before summary statistics; they are never calculated by adding monthly percentiles. Unavailable summaries, dates or percentiles stay unavailable and never borrow a deterministic observation. Before simulation, the selected deterministic values appear with an explanatory note. A difference of two selected percentiles is not the percentile of their trial differences: select an actual metric for the quantity you want to compare.

xAxis is an optional data object:

OptionMeaning
kind:"date"Actual observation dates; the default for monthly results.
kind:"year"Calendar year labels; the default for annual results.
kind:"age"currentAge plus the difference in calendar years from the starting date.
currentAgeA finite number or an actual declared numeric input reference; required for age.
startDateOptional ISO starting date for age; otherwise the first observation date.

Age labels advance when the calendar year changes, including for a partial starting year. They are labels for the existing observation, not a new calculation of its timing. Use the same timing convention when comparing series. Declared inputs bind to their exact precondition name and nested field path and read the effective value separately for each selected scenario; they are not copied from the initial declaration.

date:"YYYY-MM-DD", zero-based periodIndex, and year select exact temporal rows. Do not combine date with periodIndex. years:[2026,2027] filters calendar-year rows. ages:[65,70] filters an age axis. Either list may also be a declared numeric-array input. For an object-array input, use ages:{source:chosenAges,field:"age"} to select its current numeric field values. This only selects existing rows; it never creates an absent age or fills a gap. For a containing input object, add a safe dot-separated path (or path array) to select its row array. An optional when:{path:"automatic",equals:false} compares a field of the selected input object with a scalar using strict equality. When it matches, the row list filters the results. When it does not match, an optional otherwise selects an alternative list; omitting it shows all existing rows. For example, ages:{source:budgetSettings,path:"ages",field:"age",when:{path:"automatic",equals:false}} lets the same input choose between all rows and explicit ages. A condition accepts only a finite number, string, boolean or null as its comparison value. Unavailable input sources and unsafe paths are rejected.

List entries can be finite numbers, declared numeric input references, or {add:[left,right]}. Addition takes exactly two operands with the same supported forms and may nest to depth 32. The result must be a finite number; Money, missing inputs and other operations are rejected. These expressions select existing display coordinates; they do not calculate financial results. Repeated coordinates select the row once, and coordinates outside the observed horizon create no extra rows. For example, otherwise:[currentAge,{add:[currentAge,2]}] selects the current age and the age two calendar years later. The same forms work directly in ages or years. Input values are resolved for each scenario.

range:{from:currentAge,to:lastAge} applies inclusive bounds to an age or year axis. Each endpoint accepts the same finite number, numeric input reference or addition expression as a list entry. Either endpoint may be omitted to leave that side unbounded; omitting range keeps all existing coordinates. The lower bound must not exceed the upper bound. A range is rejected on a date axis. Bounds resolve independently from each scenario's effective inputs and apply before explicit age/year lists. Charts, tables and final outcome cards use the last point remaining after both selections. Only displayed rows change; the full calculation horizon remains available to other views.

scenario uses the ordinary active, all, named and indexed selections.

For example, enter this calculation in the portal's calculation editor:

The presentation selects those ordinary financial declarations directly:

The same declarations work for a rental property's receipt flow and reserve account, a business's sales and cash, or any other standard financial series.

UncertaintyChart({source}) selects one temporal standard series instead of an authored metrics point list; do not combine the two. Its period, xAxis, date, periodIndex, year, years, ages and range use the same selection rules. percentiles defaults to [5,50,95], with unique integers from 0 to 100. Only exported observations are drawn, together with a distinct dashed deterministic base curve. Its existing scenario, maxScenarios, overflowPercentiles, summaryScenario, successMetric, finalOutcome and showValues settings also apply. Final outcome cards use the actual final selected point; a missing final sampled median stays unavailable.

Sampled calculation sources

DataCards, RecordChart, RecordTable and each Breakdown item's source accept a shared wrapper around a published calculation or projection:

values is one actual published calculation reference or projection, including results.calculation("publishedName"). It cannot be a flow, metric selector, list or another wrapper. Existing ordinary source references keep their published-record behavior. The wrapper changes only the selected displayed fields; it does not change the saved calculation or create new records.

percentile is an integer from 0 to 100 and defaults to 50 (P50, the median). metrics is a nonempty record mapping field paths to metric expressions. Paths are safe, nonempty dot-separated own field names relative to values; for example "age65.income" selects income inside row age65. Each path must select an existing declared numeric or Money field. Text, boolean, record and Money subfields such as amount are not valid targets. Unsafe or unknown paths, invalid selectors and incompatible declared types are rejected. A projection's paths start inside that projection, without repeating its outer path.

After Monte Carlo has run, every metric selector reads the requested percentile from that metric's actual sampled summary. Missing sampled metrics or requested percentiles become null: cards and tables show a dash and charts leave gaps. They never become zero or borrow a deterministic value. Actual sampled zero stays zero. The presentation never estimates an unexported percentile. A row absent from the published snapshot stays absent; a mapping never adds it. Fields without mappings retain their published values, including labels, row order and x coordinates.

Before Monte Carlo has run, the wrapper displays the original published values and the widget explains that these are deterministic observations. The source's usual scenario, date, period and year selections still apply. Mapping fields become optional in the displayed record so missing sampled values remain valid gaps; other declared fields keep their existing validation.

Metric expressions and units

A mapping value may be an actual results.metric("name") selector, a finite numeric constant, or one of the following expressions. Operands can contain other expressions. Only these declared operations are supported; arbitrary callbacks, transforms and new records are not supported.

ExpressionResult and validation
{subtract:[left,right]}Left minus right; operands must have matching units and currencies
{multiply:[left,right]}Product; at most one operand may be Money
{divide:[left,right]}Quotient; matching Money currencies produce a plain number, and Money divided by a plain number keeps its currency
{divide:[left,right],onZero:0}Optional finite numeric or null result when the divisor is zero; omitted onZero defaults to null
{divide:[left,right],onZero:{whenZero:0,otherwise:null}}When the divisor is zero, return whenZero for a zero numerator and otherwise for a nonzero numerator; both fields are required finite numbers or null
{subtract:[left,right],minimum:0}Optional finite minimum and/or maximum clamp in the expression's resulting unit; minimum cannot exceed maximum
{multiply:[value,1],nullAbove:limit}After clamps, keep the result only when it is at most the selected limit; otherwise return null. The limit is a same-unit expression, metric or finite constant. A missing limit also returns null.

Null operands propagate through expressions. Metric metadata and the resulting unit/currency must match the target field's declared and observed values. Plain numbers do not acquire the app's currency. Numeric constants serve as factors, divisors or numeric results; they cannot stand in for Money in a subtraction. Money expressions require a Money target, and numeric expressions require a numeric target; the wrapper does not convert between them. Nonfinite numbers, incompatible currencies or unsupported unit combinations are rejected. Multiplying two Money operands is unsupported.

For a budget, map income and expenses to their P50 metrics, then derive the gap as max(0, P50 expenses - P50 income) with subtract and minimum:0, as above. This is the positive difference of the two medians, not the median of simulated differences. A withdrawal share can use a nested divide of mapped Money expressions; clamp it to minimum:0,maximum:1 when that matches the displayed meaning. Each metric is summarized independently at each point, so no single simulated path need follow all displayed values. No variance band or extra percentile curve is added by a source wrapper.

P50 income and expenses with a derived gap

When annualRows publishes rows age65 and age70 with fields age, income, expenses and gap, the following presentation selects P50 amounts. All metric names must exist in the calculation and describe compatible amounts at the stated ages:

The line chart draws only the income and expense lines, and its expandable Chart values table uses those same P50 values. The separate record table also displays the positive difference between the expense and income medians. Use the same expressions wherever that quantity appears.

For DataCards, map the card's existing numeric or Money value field; its label and other metadata remain published values. If dashboardCards publishes a Money-valued gap card and a numeric gapShare card, derive both from the same median amounts. The share below means the positive gap divided by expenses:

The division policy displays zero for zero gap divided by zero expenses and an unavailable value for a nonzero gap divided by zero expenses. gapShare can use published format:"percent" to display its fractional value as a percentage.

For Breakdown, wrap each item's published source and use its usual path to select the contribution. Mapping paths remain relative to the wrapper's values, before the item's path selection. Aggregation and explicit signs then apply to the selected values:

DataCards

Use MetricCards for simple KPIs whose labels and units already belong to their metric declarations. Use DataCards when cards need explanatory detail, tone or a different display format. Choose one of two inputs: cards declares that display metadata in the presentation; source reads existing published card records. Combining them is rejected. Both return a responsive group of cards for each selected scenario, in the declared record's order.

Declared cards with metric or calculation values

DataCards({cards:{key:{label,value,detail?,tone?,format?,unit?}}, percentile:50}) keeps labels and layout in the presentation without publishing another record of display data. cards must be a nonempty named record with safe own-property keys. Each label is nonempty text and each value is required:

  • results.metric("name") selects an actual declared metric.
  • results.calculation("name"), or a published calculation's .project(...),

selects a scalar calculation value: finite number, Money, text or an optional unavailable value. A record or array is unsupported.

  • A supported metric expression uses finite numeric constants, metric selectors,

subtract, multiply or divide, with the clamps, nullAbove and zero-division policies described under Sampled calculation sources. Calculation selectors cannot be operands inside a metric expression.

The metadata fields have the same meanings and validation as source cards in the table below. They are static text/data, never callbacks, getters or executable code. Unsafe keys such as constructor, unknown fields, invalid formats and incompatible numeric/Money operations are rejected.

Before Monte Carlo, metric expressions use their deterministic metric values. After Monte Carlo, each metric leaf uses only the selected exported percentile; percentile is an integer from 0 to 100 and defaults to 50. Missing metric samples remain unavailable rather than falling back to the deterministic value. Expressions combine those selected percentile values; a difference of two medians is not the median of the trial-by-trial differences. Money keeps its currency and the monetary operand's valuation date; a plain numeric ratio does not acquire a currency. Zero remains zero and unavailable values display a dash.

Calculation selectors retain their deterministic published snapshots, including after Monte Carlo. The widget uses their latest non-null value matching date, periodIndex or year; an exact missing observation remains unavailable. These snapshot options do not change final metric values or sampled metric percentiles. The top-level percentile option belongs only to cards; a sampled source keeps its percentile inside the source wrapper.

For example, enter this business calculation in the model editor:

Then enter this in the presentation editor:

The cards display 30,000 SEK, 25% and 500,000 SEK. The same presentation can use scenario results and exported percentiles without changing its metadata.

Published source cards

DataCards({source, columns:3, title:false}) displays independent cards in the source record's order. source is a published calculation reference or a projection, including results.calculation("publishedName"), or the sampled source wrapper above. Its result is a named record or map with one record per card:

FieldSupported value
labelRequired nonempty text
valueFinite number, Money, text, null or omitted
detailOptional explanatory text
tone"positive", "negative", "warning" or "neutral" (default)
format"number", "percent", "money" or "yesNo"; omitted preserves the value's type
unitOptional text appended after the formatted value

For example, a published card record may contain {income:{label:"Monthly income",value:moneyValue,detail:"After tax",tone:"positive"}}. The widget selects the latest nonempty observed record by default. columns accepts an integer from 1 to 12 and defaults to 3; the cards adapt to narrower screens and panes. A missing value displays a dash and zero stays zero.

Percent format reads a fraction, so 0.25 becomes 25%; Money is unsupported for percentages. Money keeps its own currency. unit adds a suffix such as "/month" without replacing that currency. Numeric "money" format needs an explicit unit; untyped numbers never inherit the application's currency. Text does not accept a numeric format. Labels and details display as plain text. Unsupported card fields, invalid tones, nonfinite numbers and malformed records are rejected. Published optional metadata may be null, with the same meaning as omitting it. At least one card must have an observed value.

format:"yesNo" accepts a plain number from 0 through 1: values at least 0.5 display YES, lower values display NO, and unavailable values remain a dash. This can display the P50 of a simulated zero/one outcome. Money, text, out-of-range and nonfinite values are rejected; the format never uses the deterministic outcome to fill a missing sampled observation. Displayed words follow the app language.

Binary outcomes and censored ages

Publish numeric outcomes rather than a preformatted YES/NO string. For an age search, retain unsuccessful trials as a finite value beyond the lifetime used by the plan; dropping those trials would bias the reported median. Choose the bound so an interpolated median involving an unsuccessful upper-middle trial also lies beyond the lifetime. Then use nullAbove to show unavailable ages. The following minimal model demonstrates the presentation contract:

In the presentation editor, select the actual sampled median of each outcome:

An ordinary run uses the original published card values. A Monte Carlo run uses P50, with ages above the selected lifetime displayed as a dash. Failed age-search trials must still contribute to the metric distribution.

RecordChart

RecordChart({source, xKey:"age", series, kind:"line"}) plots a published named record or map of rows. source accepts the same published calculation references and projections, including the sampled source wrapper described above. Each row has a finite numeric xKey field and the selected numeric or Money fields. The row order and x labels are preserved.

series is a nonempty array of {key, label?} records. Keys must be unique safe field names; omitted labels use the keys. xKey defaults to "age". Missing optional series values create gaps, while numeric zero remains visible. With an ordinary calculation reference as source, every line reads the published record values, including after a Monte Carlo run.

OptionBehavior and default
kind"line" (default), "horizontalBar" for grouped horizontal bars, or "stackedBar" for signed stacks
horizontalfalse by default; true turns stacked bars horizontal
normalizefalse by default; true shows each nonnegative stacked row as percentages
highlightKeyOptional boolean row field; true rows receive a shaded background
unitOptional "percent" to format plain numeric fractions as percentages; other units come from the selected values

Every observed series value must use the same unit or currency. Money and untyped numbers cannot be mixed on one axis. Negative values work in ordinary bar charts but are rejected for normalized stacks. Normalization is supported only with kind:"stackedBar"; it never replaces the original amounts in the expandable Chart values table. SVG titles and the table retain exact labels, units and unavailable values. No observed numeric cells is an invalid selection.

Sampled uncertainty bands

For a line chart, add uncertainty:{lower,upper,opacity:0.5,fade:true} to draw filled percentile bands behind the center lines. Each age uses its own sampled percentiles. Both bounds are sampled calculation sources using values, metrics and percentile. The lower percentile must be less than the upper percentile; both must be integers from 0 to 100. They align with the center source by scenario, exact snapshot date, row key and numeric x value. Each band field must have an explicit mapping in both bounds. Unmapped fields stay empty. Missing sampled metrics or requested percentiles produce gaps, never baseline bands or fabricated zeroes. Before Monte Carlo, only the ordinary center values are shown.

Bands use each line's color with no stroke or markers. opacity is a finite number from 0 through 1, default 0.1, meaning 90% transparent. The vertical scale includes the full bounds. Optional fade:true smoothly fades the fill from its configured opacity along the plotted line to transparent at both curved edges. It follows the actual upper and lower bounds at every age, rather than a single vertical fade across the whole diagram. The default is fade:false, a uniform fill. Missing center values break the fade. If a plotted value lies outside the sampled bounds, the peak stays at the nearest observed edge; the area never extends beyond those bounds. For 50% transparency along the line with transparent edges, set opacity:0.5, fade:true. Missing endpoints break the filled area; the chart never bridges a missing interval. Matching units/currency and ordered lower/upper amounts are required. Uncertainty bands are supported only for kind:"line".

showPoints is a boolean, default true. Set it to false to hide the center line's point markers too. The lines, their accessible value descriptions and the observed-value table remain available. Other chart types keep their normal bar rendering.

For the retirement example's published lifetime rows, this displays income and expense medians with actual P5–P95 bands:

The retirement app's funding-gap center line remains P50 expenses minus P50 income, clamped at zero. Its band uses the actual simulated gap's P5 and P95; subtracting separate income/expense percentile endpoints would describe a different range. All bounds honor the selected money basis and observation dates.

DataCards and RecordChart also accept date:"YYYY-MM-DD", periodIndex as a nonnegative integer, or year as a four-digit year. date and periodIndex cannot be combined. Selections apply to the published snapshot's calendar period, rather than the row's x label. An unavailable exact period never falls back to another period. Use a published projection when only one nested record should be displayed.

UncertaintyChart

UncertaintyChart({metrics, percentiles:[5,50,95], successMetric?}) compares actual Monte Carlo percentile trajectories with a dashed deterministic base case. metrics is a nonempty ordered array of {metric:results.metric("publishedName"), label:"Point label"}. Each metric must be unique. Labels are required nonempty text and determine the x labels.

percentiles defaults to [5,50,95]. Supply unique integers from 0 to 100; only percentiles exported by the actual run appear. They are never invented or estimated from other percentiles. The deterministic curve reads the same metric identifiers from the base calculation, evaluated at the distribution centers. It is displayed distinctly and is not the simulation median or mean. All observed values must have compatible units or currency.

Before Monte Carlo has run, the widget shows the deterministic observations and an explanatory note. Missing metrics are excluded and zero remains observed. Each curve also has a final selected-point outcome card. The expandable Chart values table gives the observed values at every selected point, with money rounded for display. At least one actual base or percentile observation is required.

Optional successMetric:results.metric("success") selects a simulated zero/one outcome metric. Its sampled summary mean, between 0 and 1, is displayed as the success probability. No probability appears before that summary is available; the deterministic success value does not substitute for it.

summaryScenario optionally selects the scenarios for success-probability rows and scenario outcome cards independently of the plotted curves. It accepts the same names, indices, arrays, "active" and "all" as scenario. When omitted, these summaries follow the chart selection. With summaryScenario:"all", every available scenario has its own named probability row, regardless of the active scenario, including a scenario with a success summary but no selected chart observations. Missing simulated success summaries still produce no probability.

finalOutcome defaults to "curves", retaining one final value per displayed curve. Set finalOutcome:"scenarioMedian" to show one card per summary scenario, labelled with its name and containing its actual P50 at the last observed point. The card reads the exported P50 even when the chart's percentiles list omits

  1. If Monte Carlo has not run, it uses that scenario's deterministic value.

A missing P50 after simulation remains unavailable, never a baseline substitute. Scenarios ending at different points have separate headings so the displayed age remains accurate. Use this mode with opening-portfolio metrics labelled by age; its heading identifies the start of that age.

Use scenario:"all", maxScenarios:3 to overlay the scenarios in one diagram when there are up to three. Above the limit, the diagram follows the active scenario. maxScenarios must be a positive safe integer; omission retains the existing separate, unlimited scenario charts. The limit applies only to scenario:"all". An overlay aligns the authored metric points, leaves missing points empty, and requires matching units or currency across scenarios.

overflowPercentiles optionally supplies a second list of unique integer percentiles from 0 to 100 for the active scenario when the limit is exceeded. Omission uses the ordinary percentiles list. Both lists are validated, and only actual exported percentiles appear. For example, percentiles:[50] with overflowPercentiles:[5,50,95] compares median and base curves for up to three scenarios and adds P5/P95 for a single selected scenario above the limit. The limit and alternate curves do not restrict summaryScenario:"all".

showValues is a boolean, default true. Set it to false to omit the expandable Chart values table. The diagram, accessible SVG descriptions, probability rows and outcome cards remain available. Unsupported finalOutcome modes and nonboolean showValues values are rejected.

When plotting a portfolio by age, every metric must describe the same moment, such as the opening portfolio at that age. Percentile trajectories connect per-point summaries; an entire simulated path need not follow one percentile line.

The example names must match actual published calculations and metrics in your app. Presentation code selects the results; it does not create these metrics, rewrite the calculation or fabricate alternative outcomes.