归因

Brinson-Fachler、Brinson-Hood-Beebower、Fama-French 与风格归因。

面向任务的示例参见使用指南。以下签名由与本站点其余内容同一提交的公共头文件生成。

class BrinsonAttribution

与源实现中有状态的 BrinsonAttribution 计算器相对应的原生所有权门面。

该门面存储一个可选的行业映射，并在委托给规范的 brinson_results 内核之前，将其应用于收益率（均值）、基准收益率（均值）与权重（求和）。缺失的基准收益率默认取组合收益率；缺失的权重默认取等权重。原生结果保留内核的时间戳索引与完整效应列（源实现中的整数周期列和 RangeIndex 属于 Python 侧的身份标识，并非原生声明）。

公共函数

explicit BrinsonAttribution(std::map<std::string, std::vector<std::string>> sector_mapping = {})

使用可选的行业映射构造门面。

映射按传入原样存储，并在 calculate 运行时校验。

参数:

sector_mapping -- Sector name to asset-column mapping; empty disables sector aggregation.

const std::map<std::string, std::vector<std::string>> &sector_mapping() const noexcept

返回存储的行业到资产映射。

返回:

Const reference to the mapping owned by this facade.

dataframe calculate(const dataframe &returns, std::optional<dataframe> benchmark_returns = std::nullopt, std::optional<dataframe> weights = std::nullopt, std::string_view method = "brinson") const

针对给定的收益率计算原生 Brinson 归因。

method 参数接受 brinson 以及历史别名 brinson_hood，两者都选择 BHB 算术分解。存在行业映射时，先对各行业的资产求收益率与基准收益率的均值、并对权重求和，再进行归因。缺失的基准收益率默认取组合收益率，缺失的权重默认取等权重，而基准权重始终为等权重。

参数:

  • returns -- Portfolio returns with one double column per asset.

  • benchmark_returns -- Optional benchmark returns; defaults to returns.

  • weights -- Optional portfolio weights; defaults to equal weights.

  • method -- Attribution method name.

抛出:

  • fincore_error -- If method is unknown, a mapping entry names an empty sector or asset list, a mapped asset column length does not match the index, or no return column remains.

  • input_error -- If a mapped asset column is missing or the Brinson kernel rejects the resolved inputs.

返回:

A frame indexed like returns with the allocation, selection, interaction, total, portfolio-return and benchmark-return columns.

class FamaFrenchModel

原生带所有权的 Fama-French 模型门面。

该模型存储其设定（3factor、5factor 或 4factor_mom）、无风险利率以及拟合的 alpha 与 beta。估计过程委托给既有的原生因子回归内核。所有返回的帧都自行持有数据。

公共函数

explicit FamaFrenchModel(std::string model_type = "5factor", double risk_free_rate = 0.0)

为受支持的设定构造 Fama-French 模型。

参数:

  • model_type -- One of 3factor, 5factor or 4factor_mom.

  • risk_free_rate -- Finite risk-free rate stored with the model.

抛出:

fincore_error -- If model_type is unsupported or the risk-free rate is not finite.

const std::string &model_type() const noexcept

返回配置的模型类型。

返回:

One of 3factor, 5factor or 4factor_mom.

double risk_free_rate() const noexcept

返回配置的无风险利率。

返回:

The risk-free rate supplied at construction.

std::span<const std::string_view> factors() const noexcept

返回由模型类型选定的因子名称。

返回:

A non-owning view valid for the lifetime of this model.

const std::map<std::string, double> &betas() const noexcept

返回拟合的因子 beta。

返回:

Factor-to-beta mapping, empty before a successful fit.

std::optional<double> alpha() const noexcept

返回拟合的截距。

返回:

The alpha from the most recent fit, empty before fitting.

fama_french_fit_result fit(const dataframe &returns, const dataframe &factor_data, std::string_view returns_column = {})

拟合配置的模型并存储其 alpha 与 beta。

returns_column 为空时选择第一个 double 列，与源实现的单资产 DataFrame 行为一致。拟合过程委托给原生最小二乘因子回归。

参数:

  • returns -- Frame containing the dependent return series.

  • factor_data -- Frame containing the configured factor columns and sharing returns' index.

  • returns_column -- Optional dependent column name.

抛出:

  • fincore_error -- If no double returns column can be selected.

  • input_error -- If the regression rejects the inputs or is rank deficient.

返回:

The native fit result and the factor betas for this model.

dataframe predict(const dataframe &factor_data) const

使用存储的模型由因子数据预测拟合收益。

结果为每个输入行的 alpha + sum(beta_i * factor_i)，并存入 fitted_returns 列。

参数:

factor_data -- Frame containing all configured factor columns.

抛出:

fincore_error -- If the model has not been fitted (code fincore.model_not_fit) or a factor column length does not match the frame index.

返回:

A frame indexed like factor_data with one fitted_returns column.

dataframe get_factor_exposures(const dataframe &returns, const dataframe &factor_data, std::optional<std::size_t> rolling_window = std::nullopt, std::string_view returns_column = {}) const

在扩展窗口或滚动窗口上计算 alpha 与因子 beta。

rolling_window 选择滚动窗口；std::nullopt 或零表示从首行开始的扩展窗口。对 K 个因子而言观测数不超过 K 的行为 NaN。该方法不会更新模型存储的 alpha 或 beta。

参数:

  • returns -- Frame containing the dependent return column.

  • factor_data -- Frame containing the configured factor columns.

  • rolling_window -- Optional trailing window length.

  • returns_column -- Optional dependent column name; an empty value selects the first double column.

抛出:

  • fincore_error -- If the frames do not share the same index or the dependent column cannot be selected.

  • input_error -- If an eligible window regression fails.

返回:

A frame indexed like returns with alpha followed by one column per configured factor.

std::map<std::string, double> attribution_decomposition(const dataframe &returns, const dataframe &factor_data, std::string_view returns_column = {})

拟合模型并分解其平均收益。

返回的映射包含 alpha、每个配置因子一条 _attribution 记录（beta * mean(factor)）、specific_return（这些贡献之和）、common_return（因变量平均收益减去配置的无风险利率）以及 unexplained（common_return - alpha - specific_return）。拟合过程会更新模型存储的 alpha 与 beta。

参数:

  • returns -- Frame containing the dependent return series.

  • factor_data -- Frame containing the configured factor columns.

  • returns_column -- Optional dependent column name.

抛出:

  • fincore_error -- If the dependent return column cannot be selected.

  • input_error -- If the regression rejects the inputs.

返回:

A map from component name to contribution.

class StyleResult

StyleResult 的原生所有权门面。

源容器暴露 exposures、returns_by_style 与 overall_returns，以及确定性的摘要/字典投影。原生类持有这三张帧的副本。

公共函数

StyleResult(dataframe exposures, dataframe returns_by_style, dataframe overall_returns)

由三张已有的帧构造结果。

帧被移动进结果对象，此处不做校验。

参数:

  • exposures -- Asset-by-style exposure frame.

  • returns_by_style -- Style/return summary frame.

  • overall_returns -- Portfolio return frame.

explicit StyleResult(style_analysis_result result)

通过消耗一个风格分析结果来构造结果。

参数:

result -- Analysis result whose frames are moved into this object.

const dataframe &exposures() const noexcept

返回所持有的暴露帧。

返回:

Const reference to the asset-by-style exposures.

const dataframe &returns_by_style() const noexcept

返回所持有的风格/收益摘要帧。

返回:

Const reference to the style and return columns.

const dataframe &overall_returns() const noexcept

返回所持有的组合收益帧。

返回:

Const reference to the overall returns.

std::map<std::string, double> style_summary() const

返回按确定性键序排列的风格到平均收益映射。

存在时使用 returns_by_style 的 style 列与 return 列；缺少 return 列时回退到第一个 double 列，缺少 style 列时以时间戳作为标签。后出现的重复风格标签会覆盖先前的值。

抛出:

fincore_error -- If no numeric return column exists or the style and return columns do not align.

返回:

Mapping from style label to its stored return.

std::map<std::string, dataframe> to_dict() const

返回三张所持帧的字典。

键为 exposures、returns_by_style 与 overall_returns；每个值都是独立副本。

返回:

Map from source key to a copied frame.

struct attribution_alignment

资产与日期对齐之后的归因输入。

公共成员

dataframe returns

限定为对齐日期的收益率。

dataframe positions

剔除未载入的非现金资产与未对齐日期后的持仓。

dataframe factor_returns

限定为对齐日期的因子收益率。

factor_loading_table factor_loadings

从输入表原样复制的载荷。

std::vector<std::string> warnings

对齐警告，缺失资产警告排在最前。

struct brinson_cumulative_result

跨所有周期的 Brinson 效应求和与复利收益。

公共成员

double allocation

各期配置效应之和。

double selection

各期选择效应之和。

double interaction

各期交互效应之和。

double total

各期总效应之和。

double portfolio_cumulative

复利组合收益，即 wealth - 1。

double benchmark_cumulative

复利基准收益，即 wealth - 1。

struct brinson_period_result

单期的 Brinson-Hood-Beebower 效应。

每个效应都是该期的直接算术贡献；不做归一化或复利处理。

公共成员

double allocation

该期的配置效应。

double selection

该期的选择效应。

double interaction

该期的交互效应。

double total

配置、选择与交互之和。

double portfolio_return

该期的加权组合收益。

double benchmark_return

该期的加权基准收益。

struct factor_loading_table

按日期、资产与因子标签对齐的因子载荷表。

values 是展平的 dates x assets x factors 缓冲区；NaN 标记缺失的载荷。align_and_warn 要求其长度与标签维度匹配，并使用日期与资产标签进行对齐。

公共成员

std::vector<timestamp> dates

存在可用载荷的日期。

std::vector<std::string> assets

具有载荷的资产标识。

std::vector<std::string> factors

因子标识。

std::vector<double> values

展平的载荷值，缺失时为 NaN。

struct factor_regression_result

普通最小二乘因子回归的结果。

所有帧都自行持有数据。coefficients 具有序号索引以及 factor 与 coefficient 列，alpha 在前，其后是按请求顺序排列的因子名称。

公共成员

double alpha

估计的截距。

double r_squared

1 - SSE/SST；收益完全恒定时为 0。

dataframe coefficients

alpha 与因子系数表。

dataframe fitted_returns

在收益率索引上的拟合值。

dataframe residuals

在收益率索引上的观测值减拟合值。

struct fama_french_fit_result

原生 OLS Fama-French 拟合的结果。

原生内核即规范的最小二乘因子回归。Python 的 Newey-West/WLS 协方差选项不属于该内核，因此有意不提供 std_errors/p_values，而不是伪造它们。

公共成员

double alpha = {}

估计的截距。

std::map<std::string, double> betas

因子名称到拟合 beta。

double r_squared = {}

原生拟合得到的回归 R 方。

dataframe fitted_returns

在收益率索引上的拟合值。

dataframe residuals

观测值减拟合值。

struct idiosyncratic_risk_result

特异性风险计算的结果。

公共成员

std::vector<std::string> assets

按列顺序排列的资产名称。

std::vector<double> specific_volatility

各资产的特异性波动率。

double market_beta = 0.0

应用于所有资产的 beta。

struct style_analysis_options

控制风格暴露构造的输入。

可选的逐资产向量必须为空，或为每个资产列包含一个有限值。当 market_caps 为空时，规模风格由 equal_weight 替代。同时提供时 value_scores 优先于 book_to_price。

公共成员

std::span<const double> market_caps = {}

逐资产市值。

std::span<const double> book_to_price = {}

逐资产的账面市值比。

std::span<const double> value_scores = {}

逐资产的价值得分。

std::size_t momentum_window = {252U}

回溯动量观测值。

std::array<double, 2U> size_quantiles = {.5, .5}

落在 [0, 1] 内的规模上下分界。

struct style_analysis_result

style_analysis 产生的帧。

公共成员

dataframe exposures

资产为行、每个风格一列。

dataframe returns_by_style

风格名称与风格平均收益。

dataframe overall_returns

在输入索引上的等权重收益。

attribution_alignment fincore::align_and_warn(const dataframe &returns, const dataframe &positions, const dataframe &factor_returns, const factor_loading_table &factor_loadings)

将归因输入对齐到持仓的资产与载荷日期。

没有载荷的持仓资产会被丢弃（现金除外），没有载荷的日期会从收益率、持仓与因子收益率中移除。警告通过 warnings 返回而不是直接发出。成交换手检查与堆叠 Series 形式的持仓不在这个带类型的接口面之中。

参数:

  • returns -- Portfolio returns to restrict to aligned dates.

  • positions -- Position frame whose double columns define the assets.

  • factor_returns -- Factor returns to restrict to aligned dates.

  • factor_loadings -- Loading labels and flattened values; its value count must equal dates x assets x factors.

抛出:

input_error -- If an input index contains adjacent duplicate timestamps, positions are empty, the loading buffer size is inconsistent, or no non-cash position has loadings.

返回:

The aligned frames, the copied loading table and any warnings.

dataframe fincore::analyze_performance_by_style(const dataframe &asset_returns)

使用默认风格分析计算逐风格收益序列。

以默认选项运行 style_analysis，并将其暴露传入双帧重载。空形状的输入产生空帧。

参数:

asset_returns -- Per-asset simple returns.

抛出:

input_error -- If style analysis or performance alignment rejects the input.

返回:

One <style>_return column per style on an ordinal index.

dataframe fincore::analyze_performance_by_style(const dataframe &asset_returns, const dataframe &style_exposures)

由显式风格暴露计算逐风格收益序列。

暴露帧必须具有序号索引、恰好一个名为 asset 的字符串列，以及至少一个 double 风格列。行按资产身份与收益列对齐；缺失的资产贡献为零，多余的暴露资产被忽略。对齐权重之和为正的风格会被归一化使其和为 1；总和为非正的风格产生全零的收益序列。空形状输入，或没有 double 风格列的暴露帧，产生空帧。

参数:

  • asset_returns -- Per-asset simple returns.

  • style_exposures -- Asset-by-style exposure table.

抛出:

input_error -- If either frame is malformed, asset names are invalid or duplicated, values are non-finite, or arithmetic overflows.

返回:

A frame with one <style>_return column per exposure style on an ordinal index.

brinson_period_result fincore::brinson_attribution(const dataframe &portfolio_returns, const dataframe &benchmark_returns, const dataframe &portfolio_weights, const dataframe &benchmark_weights, std::span<const std::string_view> sector_column_names)

计算单期 Brinson-Hood-Beebower 归因。

每个输入帧都必须为 sector_column_names 中的每个行业包含一个 double 列，且四个帧必须共享同一唯一索引。给定的权重按原样使用，不做归一化。

参数:

  • portfolio_returns -- Per-sector portfolio returns by period.

  • benchmark_returns -- Per-sector benchmark returns by period.

  • portfolio_weights -- Per-sector portfolio weights by period.

  • benchmark_weights -- Per-sector benchmark weights by period.

  • sector_column_names -- Non-empty distinct sector column names; each name must identify a double column in every input frame.

抛出:

input_error -- If the sector names are empty or duplicated, an index contains duplicates, the indexes do not match, a selected column is missing or not a double column, or the result does not contain exactly one row.

返回:

The allocation, selection, interaction, total, portfolio and benchmark effects for the single period.

brinson_cumulative_result fincore::brinson_cumulative(const dataframe &portfolio_returns, const dataframe &benchmark_returns, const dataframe &portfolio_weights, const dataframe &benchmark_weights, std::span<const std::string_view> sector_column_names)

计算跨所有周期的效应之和与复利收益。

四个效应字段是逐期 brinson_results 列的算术求和，而 portfolio_cumulative 与 benchmark_cumulative 将逐期组合与基准收益按 wealth - 1 复利累积。

参数:

  • portfolio_returns -- Per-sector portfolio returns by period.

  • benchmark_returns -- Per-sector benchmark returns by period.

  • portfolio_weights -- Per-sector portfolio weights by period.

  • benchmark_weights -- Per-sector benchmark weights by period.

  • sector_column_names -- Non-empty distinct sector column names; each name must identify a double column in every input frame.

抛出:

input_error -- If the sector names are empty or duplicated, an index contains duplicates, the indexes do not match, or a selected column is missing or not a double column.

返回:

The summed effects and compounded portfolio and benchmark returns.

dataframe fincore::brinson_results(const dataframe &portfolio_returns, const dataframe &benchmark_returns, const dataframe &portfolio_weights, const dataframe &benchmark_weights, std::span<const std::string_view> sector_column_names)

为每个输入周期计算一行 Brinson-Hood-Beebower 效应。

每个输入帧都必须为 sector_column_names 中的每个行业包含一个 double 列，且四个帧必须共享同一唯一索引。结果保留该索引，并包含 allocation、selection、interaction、total、portfolio_return 与 benchmark_return 列。

参数:

  • portfolio_returns -- Per-sector portfolio returns by period.

  • benchmark_returns -- Per-sector benchmark returns by period.

  • portfolio_weights -- Per-sector portfolio weights by period.

  • benchmark_weights -- Per-sector benchmark weights by period.

  • sector_column_names -- Non-empty distinct sector column names; each name must identify a double column in every input frame.

抛出:

input_error -- If the sector names are empty or duplicated, an index contains duplicates, the indexes do not match, or a selected column is missing or not a double column.

返回:

A frame indexed like portfolio_returns with the six effect and return columns.

idiosyncratic_risk_result fincore::calculate_idiosyncratic_risk(const dataframe &returns, const dataframe &factor_data, std::optional<double> market_beta = std::nullopt, double risk_free = 0.0)

由因子数据计算资产的特异性波动率。

未提供 market_beta 时，先用普通最小二乘将第一个资产的超额收益对五个 Fama-French 列（MKT、SMB、HML、RMW、CMA）回归得到 beta，然后将其应用于所有资产，与固定版本的例程一致。特异性波动率为总方差减去 beta^2 倍市场方差后的平方根，方差使用剔除无风险利率后的总体方差计算；残差方差为非正时取零。

参数:

  • returns -- Frame with at least one double asset-return column.

  • factor_data -- Factor frame with the same row count; it must contain a double MKT column and, when fitting the beta, all five Fama-French columns.

  • market_beta -- Optional beta applied to every asset; fitted from the first asset when absent.

  • risk_free -- Finite risk-free rate subtracted before variance and beta calculations.

抛出:

input_error -- If the risk-free rate or beta is not finite, the frames are empty or have different row counts, a required factor column is missing, there are too few rows to fit the beta, the beta regression is singular, or no asset column exists.

返回:

The asset names, their specific volatilities and the beta used.

dataframe fincore::calculate_regression_attribution(const dataframe &asset_returns)

基于默认风格分析计算自动风格归因。

以默认选项运行 style_analysis，使用 analyze_performance_by_style 构造风格收益序列，并为每个风格赋予其与等权组合收益的中心化 Pearson 相关系数乘以该风格的平均收益。残量为组合均值减去各贡献之和。配对观测少于三个或配对偏差接近零的风格贡献为零。空形状的输入产生空帧。

参数:

asset_returns -- Per-asset simple returns.

抛出:

input_error -- If style analysis, performance alignment or attribution validation rejects the input.

返回:

A frame with style and contribution columns plus a final residual row.

dataframe fincore::calculate_regression_attribution(const dataframe &portfolio_returns, const dataframe &style_returns, std::span<const std::string_view> selected_styles)

针对显式给出的组合与风格收益计算风格归因。

组合序列为 portfolio_returns 中所有 double 列的行均值。所选风格列按时间戳对齐；每个风格的贡献是其与组合序列的中心化 Pearson 相关系数乘以在对齐时间戳上的均值。风格按 style_returns 的列顺序输出，其后是使用完整组合均值的残量行。未匹配的选取项被忽略。配对时间戳少于三个或对齐偏差接近零的风格贡献为零。空形状的组合产生空帧。

参数:

  • portfolio_returns -- One or more double portfolio return columns.

  • style_returns -- Candidate style return columns.

  • selected_styles -- Style column names to attribute; empty names, duplicates and residual are rejected.

抛出:

input_error -- If selectors are malformed, a non-empty portfolio has invalid columns or values, a selected style column has invalid structure or non-finite values, or arithmetic overflows.

返回:

A frame with style and contribution columns plus a final residual row.

dataframe fincore::calculate_style_tilts(const dataframe &asset_returns, std::size_t window = 252U)

计算滚动截面的风格倾斜指标。

每个输出行使用在该行之前结束的滚动窗口观测。规模按最新收益的平均秩在三分之一与三分之二分界处划分（下三分之一为 _large，上三分之一为 _small）；winner/loser 以零为界划分复利滚动收益；value/growth 以中位数为界划分其平均秩；high/low volatility 以中位数为界划分至多最近 60 个观测的样本标准差，并列归入 high volatility。输出列按阶段为主序：先是所有 _large 列，然后所有 _small 列，随后是 _winner、_loser、_value、_growth、_high_vol 与 _low_vol，每个阶段内资产按输入列顺序排列。

参数:

  • asset_returns -- Per-asset simple returns.

  • window -- Trailing observations used for ranks and momentum; defaults to 252.

抛出:

input_error -- If the frame contains non-double columns, invalid or duplicate asset names, non-finite returns, or an unrepresentable output becomes necessary.

返回:

A binary tilt frame whose index starts at the first eligible row, or an empty frame when fewer than three rows or fewer than two usable trailing observations are available.

dataframe fincore::factor_attribution_decomposition(const dataframe &returns, const dataframe &factor_returns, std::span<const std::string_view> factor_column_names, double risk_free_rate = 0.0, std::string_view returns_column_name = returns_column)

将平均收益分解为 alpha、因子、特异、共同与未解释部分。

因子通过普通最小二乘拟合，每个因子贡献 beta * mean(factor)，specific_return 为这些贡献之和。common_return 为 mean(returns) - risk_free_rate，unexplained 为 common_return - alpha - specific_return。输出索引为序号，行按此顺序排列：alpha、按请求顺序的每个 _attribution、specific_return、common_return 与 unexplained。

参数:

  • returns -- Frame containing the dependent return column.

  • factor_returns -- Frame containing the factor columns.

  • factor_column_names -- Non-empty distinct factor names; alpha is reserved and must not be selected.

  • risk_free_rate -- Risk-free rate subtracted when forming the common return; must be finite.

  • returns_column_name -- Double column used as the dependent variable.

抛出:

input_error -- If the selectors, risk-free rate, regression inputs or arithmetic results are invalid or non-finite.

返回:

A frame with component and contribution columns and an ordinal index.

dataframe fincore::factor_regression_predictions(const factor_regression_result &regression, const dataframe &factor_returns, std::span<const std::string_view> factor_column_names)

由已拟合的因子回归预测收益。

回归中的系数表必须在结构上有效：长度为 K + 1 的序号索引以及 factor/coefficient 列，alpha 在前，其余标签按顺序与 factor_column_names 匹配。预测值为每个输入行的 alpha + sum(beta_i * factor_i)。

参数:

  • regression -- Previously fitted factor regression.

  • factor_returns -- Frame containing the requested factor columns.

  • factor_column_names -- Non-empty distinct factor names matching the coefficient labels; alpha is reserved.

抛出:

input_error -- If the selectors, coefficient table, selected factor values or arithmetic results are invalid or non-finite.

返回:

A frame indexed like factor_returns with one predicted_returns double column.

dataframe fincore::fetch_ff_factors(std::string_view start, std::string_view end, std::string_view library, const fama_french_provider &provider, bool copy = true)

通过显式的数据提供方获取 Fama-French 因子。

保留 copy 参数是为了与源签名兼容。原生结果始终自行持有缓冲区；提供方不能把缓存数据的所有权交给调用方，因此 copy 的两个取值都返回独立副本。

参数:

  • start -- Non-empty start date passed to the provider.

  • end -- Non-empty end date passed to the provider.

  • library -- Non-empty factor library name.

  • provider -- Callable returning a non-empty frame with at least one supported column.

  • copy -- Retained for source compatibility; ignored.

抛出:

fincore_error -- If the provider is not callable, a date or library is empty, or the provider returns an empty or column-less frame.

返回:

The provider's validated frame, owned by the caller.

dataframe fincore::fetch_ff_factors(std::string_view start, std::string_view end, const fama_french_provider &provider, std::string_view library = "french", bool copy = true)

获取 Fama-French 因子，库默认取 french。

参数:

  • start -- Non-empty start date passed to the provider.

  • end -- Non-empty end date passed to the provider.

  • provider -- Callable returning a non-empty frame with at least one supported column.

  • library -- Non-empty factor library name; defaults to french.

  • copy -- Retained for source compatibility; ignored.

抛出:

fincore_error -- If the provider is not callable, a date or library is empty, or the provider returns an empty or column-less frame.

返回:

The provider's validated frame, owned by the caller.

dataframe fincore::fetch_style_factors(const std::vector<std::string> &tickers, const std::optional<std::vector<std::string>> &factors, std::string_view library, const style_factor_provider &provider)

通过注入的提供方获取风格因子。

参数:

  • tickers -- Non-empty ticker list with no empty entries.

  • factors -- Optional factor names passed through unchanged; std::nullopt mirrors the source's None.

  • library -- Factor library name; must not be empty.

  • provider -- Callable returning a non-empty frame with at least one supported column.

抛出:

fincore_error -- If the tickers, library or provider are invalid, or the provider returns an empty or column-less frame.

返回:

The provider's validated frame, owned by the caller.

dataframe fincore::fetch_style_factors(const std::vector<std::string> &tickers, const std::optional<std::vector<std::string>> &factors, const style_factor_provider &provider, std::string_view library = "us")

获取风格因子，库默认取 us。

参数:

  • tickers -- Non-empty ticker list with no empty entries.

  • factors -- Optional factor names passed through unchanged.

  • provider -- Callable returning a non-empty frame with at least one supported column.

  • library -- Factor library name; defaults to us.

抛出:

fincore_error -- If the tickers, library or provider are invalid, or the provider returns an empty or column-less frame.

返回:

The provider's validated frame, owned by the caller.

factor_regression_result fincore::fit_factor_regression(const dataframe &returns, const dataframe &factor_returns, std::span<const std::string_view> factor_column_names, std::string_view returns_column_name = returns_column)

拟合带截距的普通最小二乘因子回归。

将因变量列对指定的因子列做回归。两个帧必须共享同一唯一索引，选取的值必须有限，且 K 个因子至少需要 K + 1 个观测。拟合使用 Householder QR 求解，并拒绝秩亏的设计矩阵。

参数:

  • returns -- Frame containing the dependent return column.

  • factor_returns -- Frame containing the factor columns.

  • factor_column_names -- Non-empty distinct factor names; alpha is reserved and must not be selected.

  • returns_column_name -- Double column used as the dependent variable.

抛出:

input_error -- If the selectors are empty, duplicated or reserved, the indexes are duplicated or mismatched, a selected column is missing or non-finite, there are fewer than K + 1 observations, the design is rank deficient, or an intermediate is not finite.

返回:

The intercept, R-squared, coefficient table, fitted values and residuals.

dataframe fincore::rolling_factor_exposures(const dataframe &returns, const dataframe &factor_returns, std::span<const std::string_view> factor_column_names, std::optional<std::size_t> rolling_window = std::nullopt, std::string_view returns_column_name = returns_column)

用最小二乘计算滚动或扩展的因子暴露。

每个输出行在截至该行的窗口上拟合所请求的因子。给定 rolling_window 时窗口限制为该数量的末尾观测；std::nullopt 表示从首行开始的扩展窗口。对 K 个因子而言观测数不超过 K 的行为 NaN。

参数:

  • returns -- Frame containing the dependent return column.

  • factor_returns -- Frame containing the factor columns.

  • factor_column_names -- Non-empty distinct factor names; alpha is reserved and must not be selected.

  • rolling_window -- Optional trailing window length; must be positive when supplied.

  • returns_column_name -- Double column used as the dependent variable.

抛出:

input_error -- If selectors are empty, duplicated, reserved or malformed, the window is zero, an index is duplicated or mismatched, a selected value is non-finite, an eligible window is rank deficient, or arithmetic overflows.

返回:

A frame indexed like returns with alpha followed by one double column per requested factor.

style_analysis_result fincore::style_analysis(const dataframe &asset_returns, const style_analysis_options &options = {})

计算风格暴露与风格收益摘要。

每个资产列都必须为 double、名称互不相同且非空，并包含有限值。暴露表每个资产一行、每个构造出的风格一列；returns_by_style 报告每个风格的算术平均收益；overall_returns 在输入时间戳上报告等权组合收益。没有合格资产的风格得到零权重和 NaN 摘要收益。

参数:

  • asset_returns -- Per-asset simple returns; every column is an asset.

  • options -- Style construction options; per-asset vectors must be empty or match the asset count.

抛出:

input_error -- If the frame is empty, contains non-double columns, empty or duplicate asset names, non-finite returns or option values, size quantiles outside [0, 1], or unrepresentable sizes.

返回:

Exposure, style-return summary and overall-return frames, each owning its data.

using fincore::FamaFrenchModelPatch = FamaFrenchModel

与源实现兼容的 fincore.attribution.fama_french_patch.FamaFrenchModelPatch 兼容门面。

该补丁模块记录了与规范 Fama-French 模型相同的模型设定字段（model_type、risk_free_rate、所选因子与拟合 beta）。在固定版本的源实现中它不引入独立计算，因此原生别名有意映射到带所有权的 FamaFrenchModel，而不是复制估计状态。

using fincore::fama_french_provider = std::function<dataframe(std::string_view start, std::string_view end, std::string_view library)>

Fama-French 数据的注入式提供方边界。

每次调用都显式提供提供方；不存在进程全局的提供方或缓存状态。返回的帧由 fetch_ff_factors 校验并复制为独立副本（深拷贝）。

using fincore::style_factor_provider = std::function<dataframe(const std::vector<std::string> &tickers, const std::optional<std::vector<std::string>> &factors, std::string_view library)>

注入式的风格因子提供方边界。

提供方接收一个显式的 factors 选项（nullopt 对应源实现中的 None），并返回经过校验的独立帧。

constexpr std::array<std::string_view, 3U> fincore::FF3_FACTORS{"MKT", "SMB", "HML"}

标准三因子 Fama-French 定义，与固定版本源实现一致。

constexpr std::array<std::string_view, 4U> fincore::FF4MOM_FACTORS{"MKT", "SMB", "HML", "MOM"}

包含动量因子的四因子 Fama-French 定义。

constexpr std::array<std::string_view, 5U> fincore::FF5_FACTORS{"MKT", "SMB", "HML", "RMW", "CMA"}

标准五因子 Fama-French 定义，与固定版本源实现一致。

constexpr std::string_view fincore::brinson_allocation_column = {"allocation"}

Brinson 配置效应列的名称。

constexpr std::string_view fincore::brinson_benchmark_return_column{"benchmark_return"}

Brinson 基准收益列的名称。

constexpr std::string_view fincore::brinson_interaction_column = {"interaction"}

Brinson 交互效应列的名称。

constexpr std::string_view fincore::brinson_portfolio_return_column{"portfolio_return"}

Brinson 组合收益列的名称。

constexpr std::string_view fincore::brinson_selection_column = {"selection"}

Brinson 选择效应列的名称。

constexpr std::string_view fincore::brinson_total_column = {"total"}

Brinson 总效应列的名称。

constexpr std::string_view fincore::factor_attribution_component_column{"component"}

归因摘要中成分标签列的名称。

constexpr std::string_view fincore::factor_attribution_contribution_column{"contribution"}

归因摘要中贡献值列的名称。

constexpr std::string_view fincore::factor_prediction_column = {"predicted_returns"}

预测收益列的名称。

constexpr std::string_view fincore::factor_regression_alpha_name = {"alpha"}

用于回归截距的标签。

constexpr std::string_view fincore::factor_regression_coefficient_column{"coefficient"}

系数帧中系数值列的名称。

constexpr std::string_view fincore::factor_regression_factor_column = {"factor"}

系数帧中因子标签列的名称。

constexpr std::string_view fincore::factor_regression_fitted_column{"fitted_returns"}

拟合收益列的名称。

constexpr std::string_view fincore::factor_regression_residual_column{"residuals"}

残差列的名称。

constexpr std::string_view fincore::style_asset_column = {"asset"}

暴露表中存放资产标识的字符串列名称。

constexpr std::string_view fincore::style_attribution_contribution_column{"contribution"}

存放风格归因贡献的 double 列名称。

constexpr std::string_view fincore::style_attribution_residual_name = {"residual"}

风格归因结果中残量行的名称。

constexpr std::string_view fincore::style_equal_weight_column = {"equal_weight"}

等权风格列的名称。

constexpr std::string_view fincore::style_growth_column = {"growth"}

成长风格列的名称。

constexpr std::string_view fincore::style_high_column = {"high"}

高波动风格列的名称。

constexpr std::string_view fincore::style_large_column = {"large"}

大盘规模风格列的名称。

constexpr std::string_view fincore::style_loser_column = {"loser"}

动量输家风格列的名称。

constexpr std::string_view fincore::style_low_column = {"low"}

低波动风格列的名称。

constexpr std::string_view fincore::style_mid_column = {"mid"}

中盘规模风格列的名称。

constexpr std::string_view fincore::style_name_column = {"style"}

存放风格名称的字符串列名称。

constexpr std::string_view fincore::style_return_column = {"return"}

存放风格或组合收益的 double 列名称。

constexpr std::string_view fincore::style_small_column = {"small"}

小盘规模风格列的名称。

constexpr std::string_view fincore::style_value_column = {"value"}

价值风格列的名称。

constexpr std::string_view fincore::style_winner_column = {"winner"}

动量赢家风格列的名称。