data

package
v0.9.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 5, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package data provides the core types for working with financial time-series data in pvbt. It is built around three concepts:

  • Metrics -- externally-sourced measurements such as prices, volumes, and fundamental accounting figures.
  • Data providers -- adapters that connect to external sources (databases, APIs, live feeds) and deliver metrics to the engine.
  • DataFrames -- the primary data structure for time-series data, stored in column-major layout with gonum-compatible []float64 columns.

Metrics

A Metric is a named type backed by string that identifies a single measurement. The package declares well-known metrics for each data domain:

Custom metrics can be created by converting any string to a Metric: 

custom := data.Metric("MySignal")

Economic indicators such as unemployment and CPI are not tied to a specific asset. They use the sentinel asset.EconomicIndicator in requests and DataFrames. From the DataFrame's perspective they look like any other asset; the data layout stays uniform.

Data Providers

The DataProvider interface is the base for all providers. Every provider must declare the metrics it can supply via Provides and release resources via Close.

Two specializations exist:

  • BatchProvider -- fetches historical data in bulk via Fetch. Used during backtesting where the engine requests a complete time range upfront.
  • StreamProvider -- delivers data in real-time via Subscribe. Used during live trading where the engine reacts to incoming market data.

Provider lifecycle:

  1. The caller constructs a provider (e.g. connecting to a database).
  2. The caller registers it with the engine via WithDataProvider.
  3. The engine routes DataRequest values to providers based on the metrics each provider advertises.
  4. The engine calls Close when it is finished with the provider.

AssetProvider supplies asset metadata. The engine bulk-loads all known assets at startup via Assets and uses LookupAsset as a fallback for cache misses.

The DataSource interface (defined in the universe package) decouples the universe from the engine. It exposes Fetch, FetchAt, and CurrentDate so that universe implementations can obtain data without depending on the engine type directly.

IndexProvider supplies historical index membership and weights. A provider that has access to historical index composition (e.g. S&P 500 additions and removals) implements this interface alongside BatchProvider or StreamProvider. The IndexMembers method returns both a plain asset slice and an IndexConstituent slice (which includes weight data) for the members that belonged to the index at a given point in time.

DataRequest describes a batch of data to fetch. It specifies the assets, metrics, time range, and Frequency.

Time Zones

Timestamps returned by a BatchProvider must use the same time zone as the tradecron schedule driving the backtest. Market-aware tradecron directives (@monthend, @open, etc.) produce America/New_York timestamps. If the provider returns UTC timestamps instead, the engine's time-range filtering will silently produce empty DataFrames and no trades will execute. See the tradecron package documentation for details.

DataFrame

DataFrame stores contiguous float64 data in column-major order. Each column represents a single (asset, metric) pair across all timestamps. Columns are stored contiguously so that time-series operations can work on a single uninterrupted []float64 slice. The DataFrame.Column method returns the raw slice, which is directly usable with gonum routines.

For a frame with T timestamps, A assets, and M metrics the total length of the internal data slab is T*A*M. The column for asset index a and metric index m starts at offset (a*M + m) * T and runs for T elements.

Accessors

DataFrame.Start, DataFrame.End, DataFrame.Duration, and DataFrame.Len describe the time axis. DataFrame.ColCount returns the total number of columns (assets * metrics). DataFrame.Value returns the last value for an (asset, metric) pair and DataFrame.ValueAt returns the value at a specific time. DataFrame.Column returns the full []float64 slice for a column. DataFrame.At narrows to a single timestamp and DataFrame.Last narrows to the final row. DataFrame.Copy produces a deep copy. DataFrame.Table returns a human-readable text table.

Narrowing and Filtering

DataFrame.Assets restricts the frame to a subset of assets. DataFrame.Metrics restricts to a subset of metrics. DataFrame.Between restricts to a time range. DataFrame.Drop removes rows where any column matches a sentinel value. DataFrame.Filter keeps only rows for which a predicate returns true.

Arithmetic

Element-wise operations between two DataFrames:

Scalar operations applied to every element:

Per-Column Aggregation

Each method collapses the time axis to a single row:

Cross-Asset Aggregation

These methods collapse the asset axis:

Transforms

Each method returns a new DataFrame with the transformation applied to every column:

Resampling

DataFrame.Downsample groups timestamps by the target frequency and returns a DownsampledDataFrame. Aggregation methods on the result include Last, Sum, Max, Min, Mean, First, Std, and Variance.

DataFrame.Upsample fills gaps when converting to a higher frequency and returns an UpsampledDataFrame. Fill strategies include ForwardFill, BackFill, and Interpolate.

Rolling Windows

DataFrame.Rolling returns a RollingDataFrame that applies rolling-window operations to each column:

Extensibility

DataFrame.Apply maps a function over each column, returning a new DataFrame. DataFrame.Reduce collapses each column to a single value. For direct gonum usage, call DataFrame.Column to obtain the raw []float64 slice and pass it to any gonum function.

Chaining

All operations that produce a new DataFrame return a pointer, so calls chain naturally: 

pct := df.Assets(spy).Metrics(data.MetricClose).Pct(1)

If any step encounters an error the resulting DataFrame carries the error (retrievable via DataFrame.Err) and subsequent operations short-circuit.

Annotations

Annotations are step-level key-value entries that capture intermediate computations (momentum scores, signal values, factor exposures) for debugging and analysis. They differ from justifications, which are human-readable sentences attached to transactions explaining why a trade was made.

DataFrame.Annotate pushes every non-NaN cell as a key-value annotation to an Annotator destination. Keys are formatted as "TICKER/Metric" and values are the float formatted as a string. This allows a strategy to annotate its intermediate computations with a single call: 

momentumDF.Annotate(portfolio)

The Annotator interface is intentionally narrow (a single Annotate method) to avoid a circular dependency with the portfolio package. The portfolio [Portfolio] interface satisfies it.

Frequency

The Frequency type represents data publication frequency. Constants range from Tick (sub-second) through Daily, Weekly, Monthly, Quarterly, and Yearly. Frequency is used in DataRequest, resampling, and upsampling operations.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AllMetricNames 

func AllMetricNames() []string

AllMetricNames returns the sorted list of all registered metric names.

func CompositeAsset 

func CompositeAsset(a, b asset.Asset) asset.Asset

CompositeAsset creates an asset representing a pair, with fields joined by ":". Used by Covariance for multi-asset results.

func CreateSnapshotSchema 

func CreateSnapshotSchema(db *sql.DB) error

CreateSnapshotSchema creates all tables needed by a snapshot database.

func DateKey added in v0.7.0 

func DateKey(t time.Time) int32

DateKey is the exported form of dateKey. It converts a time.Time to an integer YYYYMMDD key suitable for date-only comparisons.

func ExampleData 

func ExampleData() (*TestProvider, AssetProvider)

ExampleData returns a BatchProvider and AssetProvider pre-populated with synthetic daily data for three assets (SPY, TLT, GLD) from January through June 2024. The data is deterministic and suitable for use in testable examples and documentation.

The returned providers supply MetricClose, AdjClose, Dividend, MetricHigh, MetricLow, SplitFactor, and Volume metrics. Dividend values are zero (no dividends in the synthetic data). High and Low are derived from Close by adding/subtracting 1% of the base price. SplitFactor is always 1.0 (no splits). Volume is fixed at 1,000,000.

func IsFundamental added in v0.7.0 

func IsFundamental(metric Metric) bool

IsFundamental reports whether the given metric is sourced from the fundamentals table. Fundamental metrics are sparse (quarterly) and require forward-fill when merged with daily price data.

func NewIndexState added in v0.6.0 

func NewIndexState(snapshots []IndexSnapshotEntry, changelog []IndexChangeEntry) *indexState

NewIndexState creates an indexState from pre-sorted snapshots and changelog entries (earliest first). Used by PVDataProvider and tests.

func SlabToColumns 

func SlabToColumns(slab []float64, numCols, colLen int) [][]float64

SlabToColumns reshapes a flat column-major slab into per-column slices. Each column sub-slice has its capacity capped so that append() on one column cannot corrupt adjacent columns in the shared backing array.

Types

type Annotator 

type Annotator interface {
	Annotate(timestamp time.Time, key, value string)
}

Annotator receives key-value annotations. Portfolio satisfies this interface, allowing DataFrame.Annotate to push entries without depending on the portfolio package.

type AssetProvider 

type AssetProvider interface {
	// Assets returns all known assets.
	Assets(ctx context.Context) ([]asset.Asset, error)

	// LookupAsset resolves a single ticker to its full Asset (including
	// CompositeFigi). Returns an error if the ticker is unknown.
	LookupAsset(ctx context.Context, ticker string) (asset.Asset, error)
}

AssetProvider supplies asset metadata. The engine bulk-loads all known assets at startup and uses LookupAsset as a fallback for cache misses.

type BatchProvider 

type BatchProvider interface {
	DataProvider

	// Fetch retrieves historical data for the given request. The returned
	// DataFrame contains all requested assets, metrics, and timestamps.
	Fetch(ctx context.Context, req DataRequest) (*DataFrame, error)
}

BatchProvider fetches historical data in bulk. Used during backtesting where the engine requests a complete time range upfront.

type BlockBootstrap 

type BlockBootstrap struct {
	BlockSize int // number of trading days per block
}

BlockBootstrap resamples by picking random contiguous blocks of returns across all assets simultaneously, preserving short-term autocorrelation and cross-asset correlations within blocks.

func (*BlockBootstrap) Resample 

func (bb *BlockBootstrap) Resample(returns [][]float64, targetLen int, rng *rand.Rand) [][]float64

Resample draws contiguous blocks of length BlockSize (default 20) from the historical return series and concatenates them until targetLen is reached. All assets use the same block start index at each step, preserving cross-asset correlations within each block.

type DataFrame 

type DataFrame struct {
	// contains filtered or unexported fields
}

DataFrame stores float64 data with one []float64 slice per (Asset, Metric) column. Each column holds T values in chronological order. The column for asset index a and metric index m is at columns[a*M + m].

View operations (Between, Window, Metrics, Assets) create new DataFrames that share the underlying column slices by reference, avoiding data copies. Three-index slice expressions cap view capacity to prevent AppendRow aliasing.

func MergeColumns 

func MergeColumns(frames ...*DataFrame) (*DataFrame, error)

MergeColumns combines DataFrames with the same timestamps but different metrics or assets. Used for multi-provider routing.

func MergeTimes 

func MergeTimes(frames ...*DataFrame) (*DataFrame, error)

MergeTimes combines DataFrames with the same assets and metrics but different, non-overlapping time ranges. Timestamps must not overlap.

func NewDataFrame 

func NewDataFrame(times []time.Time, assets []asset.Asset, metrics []Metric, freq Frequency, columns [][]float64) (*DataFrame, error)

NewDataFrame constructs a DataFrame from the given dimensions and columns. columns must have length len(assets)*len(metrics), and each column must have length len(times).

func WithErr 

func WithErr(err error) *DataFrame

WithErr returns a zero-value DataFrame carrying the given error. All accessor methods (Len, AssetList, etc.) return safe defaults on this form. Exported so that packages like signal can create error DataFrames.

func (*DataFrame) Add 

func (df *DataFrame) Add(other *DataFrame, metrics ...Metric) *DataFrame

Add returns a new DataFrame with element-wise addition of two DataFrames aligned by asset and metric. If metrics are provided, each named metric column from other is broadcast across all columns of df.

func (*DataFrame) AddScalar 

func (df *DataFrame) AddScalar(scalar float64) *DataFrame

AddScalar adds a constant to every value in the DataFrame.

func (*DataFrame) Annotate 

func (df *DataFrame) Annotate(dest Annotator) *DataFrame

Annotate pushes every non-NaN cell in the DataFrame as a key-value annotation to the destination. Keys are formatted as "TICKER/Metric". Values are the float formatted with strconv.FormatFloat(v, 'f', -1, 64). Returns the DataFrame for chaining. If the DataFrame has an error, this is a no-op.

func (*DataFrame) AppendRow 

func (df *DataFrame) AppendRow(timestamp time.Time, values []float64) error

AppendRow appends a single timestamp and its column values to the DataFrame in place. The values slice must have length len(assets) * len(metrics), ordered as [asset0_metric0, asset0_metric1, ..., asset1_metric0, ...] (matching column-major layout). Returns an error if the timestamp is not after the current End() or if the values length is wrong.

AppendRow is the only DataFrame method that mutates in place. This is safe because all read methods produce independent copies via make+copy.

func (*DataFrame) Apply 

func (df *DataFrame) Apply(transform func([]float64) []float64) *DataFrame

Apply runs fn on each column and returns a new DataFrame with the transformed values. The function receives a contiguous []float64 column and must return a slice of the same length.

func (*DataFrame) AssetList 

func (df *DataFrame) AssetList() []asset.Asset

AssetList returns a copy of the asset list.

func (*DataFrame) Assets 

func (df *DataFrame) Assets(assets ...asset.Asset) *DataFrame

Assets returns a new DataFrame containing only the specified assets. Duplicate assets are silently deduplicated; each asset appears at most once.

func (*DataFrame) At 

func (df *DataFrame) At(t time.Time) *DataFrame

At returns a single-row DataFrame containing all assets and metrics at the given timestamp.

func (*DataFrame) Between 

func (df *DataFrame) Between(start, end time.Time) *DataFrame

Between returns a new DataFrame containing only timestamps within the inclusive range [start, end]. For daily-or-coarser data the comparison uses calendar dates only, ignoring the time-of-day component.

func (*DataFrame) ColCount 

func (df *DataFrame) ColCount() int

ColCount returns the number of columns (assets * metrics).

func (*DataFrame) Column 

func (df *DataFrame) Column(a asset.Asset, metric Metric) []float64

Column returns the contiguous []float64 slice for the given asset and metric. The returned slice shares the underlying Data array and is directly compatible with gonum.

func (*DataFrame) Copy 

func (df *DataFrame) Copy() *DataFrame

Copy returns a deep copy of the DataFrame. The underlying Data slab is duplicated so modifications to the copy do not affect the original.

func (*DataFrame) Correlation 

func (df *DataFrame) Correlation(assets ...asset.Asset) *DataFrame

Correlation computes Pearson correlation between columns.

  • 1 asset: cross-metric correlation. Returns composite metric keys.
  • 2+ assets: per-metric correlation for all unique pairs. Returns composite asset keys.

func (*DataFrame) CountWhere 

func (df *DataFrame) CountWhere(metric Metric, predicate func(float64) bool) *DataFrame

CountWhere returns a new single-asset DataFrame with one metric (Count) whose value at each timestep is the number of assets where the predicate returns true for the given metric. The synthetic asset has Ticker "COUNT".

func (*DataFrame) Covariance 

func (df *DataFrame) Covariance(assets ...asset.Asset) *DataFrame

Covariance computes sample covariance (N-1 denominator) between columns.

  • 1 asset: cross-metric covariance. Returns composite metric keys.
  • 2+ assets: per-metric covariance for all unique pairs. Returns composite asset keys.

func (*DataFrame) CumMax 

func (df *DataFrame) CumMax() *DataFrame

CumMax returns the running maximum along the time axis for each column.

func (*DataFrame) CumSum 

func (df *DataFrame) CumSum() *DataFrame

CumSum returns the cumulative sum along the time axis for each column.

func (*DataFrame) Diff 

func (df *DataFrame) Diff() *DataFrame

Diff returns the first difference between consecutive values.

func (*DataFrame) Div 

func (df *DataFrame) Div(other *DataFrame, metrics ...Metric) *DataFrame

Div returns a new DataFrame with element-wise division. If metrics are provided, each named metric column from other is broadcast across all columns of df.

func (*DataFrame) DivScalar 

func (df *DataFrame) DivScalar(scalar float64) *DataFrame

DivScalar divides every value in the DataFrame by a constant.

func (*DataFrame) Downsample 

func (df *DataFrame) Downsample(freq Frequency) *DownsampledDataFrame

Downsample returns a DownsampledDataFrame that aggregates values when converting to a lower frequency.

func (*DataFrame) Drop 

func (df *DataFrame) Drop(val float64) *DataFrame

Drop removes all timestamps where any value equals val (e.g. NaN).

func (*DataFrame) Duration 

func (df *DataFrame) Duration() time.Duration

Duration returns the time span from the first to the last timestamp.

func (*DataFrame) End 

func (df *DataFrame) End() time.Time

End returns the latest timestamp in the frame. Returns the zero time if the frame is empty.

func (*DataFrame) Err 

func (df *DataFrame) Err() error

Err returns the first error encountered during chained operations.

func (*DataFrame) Filter 

func (df *DataFrame) Filter(predicate func(t time.Time, row *DataFrame) bool) *DataFrame

Filter returns a new DataFrame keeping only the timestamps for which fn returns true. The function receives the timestamp and a single-row DataFrame with all assets and metrics at that point.

func (*DataFrame) Frequency 

func (df *DataFrame) Frequency() Frequency

Frequency returns the data resolution of this DataFrame.

func (*DataFrame) IdxMaxAcrossAssets 

func (df *DataFrame) IdxMaxAcrossAssets() []asset.Asset

IdxMaxAcrossAssets returns, for each timestamp, the asset that holds the maximum value for the first metric across all assets.

func (*DataFrame) Insert 

func (df *DataFrame) Insert(targetAsset asset.Asset, metric Metric, values []float64) error

Insert adds or overwrites a column in the DataFrame for the given asset and metric. The length of values must equal Len(). Returns an error if the values length does not match.

func (*DataFrame) Last 

func (df *DataFrame) Last() *DataFrame

Last returns a single-row DataFrame containing the most recent timestamp.

func (*DataFrame) Len 

func (df *DataFrame) Len() int

Len returns the number of timestamps.

func (*DataFrame) Log 

func (df *DataFrame) Log() *DataFrame

Log returns the natural logarithm of every value.

func (*DataFrame) Max 

func (df *DataFrame) Max() *DataFrame

Max returns a single-row DataFrame with the maximum value of each column over the time dimension.

func (*DataFrame) MaxAcrossAssets 

func (df *DataFrame) MaxAcrossAssets() *DataFrame

MaxAcrossAssets returns a new DataFrame with the maximum value across all assets for each timestamp and metric. The result has a single synthetic asset with Ticker "MAX".

func (*DataFrame) Mean 

func (df *DataFrame) Mean() *DataFrame

Mean returns a single-row DataFrame with the arithmetic mean of each column over the time dimension.

func (*DataFrame) MetricList 

func (df *DataFrame) MetricList() []Metric

MetricList returns a copy of the metric list.

func (*DataFrame) Metrics 

func (df *DataFrame) Metrics(metrics ...Metric) *DataFrame

Metrics returns a new DataFrame containing only the specified metrics.

func (*DataFrame) Min 

func (df *DataFrame) Min() *DataFrame

Min returns a single-row DataFrame with the minimum value of each column over the time dimension.

func (*DataFrame) MinAcrossAssets 

func (df *DataFrame) MinAcrossAssets() *DataFrame

MinAcrossAssets returns a new DataFrame with the minimum value across all assets for each timestamp and metric. The result has a single synthetic asset with Ticker "MIN".

func (*DataFrame) Mul 

func (df *DataFrame) Mul(other *DataFrame, metrics ...Metric) *DataFrame

Mul returns a new DataFrame with element-wise multiplication. If metrics are provided, each named metric column from other is broadcast across all columns of df.

func (*DataFrame) MulScalar 

func (df *DataFrame) MulScalar(scalar float64) *DataFrame

MulScalar multiplies every value in the DataFrame by a constant.

func (*DataFrame) Pct 

func (df *DataFrame) Pct(periods ...int) *DataFrame

Pct returns the percent change over n periods. If n is omitted it defaults to 1.

func (*DataFrame) Reduce 

func (df *DataFrame) Reduce(reducer func([]float64) float64) *DataFrame

Reduce runs fn on each column, collapsing it to a single value. The result is a single-row DataFrame with the same assets and metrics.

func (*DataFrame) RenameMetric 

func (df *DataFrame) RenameMetric(old, new Metric) *DataFrame

RenameMetric returns a new DataFrame with metric old replaced by new. Returns a DataFrame with Err set if old is not found or new already exists.

func (*DataFrame) RiskAdjustedPct 

func (df *DataFrame) RiskAdjustedPct(periods ...int) *DataFrame

RiskAdjustedPct returns the risk-adjusted percent change over n periods. It subtracts the risk-free return over the same period from each column's percent change. If no risk-free rates are attached, sets an error on the returned DataFrame. Default period is 1.

func (*DataFrame) RiskFreeRates 

func (df *DataFrame) RiskFreeRates() []float64

RiskFreeRates returns the attached cumulative risk-free rate values, or nil if none have been set.

func (*DataFrame) Rolling 

func (df *DataFrame) Rolling(n int) *RollingDataFrame

Rolling returns a RollingDataFrame that applies rolling-window operations with a window of n periods.

func (*DataFrame) SetRiskFreeRates 

func (df *DataFrame) SetRiskFreeRates(rates []float64) error

SetRiskFreeRates attaches raw annualized risk-free yields to the DataFrame. Returns an error if len(rates) != df.Len().

func (*DataFrame) SetSource 

func (df *DataFrame) SetSource(ds DataSource)

SetSource sets the DataSource on this DataFrame.

func (*DataFrame) Shift 

func (df *DataFrame) Shift(positions int) *DataFrame

Shift shifts every column forward by n periods, filling leading values with NaN. Negative n shifts backward.

func (*DataFrame) Source 

func (df *DataFrame) Source() DataSource

Source returns the DataSource that populated this DataFrame, or nil.

func (*DataFrame) Start 

func (df *DataFrame) Start() time.Time

Start returns the earliest timestamp in the frame. Returns the zero time if the frame is empty.

func (*DataFrame) Std 

func (df *DataFrame) Std() *DataFrame

Std returns a single-row DataFrame with the sample standard deviation (N-1 denominator) of each column over the time dimension.

func (*DataFrame) Sub 

func (df *DataFrame) Sub(other *DataFrame, metrics ...Metric) *DataFrame

Sub returns a new DataFrame with element-wise subtraction. If metrics are provided, each named metric column from other is broadcast across all columns of df.

func (*DataFrame) SubScalar 

func (df *DataFrame) SubScalar(scalar float64) *DataFrame

SubScalar subtracts a constant from every value in the DataFrame.

func (*DataFrame) Sum 

func (df *DataFrame) Sum() *DataFrame

Sum returns a single-row DataFrame with the sum of each column over the time dimension.

func (*DataFrame) Table 

func (df *DataFrame) Table() string

Table returns an ASCII table representation of the DataFrame for debugging and interactive use.

func (*DataFrame) Times 

func (df *DataFrame) Times() []time.Time

Times returns a copy of the timestamp axis.

func (*DataFrame) Upsample 

func (df *DataFrame) Upsample(freq Frequency) *UpsampledDataFrame

Upsample returns an UpsampledDataFrame that fills gaps when converting to a higher frequency.

func (*DataFrame) Value 

func (df *DataFrame) Value(a asset.Asset, metric Metric) float64

Value returns the most recent float64 for the given asset and metric.

func (*DataFrame) ValueAt 

func (df *DataFrame) ValueAt(a asset.Asset, metric Metric, timestamp time.Time) float64

ValueAt returns the float64 for the given asset, metric, and timestamp.

func (*DataFrame) Variance 

func (df *DataFrame) Variance() *DataFrame

Variance returns a single-row DataFrame with the sample variance (N-1 denominator) of each column over the time dimension.

func (*DataFrame) Window 

func (df *DataFrame) Window(period *Period) *DataFrame

Window returns a DataFrame containing only timestamps within the trailing window defined by p. When p is nil, returns the full DataFrame. When the window exceeds the available data, returns the full DataFrame.

type DataPoint 

type DataPoint struct {
	Time   time.Time
	Asset  asset.Asset
	Metric Metric
	Value  float64
}

DataPoint is a single timestamped value delivered by a StreamProvider.

type DataProvider 

type DataProvider interface {
	// Provides returns the set of metrics this provider can supply.
	Provides() []Metric

	// Close releases any resources held by the provider (database
	// connections, open files, etc.). The engine calls Close when it
	// is finished with the provider.
	Close() error
}

DataProvider is the base interface for all data providers. A provider supplies externally-sourced metrics (e.g. price data from a database, economic indicators from an API). Providers are constructed by the caller and registered with the engine via WithDataProvider.

type DataRequest 

type DataRequest struct {
	Assets    []asset.Asset
	Metrics   []Metric
	Start     time.Time
	End       time.Time
	Frequency Frequency
}

DataRequest describes a batch of data to fetch.

type DataSource 

type DataSource interface {
	// Fetch returns a DataFrame covering [currentDate - lookback, currentDate]
	// for the given assets and metrics.
	Fetch(ctx context.Context, assets []asset.Asset, lookback Period,
		metrics []Metric) (*DataFrame, error)

	// FetchAt returns a single-row DataFrame at the given time for the given
	// assets and metrics.
	FetchAt(ctx context.Context, assets []asset.Asset, t time.Time,
		metrics []Metric) (*DataFrame, error)

	// CurrentDate returns the current simulation date.
	CurrentDate() time.Time
}

DataSource provides data fetching capabilities. The engine implements this interface; DataFrames hold a reference to it so downstream consumers (such as weighting functions) can fetch additional data on demand.

type DownsampledDataFrame 

type DownsampledDataFrame struct {
	// contains filtered or unexported fields
}

DownsampledDataFrame groups timestamps by the target frequency and aggregates values within each period. Created by DataFrame.Downsample(freq).

func (*DownsampledDataFrame) First 

func (d *DownsampledDataFrame) First() *DataFrame

First returns a DataFrame with the first value of each group.

func (*DownsampledDataFrame) Last 

func (d *DownsampledDataFrame) Last() *DataFrame

Last returns a DataFrame with the last value of each group.

func (*DownsampledDataFrame) Max 

func (d *DownsampledDataFrame) Max() *DataFrame

Max returns a DataFrame with the maximum value of each group.

func (*DownsampledDataFrame) Mean 

func (d *DownsampledDataFrame) Mean() *DataFrame

Mean returns a DataFrame with the mean of each group.

func (*DownsampledDataFrame) Min 

func (d *DownsampledDataFrame) Min() *DataFrame

Min returns a DataFrame with the minimum value of each group.

func (*DownsampledDataFrame) Std 

func (d *DownsampledDataFrame) Std() *DataFrame

Std returns a DataFrame with the sample standard deviation (N-1 denominator) of each group.

func (*DownsampledDataFrame) Sum 

func (d *DownsampledDataFrame) Sum() *DataFrame

Sum returns a DataFrame with the sum of each group.

func (*DownsampledDataFrame) Variance 

func (d *DownsampledDataFrame) Variance() *DataFrame

Variance returns a DataFrame with the sample variance (N-1 denominator) of each group.

type Frequency 

type Frequency int

Frequency represents data publication frequency. 

const (
	Tick Frequency = iota
	Daily
	Weekly
	Monthly
	Quarterly
	Yearly
)

func ParseFrequency 

func ParseFrequency(freqStr string) (Frequency, error)

ParseFrequency converts a string back to a Frequency constant.

func (Frequency) PeriodsPerYear 

func (f Frequency) PeriodsPerYear() float64

PeriodsPerYear returns the approximate number of periods per year for this frequency. Used to convert annualized rates to per-period rates.

func (Frequency) String 

func (f Frequency) String() string

type FundamentalsByDateKeyProvider added in v0.7.2 

type FundamentalsByDateKeyProvider interface {
	// FetchFundamentalsByDateKey returns one row per asset for the given
	// date_key + dimension. Only filings with event_date <= maxEventDate
	// are included (point-in-time correctness). For dimensions where a
	// single (figi, date_key) can have multiple filings (MR restatements),
	// the row with the maximum event_date wins.
	//
	// metrics must contain only fundamental metrics. Metadata metrics
	// (FundamentalsDateKey, FundamentalsReportPeriod) populate from the
	// row's date_key/report_period columns.
	FetchFundamentalsByDateKey(
		ctx context.Context,
		assets []asset.Asset,
		metrics []Metric,
		dateKey time.Time,
		dimension string,
		maxEventDate time.Time,
	) (*DataFrame, error)
}

FundamentalsByDateKeyProvider is implemented by providers that can return fundamentals filtered to a specific reporting period (date_key). The engine type-asserts on this interface from FetchFundamentalsByDateKey.

type HolidayProvider 

type HolidayProvider interface {
	FetchMarketHolidays(ctx context.Context) ([]tradecron.MarketHoliday, error)
}

HolidayProvider supplies market holiday data. Providers that have access to a holiday calendar (database, snapshot file) implement this so the engine can initialize tradecron automatically during Backtest.

type IndexChangeEntry added in v0.6.0 

type IndexChangeEntry struct {
	Date   time.Time
	Asset  asset.Asset
	Action string
	Weight float64
}

IndexChangeEntry is a changelog event used to construct an indexState. Asset must carry full metadata (Sector, Industry, Name, etc.); the engine surfaces this asset directly to strategies via IndexUniverse.Assets().

type IndexConstituent added in v0.6.0 

type IndexConstituent struct {
	Asset  asset.Asset
	Weight float64
}

IndexConstituent is an asset with its weight in an index at a point in time.

type IndexProvider 

type IndexProvider interface {
	IndexMembers(ctx context.Context, index string, t time.Time) ([]asset.Asset, []IndexConstituent, error)
}

IndexProvider supplies index membership data. A provider that has access to historical index composition (e.g. S&P 500 additions and removals) implements this interface alongside BatchProvider or StreamProvider.

type IndexSnapshotEntry added in v0.6.0 

type IndexSnapshotEntry struct {
	Date    time.Time
	Members []IndexConstituent
}

IndexSnapshotEntry is a snapshot used to construct an indexState.

type Metric 

type Metric string

Metric identifies an externally-sourced measurement about an asset or the economy. 

const (
	// MetricOpen is the opening price for the trading day.
	MetricOpen Metric = "Open"
	// MetricHigh is the highest price reached during the trading day.
	MetricHigh Metric = "High"
	// MetricLow is the lowest price reached during the trading day.
	MetricLow Metric = "Low"
	// MetricClose is the closing price for the trading day.
	MetricClose Metric = "Close"
	// AdjClose is the closing price adjusted for splits and dividends.
	AdjClose Metric = "AdjClose"
	// Volume is the number of shares traded during the trading day.
	Volume Metric = "Volume"
	// Dividend is the per-share cash dividend paid on the ex-date.
	Dividend Metric = "Dividend"
	// SplitFactor is the ratio applied to shares on the split effective date (e.g. 2.0 for a 2-for-1 split).
	SplitFactor Metric = "SplitFactor"
)

End-of-day price metrics (eod table). 

const (
	// Price is the last-traded price from a live/streaming feed.
	Price Metric = "Price"
	// Bid is the highest current bid price from a live/streaming feed.
	Bid Metric = "Bid"
	// Ask is the lowest current ask price from a live/streaming feed.
	Ask Metric = "Ask"
)

Live/streaming price metrics. 

const (
	// MarketCap is the total market capitalization (share price times shares outstanding).
	MarketCap Metric = "MarketCap"
	// EnterpriseValue is market cap plus debt minus cash, representing the total value of the business.
	EnterpriseValue Metric = "EnterpriseValue"
	// PE is the trailing price-to-earnings ratio (price divided by trailing-twelve-month EPS).
	PE Metric = "PE"
	// ForwardPE is the forward price-to-earnings ratio (price divided by consensus forward EPS estimate).
	ForwardPE Metric = "ForwardPE"
	// PEG is the price/earnings-to-growth ratio (PE divided by expected earnings growth rate).
	PEG Metric = "PEG"
	// PB is the price-to-book ratio (price divided by book value per share).
	PB Metric = "PB"
	// PS is the price-to-sales ratio (price divided by revenue per share).
	PS Metric = "PS"
	// PriceToCashFlow is the price-to-cash-flow ratio (price divided by operating cash flow per share).
	PriceToCashFlow Metric = "PriceToCashFlow"
	// EVtoEBIT is the enterprise-value-to-EBIT ratio.
	EVtoEBIT Metric = "EVtoEBIT"
	// EVtoEBITDA is the enterprise-value-to-EBITDA ratio.
	EVtoEBITDA Metric = "EVtoEBITDA"
	// Beta measures the asset's sensitivity to market movements (slope of returns vs. market returns).
	Beta Metric = "Beta"
)

Valuation metrics (metrics table). 

const (
	// Revenue is total top-line sales for the period.
	Revenue Metric = "Revenue"
	// CostOfRevenue is the direct costs attributable to producing goods or services sold.
	CostOfRevenue Metric = "CostOfRevenue"
	// GrossProfit is revenue minus cost of revenue.
	GrossProfit Metric = "GrossProfit"
	// OperatingExpenses is total operating costs excluding cost of revenue (includes SGA, R&D, etc.).
	OperatingExpenses Metric = "OperatingExpenses"
	// OperatingIncome is gross profit minus operating expenses.
	OperatingIncome Metric = "OperatingIncome"
	// EBIT is earnings before interest and taxes.
	EBIT Metric = "EBIT"
	// EBITDA is earnings before interest, taxes, depreciation, and amortization.
	EBITDA Metric = "EBITDA"
	// EBT is earnings before taxes (net income before income tax provision).
	EBT Metric = "EBT"
	// ConsolidatedIncome is net income including all consolidated subsidiaries.
	ConsolidatedIncome Metric = "ConsolidatedIncome"
	// NetIncome is the bottom-line profit after all expenses, taxes, and adjustments.
	NetIncome Metric = "NetIncome"
	// NetIncomeCommonStock is net income available to common stockholders (after preferred dividends).
	NetIncomeCommonStock Metric = "NetIncomeCommonStock"
	// EarningsPerShare is basic earnings per share (net income divided by basic shares outstanding).
	EarningsPerShare Metric = "EarningsPerShare"
	// EPSDiluted is diluted earnings per share (net income divided by diluted shares outstanding).
	EPSDiluted Metric = "EPSDiluted"
	// InterestExpense is the cost of borrowed funds for the period.
	InterestExpense Metric = "InterestExpense"
	// IncomeTaxExpense is the total income tax provision for the period.
	IncomeTaxExpense Metric = "IncomeTaxExpense"
	// RandDExpenses is research and development expenditures for the period.
	RandDExpenses Metric = "RandDExpenses"
	// SGAExpense is selling, general, and administrative expenses for the period.
	SGAExpense Metric = "SGAExpense"
	// ShareBasedCompensation is the non-cash expense recognized for equity-based employee compensation.
	ShareBasedCompensation Metric = "ShareBasedCompensation"
	// DividendsPerShare is the total dividends declared per basic common share.
	DividendsPerShare Metric = "DividendsPerShare"

	// NetLossIncomeDiscontinuedOperations is the gain or loss from discontinued business segments.
	NetLossIncomeDiscontinuedOperations Metric = "NetLossIncomeDiscontinuedOperations"
	// NetIncomeToNonControllingInterests is the portion of net income allocated to minority/non-controlling interests.
	NetIncomeToNonControllingInterests Metric = "NetIncomeToNonControllingInterests"
	// PreferredDividendsImpact is the income statement impact of preferred stock dividends.
	PreferredDividendsImpact Metric = "PreferredDividendsImpact"
)

Income statement metrics (fundamentals table). 

const (
	// TotalAssets is the sum of all current and non-current assets.
	TotalAssets Metric = "TotalAssets"
	// CurrentAssets is the total assets expected to be converted to cash within one year.
	CurrentAssets Metric = "CurrentAssets"
	// AssetsNonCurrent is the total long-term assets not expected to be converted to cash within one year.
	AssetsNonCurrent Metric = "AssetsNonCurrent"
	// AverageAssets is the average of beginning and ending total assets for the period.
	AverageAssets Metric = "AverageAssets"

	// CashAndEquivalents is cash on hand plus short-term highly liquid investments.
	CashAndEquivalents Metric = "CashAndEquivalents"
	// Inventory is the value of raw materials, work-in-progress, and finished goods held for sale.
	Inventory Metric = "Inventory"
	// Receivables is amounts owed by customers for goods or services delivered.
	Receivables Metric = "Receivables"
	// Investments is the total value of investment securities (current and non-current combined).
	Investments Metric = "Investments"
	// InvestmentsCurrent is the value of investment securities maturing within one year.
	InvestmentsCurrent Metric = "InvestmentsCurrent"
	// InvestmentsNonCur is the value of long-term investment securities maturing beyond one year.
	InvestmentsNonCur Metric = "InvestmentsNonCurrent"
	// Intangibles is the value of non-physical assets such as goodwill, patents, and trademarks.
	Intangibles Metric = "Intangibles"
	// PPENet is property, plant, and equipment net of accumulated depreciation.
	PPENet Metric = "PPENet"
	// TaxAssets is deferred and other tax assets on the balance sheet.
	TaxAssets Metric = "TaxAssets"

	// TotalLiabilities is the sum of all current and non-current liabilities.
	TotalLiabilities Metric = "TotalLiabilities"
	// CurrentLiabilities is obligations due within one year.
	CurrentLiabilities Metric = "CurrentLiabilities"
	// LiabilitiesNonCurrent is obligations due beyond one year.
	LiabilitiesNonCurrent Metric = "LiabilitiesNonCurrent"
	// TotalDebt is the sum of all short-term and long-term borrowings.
	TotalDebt Metric = "TotalDebt"
	// DebtCurrent is borrowings due within one year.
	DebtCurrent Metric = "DebtCurrent"
	// DebtNonCurrent is borrowings due beyond one year.
	DebtNonCurrent Metric = "DebtNonCurrent"
	// Payables is amounts owed to suppliers for goods or services received.
	Payables Metric = "Payables"
	// DeferredRevenue is payments received for goods or services not yet delivered.
	DeferredRevenue Metric = "DeferredRevenue"
	// Deposits is customer or counterparty deposits held (primarily for banks and financial institutions).
	Deposits Metric = "Deposits"
	// TaxLiabilities is deferred and other tax liabilities on the balance sheet.
	TaxLiabilities Metric = "TaxLiabilities"

	// Equity is total shareholders' equity (assets minus liabilities).
	Equity Metric = "Equity"
	// EquityAvg is the average of beginning and ending shareholders' equity for the period.
	EquityAvg Metric = "EquityAvg"
	// AccumulatedOtherComprehensiveIncome is unrealized gains/losses not yet recognized in net income (e.g. foreign currency, securities).
	AccumulatedOtherComprehensiveIncome Metric = "AccumulatedOtherComprehensiveIncome"
	// AccumulatedRetainedEarningsDeficit is cumulative net income retained in the business since inception.
	AccumulatedRetainedEarningsDeficit Metric = "AccumulatedRetainedEarningsDeficit"
)

Balance sheet metrics (fundamentals table). 

const (
	// FreeCashFlow is operating cash flow minus capital expenditures.
	FreeCashFlow Metric = "FreeCashFlow"
	// NetCashFlow is the net change in cash and equivalents for the period.
	NetCashFlow Metric = "NetCashFlow"
	// NetCashFlowFromOperations is cash generated or consumed by core business operations.
	NetCashFlowFromOperations Metric = "NetCashFlowFromOperations"
	// NetCashFlowFromInvesting is cash used for or generated by investing activities (capex, acquisitions, etc.).
	NetCashFlowFromInvesting Metric = "NetCashFlowFromInvesting"
	// NetCashFlowFromFinancing is cash from or used for financing activities (debt issuance, buybacks, dividends).
	NetCashFlowFromFinancing Metric = "NetCashFlowFromFinancing"
	// NetCashFlowBusiness is cash flow from business acquisitions and disposals.
	NetCashFlowBusiness Metric = "NetCashFlowBusiness"
	// NetCashFlowCommon is cash flow from issuance or repurchase of common stock.
	NetCashFlowCommon Metric = "NetCashFlowCommon"
	// NetCashFlowDebt is cash flow from issuance or repayment of debt.
	NetCashFlowDebt Metric = "NetCashFlowDebt"
	// NetCashFlowDividend is cash paid out as dividends to shareholders.
	NetCashFlowDividend Metric = "NetCashFlowDividend"
	// NetCashFlowInvest is cash flow from purchases and sales of investment securities.
	NetCashFlowInvest Metric = "NetCashFlowInvest"
	// NetCashFlowFx is the effect of foreign exchange rate changes on cash.
	NetCashFlowFx Metric = "NetCashFlowFx"
	// CapitalExpenditure is cash spent on acquiring or maintaining fixed assets.
	CapitalExpenditure Metric = "CapitalExpenditure"
	// DepreciationAmortization is the non-cash reduction in value of tangible and intangible assets.
	DepreciationAmortization Metric = "DepreciationAmortization"
)

Cash flow metrics (fundamentals table). 

const (
	// BookValue is book value per share (total equity divided by shares outstanding).
	BookValue Metric = "BookValue"
	// FreeCashFlowPerShare is free cash flow divided by shares outstanding.
	FreeCashFlowPerShare Metric = "FreeCashFlowPerShare"
	// SalesPerShare is total revenue divided by shares outstanding.
	SalesPerShare Metric = "SalesPerShare"
	// TangibleAssetsBookValuePerShare is tangible book value (equity minus intangibles) divided by shares outstanding.
	TangibleAssetsBookValuePerShare Metric = "TangibleAssetsBookValuePerShare"
	// ShareFactor is the cumulative split-adjustment factor for the period.
	ShareFactor Metric = "ShareFactor"
	// SharesBasic is the basic (non-diluted) number of shares outstanding.
	SharesBasic Metric = "SharesBasic"
	// WeightedAverageShares is the weighted average basic shares outstanding over the period.
	WeightedAverageShares Metric = "WeightedAverageShares"
	// WeightedAverageSharesDiluted is the weighted average diluted shares outstanding over the period.
	WeightedAverageSharesDiluted Metric = "WeightedAverageSharesDiluted"
	// FundamentalPrice is the closing share price as reported in the fundamental data source.
	FundamentalPrice Metric = "FundamentalPrice"
	// PE1 is an alternative price-to-earnings calculation from the fundamental data source.
	PE1 Metric = "PE1"
	// PS1 is an alternative price-to-sales calculation from the fundamental data source.
	PS1 Metric = "PS1"
	// FxUSD is the foreign exchange rate to US dollars used in financial statement conversion.
	FxUSD Metric = "FxUSD"
)

Per-share and ratio metrics (fundamentals table). 

const (
	// GrossMargin is gross profit divided by revenue, expressed as a ratio.
	GrossMargin Metric = "GrossMargin"
	// EBITDAMargin is EBITDA divided by revenue, expressed as a ratio.
	EBITDAMargin Metric = "EBITDAMargin"
	// ProfitMargin is net income divided by revenue, expressed as a ratio.
	ProfitMargin Metric = "ProfitMargin"
	// ROA is return on assets (net income divided by average total assets).
	ROA Metric = "ROA"
	// ROE is return on equity (net income divided by average shareholders' equity).
	ROE Metric = "ROE"
	// ROIC is return on invested capital (NOPAT divided by average invested capital).
	ROIC Metric = "ROIC"
	// ReturnOnSales is operating income divided by revenue, expressed as a ratio.
	ReturnOnSales Metric = "ReturnOnSales"
	// AssetTurnover is revenue divided by average total assets.
	AssetTurnover Metric = "AssetTurnover"
	// CurrentRatio is current assets divided by current liabilities.
	CurrentRatio Metric = "CurrentRatio"
	// DebtToEquity is total debt divided by total shareholders' equity.
	DebtToEquity Metric = "DebtToEquity"
	// DividendYield is annual dividends per share divided by share price, expressed as a ratio.
	DividendYield Metric = "DividendYield"
	// PayoutRatio is dividends paid divided by net income, expressed as a ratio.
	PayoutRatio Metric = "PayoutRatio"
)

Margin and return ratios (fundamentals table). 

const (
	// InvestedCapital is total debt plus equity minus cash and equivalents.
	InvestedCapital Metric = "InvestedCapital"
	// InvestedCapitalAvg is the average of beginning and ending invested capital for the period.
	InvestedCapitalAvg Metric = "InvestedCapitalAvg"
	// TangibleAssetValue is total assets minus intangible assets and goodwill.
	TangibleAssetValue Metric = "TangibleAssetValue"
	// WorkingCapital is current assets minus current liabilities.
	WorkingCapital Metric = "WorkingCapital"
	// MarketCapFundamental is market capitalization as reported in the fundamental data source.
	MarketCapFundamental Metric = "MarketCapFundamental"
)

Invested capital metrics (fundamentals table). 

const (
	// FundamentalsDateKey is the normalized calendar quarter boundary for
	// the most recent fundamental filing as of the queried timestamp.
	// Values are encoded as float64(t.Unix()); convert with
	// time.Unix(int64(val), 0). NaN means no filing has been observed.
	FundamentalsDateKey Metric = "FundamentalsDateKey"

	// FundamentalsReportPeriod is the actual fiscal-period end date for
	// the most recent fundamental filing as of the queried timestamp.
	// Values are encoded as float64(t.Unix()); convert with
	// time.Unix(int64(val), 0). NaN means no filing has been observed.
	FundamentalsReportPeriod Metric = "FundamentalsReportPeriod"
)

Fundamentals metadata metrics (fundamentals table date columns). 

const (
	// PortfolioEquity is the total equity value of the portfolio at each time step.
	PortfolioEquity Metric = "PortfolioEquity"
	// PortfolioBenchmark is the benchmark index value used for portfolio comparison.
	PortfolioBenchmark Metric = "PortfolioBenchmark"
	// PortfolioRiskFree is the risk-free rate used for risk-adjusted return calculations.
	PortfolioRiskFree Metric = "PortfolioRiskFree"
	// PortfolioReturns is the period-over-period percentage return of portfolio equity.
	PortfolioReturns Metric = "portfolio_returns"
	// PortfolioExcessReturns is portfolio returns minus the risk-free rate.
	PortfolioExcessReturns Metric = "portfolio_excess_returns"
	// PortfolioDrawdown is the percentage decline from the running equity peak.
	PortfolioDrawdown Metric = "portfolio_drawdown"
	// PortfolioBenchReturns is the period-over-period percentage return of the benchmark.
	PortfolioBenchReturns Metric = "portfolio_bench_returns"
	// PositionMarketValue is the per-asset market value recorded daily for positions-impact tracking.
	PositionMarketValue Metric = "PositionMarketValue"
	// PositionQuantity is the per-asset quantity held recorded daily for positions-impact tracking.
	PositionQuantity Metric = "PositionQuantity"
)

Portfolio performance tracking metrics. 

const (
	// Count is the metric used by CountWhere to store per-timestep counts.
	Count Metric = "Count"
)

Computed aggregate metrics.

func CompositeMetric 

func CompositeMetric(a, b Metric) Metric

CompositeMetric creates a metric representing a pair, joined by ":". Used by Covariance for cross-metric results.

func MetricByName 

func MetricByName(name string) (Metric, bool)

MetricByName looks up a Metric constant by its registry name.

type PVDataOption 

type PVDataOption func(*pvdataOptions)

PVDataOption configures a PVDataProvider.

func WithConfigFile 

func WithConfigFile(path string) PVDataOption

WithConfigFile overrides the default config file path (~/.pvdata.toml).

func WithDimension 

func WithDimension(dim string) PVDataOption

WithDimension sets the fundamental dimension filter (default "ARQ").

type PVDataProvider 

type PVDataProvider struct {
	// contains filtered or unexported fields
}

PVDataProvider is a BatchProvider that reads from a pv-data PostgreSQL database through the canonical preferred views.

func NewPVDataProvider 

func NewPVDataProvider(pool *pgxpool.Pool, opts ...PVDataOption) (*PVDataProvider, error)

NewPVDataProvider creates a provider that reads from a pv-data database. If pool is nil the provider reads ~/.pvdata.toml (or the path set via WithConfigFile) for the connection URL and creates its own pool.

func (*PVDataProvider) Assets 

func (p *PVDataProvider) Assets(ctx context.Context) ([]asset.Asset, error)

Assets returns all known assets from the database.

func (*PVDataProvider) Close 

func (p *PVDataProvider) Close() error

Close releases resources. If the provider created its own pool it is closed.

func (*PVDataProvider) Dimension added in v0.7.2 

func (p *PVDataProvider) Dimension() string

Dimension returns the current fundamental dimension filter.

func (*PVDataProvider) Fetch 

func (p *PVDataProvider) Fetch(ctx context.Context, req DataRequest) (*DataFrame, error)

Fetch retrieves data for the requested assets, metrics, and time range.

func (*PVDataProvider) FetchFundamentalsByDateKey added in v0.7.2 

func (p *PVDataProvider) FetchFundamentalsByDateKey(
	ctx context.Context,
	assets []asset.Asset,
	metrics []Metric,
	dateKey time.Time,
	dimension string,
	maxEventDate time.Time,
) (*DataFrame, error)

FetchFundamentalsByDateKey implements FundamentalsByDateKeyProvider.

func (*PVDataProvider) FetchMarketHolidays 

func (p *PVDataProvider) FetchMarketHolidays(ctx context.Context) ([]tradecron.MarketHoliday, error)

FetchMarketHolidays loads all market holidays from the database.

func (*PVDataProvider) IndexMembers added in v0.6.0 

func (p *PVDataProvider) IndexMembers(ctx context.Context, index string, forDate time.Time) ([]asset.Asset, []IndexConstituent, error)

IndexMembers returns the constituents of the named index at forDate. The returned slice is borrowed -- it is only valid for the current engine step. Callers that need data across steps must copy.

Dates must be monotonically increasing across calls for a given index. The provider loads all snapshot and changelog data on the first call and advances an internal cursor as time progresses.

func (*PVDataProvider) LookupAsset 

func (p *PVDataProvider) LookupAsset(ctx context.Context, ticker string) (asset.Asset, error)

LookupAsset resolves a ticker to an Asset using the assets view. FRED-namespaced tickers (e.g. "FRED:DGS3MO") are resolved synthetically because economic indicators do not have rows in the assets table.

func (*PVDataProvider) Provides 

func (p *PVDataProvider) Provides() []Metric

Provides returns all metrics that PVDataProvider can supply.

func (*PVDataProvider) RatedAssets 

func (p *PVDataProvider) RatedAssets(ctx context.Context, analyst string, filter RatingFilter, asOfDate time.Time) ([]asset.Asset, error)

RatedAssets returns the set of assets whose most-recent rating (on or before t) from the named analyst matches filter. It returns nil, nil when filter has no values to match.

func (*PVDataProvider) SetDimension added in v0.7.0 

func (p *PVDataProvider) SetDimension(dim string)

SetDimension updates the fundamental dimension filter at runtime. Valid values: "ARQ", "ARY", "ART", "MRQ", "MRY", "MRT".

type Period 

type Period struct {
	N    int
	Unit PeriodUnit
}

Period represents a calendar-aware duration used for performance metric windows. Unlike time.Duration, it handles variable-length units like months and years correctly.

func Days 

func Days(n int) Period

Days returns a Period of n calendar days.

func MTD 

func MTD() Period

MTD returns a Period representing month-to-date.

func Months 

func Months(n int) Period

Months returns a Period of n calendar months.

func WTD 

func WTD() Period

WTD returns a Period representing week-to-date.

func YTD 

func YTD() Period

YTD returns a Period representing year-to-date.

func Years 

func Years(n int) Period

Years returns a Period of n calendar years.

func (Period) Before 

func (p Period) Before(ref time.Time) time.Time

Before returns the start time of the period ending at ref.

type PeriodUnit 

type PeriodUnit int

PeriodUnit identifies the calendar unit of a Period. 

const (
	UnitDay PeriodUnit = iota
	UnitMonth
	UnitYear
	UnitYTD // year-to-date: from Jan 1 of the current year
	UnitMTD // month-to-date: from the 1st of the current month
	UnitWTD // week-to-date: from the most recent Monday
)

type Permutation 

type Permutation struct{}

Permutation randomly shuffles the time indices of the historical return series without replacement. All assets are permuted with the same index mapping. The marginal distribution is exactly preserved.

func (*Permutation) Resample 

func (pp *Permutation) Resample(returns [][]float64, targetLen int, rng *rand.Rand) [][]float64

Resample returns a permuted view of the historical returns. When targetLen exceeds the history length, output is capped at the history length. When targetLen is shorter, only the first targetLen permuted indices are used.

type RatingFilter 

type RatingFilter struct {
	Values []int
}

RatingFilter holds an explicit set of rating values to match against. The zero value matches nothing.

func RatingEq 

func RatingEq(v int) RatingFilter

RatingEq returns a RatingFilter that matches exactly one value.

func RatingIn 

func RatingIn(vs ...int) RatingFilter

RatingIn returns a RatingFilter that matches any of the given values. If no values are provided, the returned filter matches nothing.

func RatingLTE 

func RatingLTE(v int) RatingFilter

RatingLTE returns a RatingFilter that matches ratings 1 through v inclusive. If v <= 0, the returned filter matches nothing (zero value).

func (RatingFilter) Matches 

func (f RatingFilter) Matches(rating int) bool

Matches reports whether rating is in the filter's value set. A zero-value RatingFilter (empty Values) always returns false.

type RatingProvider 

type RatingProvider interface {
	RatedAssets(ctx context.Context, analyst string, filter RatingFilter, t time.Time) ([]asset.Asset, error)
}

RatingProvider is satisfied by any type that can return assets matching a rating filter for a given analyst at a point in time.

type Resampler 

type Resampler interface {
	Resample(returns [][]float64, targetLen int, rng *rand.Rand) [][]float64
}

Resampler produces a synthetic return series from historical returns. Input is a 2D slice (assets x time steps) of daily returns. Output is a 2D slice (assets x targetLen) of resampled returns. All methods synchronize cross-asset indices to preserve correlations.

type ResamplingProvider 

type ResamplingProvider struct {
	// contains filtered or unexported fields
}

ResamplingProvider implements BatchProvider by wrapping pre-fetched historical data and producing synthetic price series via resampling. It uses a Resampler to draw from historical daily returns and reconstructs price paths that share the statistical properties of the historical data.

func NewResamplingProvider 

func NewResamplingProvider(historicalData *DataFrame, resampler Resampler, seed uint64, metrics []Metric) *ResamplingProvider

NewResamplingProvider returns a ResamplingProvider backed by the given historical DataFrame. The resampler controls how synthetic returns are drawn; seed initialises the PRNG for reproducibility.

func (*ResamplingProvider) Close 

func (rp *ResamplingProvider) Close() error

Close is a no-op for ResamplingProvider.

func (*ResamplingProvider) Fetch 

func (rp *ResamplingProvider) Fetch(ctx context.Context, req DataRequest) (*DataFrame, error)

Fetch produces a synthetic price DataFrame for the requested assets, metrics, and time range. It:

  1. Narrows historical data to the requested assets and MetricClose only.
  2. Extracts daily returns from close prices for each asset.
  3. Passes the returns through the configured Resampler.
  4. Reconstructs synthetic prices from resampled returns, starting at each asset's first historical close price.
  5. Maps each requested metric to the synthetic series: Close/AdjClose/Open receive the synthetic price; High gets price*1.005; Low gets price*0.995; Dividend gets 0.0; SplitFactor gets 1.0.
  6. Uses the historical time axis (narrowed to the requested range) as the output time axis.

func (*ResamplingProvider) Provides 

func (rp *ResamplingProvider) Provides() []Metric

Provides returns the set of metrics this provider can supply.

type ReturnBootstrap 

type ReturnBootstrap struct{}

ReturnBootstrap resamples individual time steps with replacement. For each output time step, picks a random historical time step and copies returns for all assets at that step. Preserves cross-asset correlations at each point but destroys all temporal structure.

func (*ReturnBootstrap) Resample 

func (rb *ReturnBootstrap) Resample(returns [][]float64, targetLen int, rng *rand.Rand) [][]float64

Resample draws targetLen individual time steps at random (with replacement) from the historical series. All assets use the same drawn index at each step, preserving cross-asset correlations.

type RollingDataFrame 

type RollingDataFrame struct {
	// contains filtered or unexported fields
}

RollingDataFrame applies rolling-window operations to each column of the source DataFrame. Created by DataFrame.Rolling(n).

func (*RollingDataFrame) EMA added in v0.5.0 

func (r *RollingDataFrame) EMA() *DataFrame

EMA returns a DataFrame with the exponential moving average over the window. The smoothing factor is alpha = 2 / (n + 1) where n is the window size. The first n-1 rows are NaN. The EMA is seeded with the simple moving average of the first n values.

func (*RollingDataFrame) Max 

func (r *RollingDataFrame) Max() *DataFrame

Max returns a DataFrame with the rolling maximum over the window.

func (*RollingDataFrame) Mean 

func (r *RollingDataFrame) Mean() *DataFrame

Mean returns a DataFrame with the rolling mean over the window.

func (*RollingDataFrame) Min 

func (r *RollingDataFrame) Min() *DataFrame

Min returns a DataFrame with the rolling minimum over the window.

func (*RollingDataFrame) Percentile 

func (r *RollingDataFrame) Percentile(percentile float64) *DataFrame

Percentile returns a DataFrame with the rolling p-th percentile over the window. p should be in the range [0, 1].

func (*RollingDataFrame) Std 

func (r *RollingDataFrame) Std() *DataFrame

Std returns a DataFrame with the rolling sample standard deviation (N-1 denominator) over the window.

func (*RollingDataFrame) Sum 

func (r *RollingDataFrame) Sum() *DataFrame

Sum returns a DataFrame with the rolling sum over the window.

func (*RollingDataFrame) Variance 

func (r *RollingDataFrame) Variance() *DataFrame

Variance returns a DataFrame with the rolling sample variance (N-1 denominator) over the window.

type SnapshotProvider 

type SnapshotProvider struct {
	// contains filtered or unexported fields
}

SnapshotProvider replays data from a snapshot SQLite database.

func NewSnapshotProvider 

func NewSnapshotProvider(path string) (*SnapshotProvider, error)

NewSnapshotProvider opens the snapshot database at path in read-only mode.

func (*SnapshotProvider) Assets 

func (p *SnapshotProvider) Assets(ctx context.Context) ([]asset.Asset, error)

func (*SnapshotProvider) Close 

func (p *SnapshotProvider) Close() error

Close closes the database connection.

func (*SnapshotProvider) Fetch 

func (p *SnapshotProvider) Fetch(ctx context.Context, req DataRequest) (*DataFrame, error)

func (*SnapshotProvider) FetchFundamentalsByDateKey added in v0.7.2 

func (p *SnapshotProvider) FetchFundamentalsByDateKey(
	ctx context.Context,
	assets []asset.Asset,
	metrics []Metric,
	dateKey time.Time,
	dimension string,
	maxEventDate time.Time,
) (*DataFrame, error)

FetchFundamentalsByDateKey implements FundamentalsByDateKeyProvider for snapshot replay. The query mirrors the PVDataProvider implementation but uses SQLite syntax (no DISTINCT ON; row_number window function instead).

func (*SnapshotProvider) FetchMarketHolidays 

func (p *SnapshotProvider) FetchMarketHolidays(ctx context.Context) ([]tradecron.MarketHoliday, error)

FetchMarketHolidays loads market holidays from the snapshot database.

func (*SnapshotProvider) IndexMembers 

func (p *SnapshotProvider) IndexMembers(ctx context.Context, index string, forDate time.Time) ([]asset.Asset, []IndexConstituent, error)

func (*SnapshotProvider) LookupAsset 

func (p *SnapshotProvider) LookupAsset(ctx context.Context, ticker string) (asset.Asset, error)

func (*SnapshotProvider) Provides 

func (p *SnapshotProvider) Provides() []Metric

func (*SnapshotProvider) RatedAssets 

func (p *SnapshotProvider) RatedAssets(ctx context.Context, analyst string, filter RatingFilter, forDate time.Time) ([]asset.Asset, error)

type SnapshotRecorder 

type SnapshotRecorder struct {
	// contains filtered or unexported fields
}

SnapshotRecorder wraps real data providers, delegates every call, and writes the results to a SQLite snapshot database.

func NewSnapshotRecorder 

func NewSnapshotRecorder(path string, cfg SnapshotRecorderConfig) (*SnapshotRecorder, error)

NewSnapshotRecorder opens (or creates) the SQLite file at path, creates the snapshot schema, and returns a recorder ready to wrap provider calls.

func (*SnapshotRecorder) Assets 

func (r *SnapshotRecorder) Assets(ctx context.Context) ([]asset.Asset, error)

Assets delegates to the inner AssetProvider and records the results.

func (*SnapshotRecorder) Close 

func (r *SnapshotRecorder) Close() error

Close closes the underlying SQLite database.

func (*SnapshotRecorder) Fetch 

func (r *SnapshotRecorder) Fetch(ctx context.Context, req DataRequest) (*DataFrame, error)

Fetch delegates to the inner BatchProvider and records the results.

func (*SnapshotRecorder) FetchFundamentalsByDateKey added in v0.7.4 

func (r *SnapshotRecorder) FetchFundamentalsByDateKey(
	ctx context.Context,
	assets []asset.Asset,
	metrics []Metric,
	dateKey time.Time,
	dimension string,
	maxEventDate time.Time,
) (*DataFrame, error)

FetchFundamentalsByDateKey delegates to a wrapped FundamentalsByDateKeyProvider and records the returned values so SnapshotProvider can replay the same call. Returns an error when no wrapped provider implements the interface.

The recorder writes one row per asset at event_date = dateKey (the reporting period itself). This is synthetic: the true filing date is consumed inside the provider's DISTINCT ON ordering and not exposed on the returned DataFrame. Because replay queries filter with event_date <= maxEventDate and every sensible caller passes a maxEventDate on or after the reporting period, the recorded row always matches. A replay under a custom as-of date returns the same value the recording saw; it cannot reconstruct filings that the recording never observed.

func (*SnapshotRecorder) FetchMarketHolidays 

func (r *SnapshotRecorder) FetchMarketHolidays(ctx context.Context) ([]tradecron.MarketHoliday, error)

FetchMarketHolidays delegates to the underlying provider and records the holidays in the snapshot database.

func (*SnapshotRecorder) IndexMembers 

func (r *SnapshotRecorder) IndexMembers(ctx context.Context, index string, forDate time.Time) ([]asset.Asset, []IndexConstituent, error)

IndexMembers delegates to the inner IndexProvider and records the results.

func (*SnapshotRecorder) LookupAsset 

func (r *SnapshotRecorder) LookupAsset(ctx context.Context, ticker string) (asset.Asset, error)

LookupAsset delegates to the inner AssetProvider and records the result.

func (*SnapshotRecorder) Provides 

func (r *SnapshotRecorder) Provides() []Metric

Provides delegates to the inner BatchProvider.

func (*SnapshotRecorder) RatedAssets 

func (r *SnapshotRecorder) RatedAssets(ctx context.Context, analyst string, filter RatingFilter, forDate time.Time) ([]asset.Asset, error)

RatedAssets delegates to the inner RatingProvider and records the results.

type SnapshotRecorderConfig 

type SnapshotRecorderConfig struct {
	BatchProvider  BatchProvider
	AssetProvider  AssetProvider
	IndexProvider  IndexProvider  // optional
	RatingProvider RatingProvider // optional
}

SnapshotRecorderConfig holds the providers to wrap.

type StreamProvider 

type StreamProvider interface {
	DataProvider

	// Subscribe opens a real-time data stream. Each DataPoint is delivered
	// on the returned channel. The provider closes the channel when the
	// context is cancelled.
	Subscribe(ctx context.Context, req DataRequest) (<-chan DataPoint, error)
}

StreamProvider delivers data in real-time. Used during live trading where the engine reacts to incoming market data. The engine manages subscriptions by cancelling the context and re-subscribing when the requested assets or metrics change.

type TestProvider 

type TestProvider struct {
	// contains filtered or unexported fields
}

TestProvider is a BatchProvider backed by a predetermined DataFrame. It is intended for use in tests and simulations where data is known ahead of time.

func NewTestProvider 

func NewTestProvider(metrics []Metric, frame *DataFrame) *TestProvider

NewTestProvider returns a TestProvider that serves the given metrics from the given DataFrame.

func (*TestProvider) Close 

func (p *TestProvider) Close() error

Close is a no-op for TestProvider.

func (*TestProvider) Fetch 

func (p *TestProvider) Fetch(ctx context.Context, req DataRequest) (*DataFrame, error)

Fetch narrows the stored DataFrame to the request's assets, metrics, and time range.

func (*TestProvider) Provides 

func (p *TestProvider) Provides() []Metric

Provides returns the set of metrics this provider can supply.

type UpsampledDataFrame 

type UpsampledDataFrame struct {
	// contains filtered or unexported fields
}

UpsampledDataFrame fills gaps when converting to a higher frequency. Created by DataFrame.Upsample(freq).

func (*UpsampledDataFrame) BackFill 

func (u *UpsampledDataFrame) BackFill() *DataFrame

BackFill uses the next known value to fill gaps in the upsampled time axis.

func (*UpsampledDataFrame) ForwardFill 

func (u *UpsampledDataFrame) ForwardFill() *DataFrame

ForwardFill carries the last known value forward to fill gaps in the upsampled time axis.

func (*UpsampledDataFrame) Interpolate 

func (u *UpsampledDataFrame) Interpolate() *DataFrame

Interpolate linearly interpolates between known values to fill gaps in the upsampled time axis.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.