autory convert results

The autory convert results command reads Autory run output from one or more results folders and rewrites it into a format that is easier to consume elsewhere, typically CSV, SQLite, or JSON.

See the CLI reference for the full list of options. This page explains the data flow and the reasoning behind the most important options.

Example

Given an example like this (note: PowerShell uses ` for line continuation, cmd.exe uses ^):

autory convert results `
  --in path/to/results `
  --projection-node-filter "hLevel=1" `
  --time-step-filter "OR(t=1,t=12)" `
  --include-names "Premium,Reserve,Date" `
  --table-orientation long `
  --out out_dir `
  --split-by valnType `
  --output-format csv

You can think about the command in this order:

1. Which projection nodes? --projection-node-filter "hLevel=1" keeps only level-1 projection nodes.
2. Which time steps? --time-step-filter "OR(t=1,t=12)" keeps only selected rows from the time-vector output.
3. Which names? --include-names "Premium,Reserve,Date" keeps only those variables and properties in the output schema.
4. Which table shape? --table-orientation long chooses long output instead of the default wide output.
5. One output or many? --split-by valnType creates one output group per valuation type.
6. Which format? --output-format csv chooses CSV output.

What the command reads

The command starts by scanning one or more results directories given via --in. It looks for projection nodes with .feather output files and then reads:

• projection node properties such as valnType, valnDate, and hPath
• scalar results
• time-vector results

Internally, each projection node is treated as a pair of tables:

• one scalar table, usually containing one row per projection node or per iteration
• one time-vector table, containing one row per time step

The conversion pipeline

At a high level, autory convert results does this:

1. Find projection nodes with results.
2. Filter projection nodes with --projection-node-filter.
3. Filter time steps with --time-step-filter.
4. Filter included names with --include-names and --exclude-names.
5. Combine projection node properties, scalars, and time vectors into output rows.
6. Optionally split those rows into multiple files or tables with --split-by.
7. Encode and write the result in the requested format.

Aggregated versus per-iteration results

By default, the command reads aggregated results:

autory convert results --in path/to/results --use-aggregated ...

In this mode, each projection node contributes:

• one set of scalar values
• one time-vector table over t

If you use --use-iterations, the command instead reads per-iteration results. In that case, the command first detects the available iteration points from the loop_* columns, then processes each iteration separately.

This matters because:

• loop_* columns are always preserved for iteration output
• scalars and time-vectors must agree on the same iteration space
• one projection node can produce many output groups instead of one

How rows are built

Conceptually, the command combines:

• projection node properties
• scalar values
• one time-vector row at a time

There are two output styles.

Wide format

In wide format, names become columns whenever possible:

hPath	valnType	t	Premium	Reserve
Example	summary	1	100	90
Example	summary	2	120	95

This is the default because it is convenient for spreadsheets, SQL tools, and ad hoc analysis.

Long format

In long format, values are normalized into name and value columns:

hPath	valnType	t	name	value
Example	summary	1	Premium	100
Example	summary	1	Reserve	90
Example	summary	2	Premium	120

This is often better when:

• you need a schema that does not change as variable names change
• you want to aggregate many variables uniformly in downstream tooling
• you want fewer dynamically-created columns

Mixed wide/long output

The command also supports hybrid output:

• --table-wide-names forces selected names to keep their own columns in long mode
• --table-long-names forces selected names into name/value columns in wide mode

This is useful when metadata like Date, valnType, or hPath should have their own columns, while the rest of the data are stored in name/value columns.

Example:

autory convert results --in results --output-format csv --out out_dir --table-orientation long --table-wide-names "Date,hPath"

How filtering works

There are three distinct filtering stages, and they do different jobs.

Projection node filtering

--projection-node-filter decides which projection nodes are read at all.

Example:

autory convert results --in results --projection-node-filter "hLevel=1"

Use this when you want to restrict the output to specific projection nodes, for example by hierarchy node, valuation type, or valuation date.

Time-step filtering

--time-step-filter decides which time steps to use.

Example:

autory convert results --in results --time-step-filter "OR(t=1,t=12)"

Use this when you want a subset of t, Date, or other time-dependent values.

Name filtering

--include-names and --exclude-names decide which variables and properties are present in the output schema.

Example:

autory convert results --in results --include-names "Premium,Reserve,Date" --exclude-names "Reserve"

Important behavior:

• t is always included
• when using iteration output, loop_* columns are always included
• include/exclude rules affect variables and properties, not projection nodes

How splitting works

After rows have been created, --split-by groups them by one or more column values.

Examples:

autory convert results --in results --out out.sqlite --output-format sqlite --split-by valnType
autory convert results --in results --out out_dir --output-format csv --split-by valnType,valnDate

Grouping happens before writing:

• for SQLite, each group becomes a table
• for CSV and JSON, each group becomes a file

--name-pattern controls how those group names are turned into table names or file names.

Example:

--split-by valnType,valnDate --name-pattern "{valnType}_{valnDate}"

If there are two valuation types, Summary and Detail, and two valuation dates, 2026/01/31 and 2026/02/28, the resulting names in this example will be:

• Summary_20260131
• Summary_20260228
• Detail_20260131
• Detail_20260228

Output formats

CSV

CSV is best when:

• you want human-readable export files
• downstream users work in Excel or Power BI
• one file per split group is acceptable

SQLite

SQLite is best when:

• you want one database file with many tables
• downstream consumers want SQL queries
• you want append/overwrite control for tables and rows

autory_results_json

This format is different from the tabular outputs. Instead of flattening everything into a table, it keeps each projection node as a JSON object containing:

• projection node properties
• scalar values
• a results array for time-vector rows

Use this when preserving the projection-node structure matters more than producing rectangular tables.

Example:

autory convert results --in results --output-format autory_results_json --out converted.json