Configuration File

The .pd4castrrc.json file is the central configuration for your model project. It lives at the root of your model directory and defines everything the platform needs to know about your model: its identity, inputs, outputs, sensitivities, and scheduling behaviour. The CLI validates this file against a schema on every command.

File Location and Format

The configuration file must be named .pd4castrrc.json and placed at the root of your model project. It uses standard JSON format. You can generate a starter config by running pd4castr init, which scaffolds a new project from a template.

You can point the CLI to a different config file using the -c or --config flag on any command:

pd4castr test -c .pd4castrrc.variant.json

Complete Field Reference

Top-Level Fields

These fields define your model’s identity and global behaviour.

The platform UI recognises several well-known keys in metadata when present: resolution is used to build the model’s display name; features and feature_importances (aligned arrays of strings and numbers) power the feature importances panel; loss_function is shown as a training metadata attribute alongside author, version, and training_period; links adds labelled URLs (see Model links). Any other keys are preserved verbatim and visible in the Raw training metadata section.

Model links

metadata.links is a list of labelled URLs shown in the Model Info dialog and at the top of the model details card on the model info page. Each entry needs a label and a url, and both must be non-empty; entries that aren’t are skipped.

{
  "metadata": {
    "links": [
      {
        "label": "Retrospective reports",
        "url": "https://pdview.com.au/blog?category=retrospective-reports&tags=week-ahead"
      }
    ]
  }
}

A model that declares no links derives one from its horizon: week-ahead and quarterly point at the blog listing for their cadence. Declaring links replaces it.

Default comparison models

defaultComparisonModels lists the models used as default comparison selections in the pd4castr UI, before a viewer picks anything. Entries are model group IDs, and each resolves to the newest revision of that group, so a selection keeps tracking the target model as its author republishes.

Find a model group ID in the $$modelGroupID field of the target model’s .pd4castrrc.json, or as modelGroupId on any model returned by GET /v1/model.

{
  "defaultComparisonModels": ["828e98b1-9916-4a85-8a20-831fb2396845"]
}

An entry is skipped when it names a group on a different time horizon, a group you cannot see, or your own model’s group. Omit the field, or set it to [], for no default selections.

The value is read at publish time, so a change only takes effect once you republish the model.

Inputs

The inputs array defines the data your model consumes. Each entry has the following fields:

For an input with automatic data fetching, add a fetcher block. An input with sources declares no fetcher of its own: each fetcher source declares one inside its sources entry, with the same fields.

For an input that declares sources, each entry of sources has:

See Model inputs for detailed explanations, and Input sources for inputs that declare sources.

Datasets

The datasets array defines static reference data published alongside the model. Each entry has the following fields:

See Model datasets for detailed explanations.

Outputs

The outputs array defines the schema of your model’s forecast data.

See Model outputs for detailed explanations.

Sensitivities

The sensitivities array defines alternative scenario runs. Each entry has the following fields:

See Sensitivities for detailed explanations.

Input Aggregations

The inputAggregations array defines summary views of input data displayed below the forecast chart.

See Input aggregations for detailed explanations.

Views

The views array defines custom model run views: parameterized reports that visualize a run’s output as a chart or table in the pd4castr UI. Each view runs a SQL query over the run output and supporting data.

Each entry in params supports type (string, number, or boolean), optional, control (select), options (path to an options SQL file), defaultFrom, and sample. Each entry in columns supports key, role (dimension or measure), label, unit, and format.

See Model run views for detailed explanations.

File Paths

All file paths in the configuration are relative to the project root. This includes query paths (fetcher queries, sensitivity queries, input aggregation queries, view queries, view options queries, and runDatetimeQuery) and the descriptionFile Markdown path. See SQL queries for the SQL dialect each query is written in.

Full Example

Here’s a complete .pd4castrrc.json for a day-ahead price forecast model with fetched inputs, output series, and input aggregations:

{
  "name": "Day Ahead Price Forecast",
  "forecastVariable": "price",
  "timeHorizon": "day_ahead",
  "displayTimezone": "Australia/Brisbane",
  "public": false,
  "runMode": "AUTOMATIC",
  "outputFileFormat": "json",
  "runDatetimeQuery": "queries/run-datetime.sql",
  "summary": "30-minute day-ahead electricity price forecast",
  "descriptionFile": "docs/description.md",
  "metadata": {
    "resolution": "30min"
  },
  "defaultComparisonModels": ["828e98b1-9916-4a85-8a20-831fb2396845"],
  "inputs": [
    {
      "key": "dispatch_price",
      "trigger": "WAIT_FOR_LATEST_FILE",
      "uploadFileFormat": "json",
      "targetFileFormat": "json",
      "fetcher": {
        "type": "AEMO_MMS",
        "checkInterval": 300,
        "config": {
          "checkQuery": "queries/data-fetchers/dispatch-price-check.sql",
          "fetchQuery": "queries/data-fetchers/dispatch-price-fetch.sql"
        }
      }
    },
    {
      "key": "regional_boundaries",
      "file": "test_input/regional_boundaries.csv",
      "trigger": "USE_MOST_RECENT_FILE",
      "uploadFileFormat": "csv",
      "targetFileFormat": "csv"
    }
  ],
  "datasets": [
    {
      "key": "duid_info",
      "file": "datasets/duid_info.parquet"
    }
  ],
  "outputs": [
    {
      "name": "NSW1",
      "key": "nsw1",
      "type": "float",
      "seriesKey": true,
      "colour": "#84EDDC"
    },
    {
      "name": "QLD1",
      "key": "qld1",
      "type": "float",
      "seriesKey": true,
      "colour": "#FD4E4E"
    },
    {
      "name": "SA1",
      "key": "sa1",
      "type": "float",
      "seriesKey": true,
      "colour": "#FED600"
    },
    {
      "name": "TAS1",
      "key": "tas1",
      "type": "float",
      "seriesKey": true,
      "colour": "#40A967"
    },
    {
      "name": "VIC1",
      "key": "vic1",
      "type": "float",
      "seriesKey": true,
      "colour": "#1965C6"
    }
  ],
  "sensitivities": [
    {
      "name": "High Demand (+10%)",
      "key": "high-demand",
      "query": "queries/sensitivities/high-demand.sql"
    }
  ],
  "inputAggregations": [
    {
      "name": "Native Demand",
      "key": "native-demand",
      "query": "queries/input-aggregations/native-demand.sql",
      "description": "Regional demand by demand_and_nonshedgen",
      "colours": ["#008000", "#009900", "#00B300", "#00CC00", "#00E600"]
    }
  ]
}

Next Steps

• Model inputs — Detailed guide to input configuration and data fetchers.
• Model datasets — Detailed guide to publishing static reference data alongside your model.
• Model outputs — How to define your output schema.
• Sensitivities — Scenario analysis and input aggregations.
• Testing your model — Local validation workflow.
• Publishing — How to ship your model.
• Run modes and scheduling — Automatic and on-demand triggering.