ScoreCard API

A ScoreCard Extension calculates a collection of Performance Metrics based on the results of a WealthLab 9 backtest. Performance Metrics include values such as:

• APR
• Net Profit
• Sharpe Ratio
• Drawdown
• Exposure

Metrics generated by ScoreCards are available throughout WealthLab. They can be displayed by Performance Visualizers, included in optimization results, and used as optimization targets by Optimizers.

Build Environment

You can create a ScoreCard in a .NET development tool such as Visual Studio 2026. Create a class library project that targets .NET10, then reference the WealthLab.Core library DLL that you'll find in the WL9 installation folder.

Your ScoreCard will be a class in this library that descends from ScoreCardBase, which is defined in the WealthLab.Core library, in the WealthLab.Backtest namespace. After you implement and build your library, simply copy the resulting assembly DLL into the WL9 installation folder. The next time WL9 starts up, it will discover your ScoreCard, making it available in appropriate locations of the WL9 user interface.

Accessing the Host (WL9) Environment

The IHost interface provides access to the current WealthLab environment. Extensions can use it to retrieve application-level information and services, such as the location of the user's WealthLab data folder or the DataSets defined by the user.

You can access the current IHost instance from anywhere in your extension through the WLHost singleton and its Instance property. For example, the following code retrieves the path to the user's WealthLab data folder:

string folder = WLHost.Instance.DataFolder;

Use WLHost.Instance whenever your extension needs access to functionality exposed by the IHost interface.

Descriptive Properties

Name

public abstract string Name

Override this property to return the name of the ScoreCard. The name appears in the Metrics Report and other areas of WealthLab where users can select or identify a ScoreCard.

MetricNames

public abstract List<string> MetricNames

Override this property to return the names of the Performance Metrics calculated by your ScoreCard. Each Metric name should be a string that is also a valid .NET property name. For example:

public override List<string> MetricNames =>
    new List<string>
    {
        "MyMetric",
        "MyRatio",
        "MyDrawdown"
    };

These names serve as the internal identifiers for the Metrics. You can provide more descriptive labels when laying out the Metrics Report.

Calculating Performance Metrics

public virtual void Initialize(Backtester bt)

Override Initialize to calculate your ScoreCard's Performance Metrics. The supplied Backtester contains the completed backtest and provides access to information such as Positions, equity, cash, drawdown, and other backtest results. Store each calculated Metric in the Backtester's Metrics property.

Backtester.Metrics

The Metrics property is a dynamic object, allowing ScoreCards to add their own named values. For example:

bt.Metrics.MyMetric = value;

The property name should correspond to one of the names returned by your MetricNames property. Once added to Backtester.Metrics, the Metric becomes available to other parts of WealthLab that consume Performance Metrics, including Performance Visualizers and Optimizers.

Example: Gross Profit and Gross Loss

The following example from the Basic ScoreCard calculates the gross profit of winning Positions and the gross loss of losing Positions:

// Gross profit
double sum = 0;

foreach (Position pos in bt.Positions)
{
    if (pos.Profit > 0)
        sum += pos.Profit;
}

bt.Metrics.GrossProfitWinners = sum;

// Gross loss
sum = 0;

foreach (Position pos in bt.Positions)
{
    if (pos.Profit < 0)
        sum += pos.Profit;
}

bt.Metrics.GrossLossLosers = sum;

Reusing Metrics from Other ScoreCards

Your ScoreCard can use Metrics calculated by other ScoreCards. For example, you can use Metrics supplied by WealthLab's Basic ScoreCard or by ScoreCards installed by other extensions. This makes it possible to create derivative Metrics without recalculating the underlying values. For example, if existing Metrics are available:

double value =
    bt.Metrics.SomeMetric /
    bt.Metrics.AnotherMetric;

bt.Metrics.MyDerivedMetric = value;

The available Metric names can be viewed in WealthLab's Preferences > Metric Columns page. This allows custom ScoreCards to combine existing Metrics, derive new ratios, or otherwise build on calculations already performed by other ScoreCards.

Performance Metrics Report

public abstract void LayoutMetricsReport(
    IMetricsReportHost reportHost)

WealthLab calls this method when it needs to construct a Performance Metrics report, such as the report displayed by the Metrics Report Performance Visualizer. Use the supplied IMetricsReportHost to define the organization and presentation of your Metrics. The methods of IMetricsReportHost allow you to add headers, Metrics, separators, and other report elements. For example, the Basic ScoreCard begins its report with:

reportHost.AddHeader("Summary");

reportHost.AddMetricDouble(
    "Profit",
    true,
    false);

reportHost.AddMetricDouble(
    "ProfitPct",
    true,
    true);

reportHost.AddMetricDouble(
    "ProfitPerBar",
    true,
    false);

reportHost.AddMetricDouble(
    "APR",
    true,
    true,
    2,
    "APR");

reportHost.AddMetricDouble(
    "Exposure",
    false,
    true);

reportHost.AddMetricDouble(
    "Alpha",
    false,
    false,
    2,
    "Alpha (α)");

reportHost.AddMetricDouble(
    "Beta",
    false,
    false,
    2,
    "Beta (β)");

reportHost.AddMetricDouble(
    "SharpeRatio",
    false,
    false);

reportHost.AddMetricDouble(
    "SortinoRatio",
    false,
    false);

reportHost.AddMetricDouble(
    "WLScore",
    false,
    false,
    2,
    "WL Score");

reportHost.AddSeparator();

The first argument identifies the Metric stored in Backtester.Metrics. Where supported, you can also supply a more descriptive label for display. This allows the internal Metric name to remain a valid .NET property name while the report displays a friendlier name. For example:

reportHost.AddMetricDouble(
    "Alpha",
    false,
    false,
    2,
    "Alpha (α)");

The internal Metric remains "Alpha", while the report displays "Alpha (α)".

Metric Tooltips

public override string GetMetricTip(
    string itemName)

Override this method to provide explanatory text for a Performance Metric. When the user selects a Metric in the Metrics Report, WealthLab calls GetMetricTip with its internal Metric name. Return a description of the Metric, or return null if no tooltip is required. For example:

public override string GetMetricTip(
    string itemName)
{
    if (itemName == "MyMetric")
    {
        return
            "Describes how MyMetric is calculated.";
    }

    return null;
}

Metrics in Optimizations

ScoreCard Metrics can be exposed to the Optimization system, allowing Optimizers and Optimization Visualizers to use them when evaluating Strategy results.

Metric Direction

public virtual int GetMetricValueDirection(
    string itemName)

Return a value indicating whether larger or smaller values of the specified Metric are generally considered better. Return:

1   Higher values are better
-1  Lower values are better

The default implementation returns 1. Metrics where higher values are typically preferable include:

• Net Profit
• APR
• Sharpe Ratio

Metrics where lower values might be preferable include:

• Beta
• Margin Interest

Override this method for Metrics where lower values are considered better. For example:

public override int GetMetricValueDirection(
    string itemName)
{
    if (itemName == "MyDrawdown")
        return -1;

    return 1;
}

Optimization components can use this information when determining how to rank or evaluate results.

Optimizable Metrics

public virtual List<string> OptimizableMetricNames

Returns the Performance Metrics from this ScoreCard that should be available to Optimizers. The default implementation examines the calculated Metrics and includes those whose values are numeric types such as int or double. Override this property if you need more precise control over which Metrics can be selected for optimization. For example:

public override List<string>
    OptimizableMetricNames =>
    new List<string>
    {
        "MyMetric",
        "MyRatio"
    };

A Metric can therefore be available for display in Performance Visualizers without necessarily being exposed as an optimization target.

Default Optimization Metric

public abstract string DefaultMetricName

Return the name of the Performance Metric that should be selected by default when this ScoreCard is used in an optimization context. The returned value should correspond to one of the ScoreCard's optimizable Metric names. For example:

public override string DefaultMetricName =>
    "MyMetric";

Choose a Metric that provides a useful general measure of Strategy performance for your ScoreCard.