Custom Feature Types

Define new feature computation templates in YAML. Two approaches: formula language (recommended) or explicit computation steps.

---

1. Overview

FeatureTypes are defined as YAML files under .definitions/feature_types/{dimension}/. Each FeatureType can declare its computation as either a single formula string (compiled by FeatureDAG's AST compiler) or an explicit steps list (manual DAG construction).

Approach	Syntax	Best for
Formula	Single formula: string	Most features — concise, compiler-optimized
Steps	steps: list of primitives	Complex features needing manual DAG control

---

2. Formula-Based FeatureType (Recommended)

name: my_momentum
description: Rolling momentum — price change over window relative to volatility
category: momentum
version: v1.0
dimension: signal
status: stable
tags: [momentum, custom]

required_inputs:
  - close

parameters:
  fast_window:
    type: integer
    description: Fast rolling window
    required: false
    default: 10
    constraints:
      min: 2
      max: 100
  slow_window:
    type: integer
    description: Slow rolling window
    required: false
    default: 30
    constraints:
      min: 5
      max: 500

output_column: my_momentum
output_description: Normalized momentum signal

formula: (rolling_mean(close, fast_window) - rolling_mean(close, slow_window)) / rolling_std(close, slow_window)

The formula field is compiled to an IR DAG by the AST Compiler — same DAG that would be built manually with steps. Parameters are referenced with $ prefix (e.g., $fast_window) in the formula.

→ Formula Language Reference — complete function catalog

---

3. Steps-Based FeatureType (Advanced)

For cases where explicit DAG control is needed:

name: my_feature
description: What this feature computes
category: momentum
version: v1
status: stable
tags: [momentum, custom]

required_inputs:
  - close
  - volume

parameters:
  window:
    type: integer
    description: Lookback window in bars
    required: false
    default: 20
    constraints:
      min: 1
      max: 500
  decay:
    type: float
    required: false
    default: 0.94
    constraints:
      min: 0.0
      max: 1.0

output_column: my_feature_value
output_description: The computed feature value

steps:
  - primitive: WINDOW
    op: rolling_mean
    params:
      input: close
      window: $window
    output: rolling_mean_close

  - primitive: TRANSFORM
    op: sub
    params:
      a: close
      b: rolling_mean_close
    output: deviation

  - primitive: TRANSFORM
    op: div
    params:
      a: deviation
      b: rolling_mean_close

---

4. File Location

Place YAML files under .definitions/feature_types/{dimension}/:

.definitions/feature_types/
├── signal/
│   ├── ofi.yml
│   └── my_momentum.yml
├── execution/
├── quality/
├── regime/
├── stability/
└── technical/

---

5. Computation Primitives (Steps Mode)

Primitive	Purpose	Example
SOURCE	Reference an input column	Read close from source table
TRANSFORM	Stateless row-wise operation	Arithmetic, log, conditional
WINDOW	Rolling/windowed aggregation	Rolling mean, diff, lag
STATE	Persistent memory across rows	EMA, cumulative sum
EVENT	Event-triggered computation	Barrier hit, threshold crossing
SINK	Mark an output column	Final feature value

TRANSFORM Operations

op	Description	Required params
add	a + b	a, b
sub	a - b	a, b
mul	a × b	a, b
div	a ÷ b	a, b
log	Natural logarithm	input
sqrt	Square root	input
neg	Negation	a
abs	Absolute value	a
sign	Sign (-1, 0, +1)	a
clip	Clamp to [lower, upper]	a, lower, upper
conditional	If-then-else	condition, true_value, false_value

WINDOW Operations

op	Description	Required params
diff	Difference from n periods ago	input, n (default 1)
rolling_mean	Rolling average	input, window
rolling_std	Rolling standard deviation	input, window
rolling_sum	Rolling sum	input, window
rolling_min	Rolling minimum	input, window
rolling_max	Rolling maximum	input, window
rolling_corr	Rolling correlation	a, b, window
pct_change	Percentage change	input, n
lag	Shift backward by n periods	input, n

STATE Operations

op	Description	Required params
ema	Exponential moving average	input, alpha
decay_accum	Decay accumulation	input, decay
cumsum	Cumulative sum	input
rolling_zscore	Rolling z-score	input, window

---

6. Parameter Types

type	Accepted values	Constraints
integer	Whole numbers	min, max, choices
float	Decimal numbers	min, max, choices
string	Text	choices, pattern (regex)
boolean	true / false	—
column	Valid column name	—

---

7. $placeholder Resolution

Parameters in steps/params use $param_name. Resolution happens in three passes:

Pass	Rule	Example in	Example out
1. Key match	Entire param value is "$param" → replace with typed value	{"window": "$lookback"}	{"window": 20}
2. Value scan	Recurse into dict/list values	{"weights": ["$a", "$b"]}	{"weights": [0.6, 0.4]}
3. In-string	Substitute $param within a string	"spread > $threshold"	"spread > 0.05"

In formula mode, $param is resolved at compile time directly by the AST compiler.

---

8. Activating a Custom Feature

After creating the YAML, reference it in quantflow_project.yml:

feature_engine:
  features:
    - name: my_momentum_instance
      type: my_momentum             # Must match YAML file's name field
      parameters:
        fast_window: 10
        slow_window: 30
      input_entity: cdm_time_bars
      column_mapping:               # Optional: map CDM column names
        close: close_price

The FeatureDefinition model also supports:

• input_entities: dict mapping input names to CDM table columns per input
• column_mapping: dict mapping logical column names to physical CDM columns
• input_entity_overrides: per-input entity source overrides

Validate and run:

qf validate
qf run --engine feature --start-date 2026-01-01 --end-date 2026-01-31

---

→ Formula Language Reference → FeatureDAG AST Compiler