绩效

现金流调整后收益率、披露上下文、收益率推断与绩效统计。

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

struct disclosure_context

由 render_disclosure() 渲染的展示元数据。

各字段为自由格式文本，不会被解释或校验。空字符串字段渲染为 unspecified，但空基准渲染为 none。

公共成员

std::string convention = "TWR"

收益率约定标签。

std::string sample_period

样本期描述。

std::string data_quality

数据质量描述。

std::string fees = "gross-of-fees"

费用口径标签。

std::string cashflows = "none"

现金流处理方式标签。

std::string benchmark

基准标签；为空时渲染为 "none"。

std::string risk_free

无风险利率描述。

bool annualized = true

数值是否年化。

std::vector<std::string> notes

额外备注，以 "; " 连接。

std::string return_type

收益率类型标签。

std::string units

单位标签。

std::string frequency

观测频率标签。

enum class fincore::fee_treatment

计算现金流调整后绩效时的费用处理方式。

取值：

enumerator net

按所提供的估值使用；费用不调整收益率。

enumerator gross

将费用加回到其所属期间的期末估值。

dataframe fincore::cashflow_adjusted_returns(const dataframe &valuations, const std::optional<dataframe> &cashflows = std::nullopt, const std::optional<dataframe> &fees = std::nullopt, fee_treatment treatment = fee_treatment::net, std::string_view value_column = "value", std::string_view amount_column = "amount", std::string_view timing_column = "timing", std::string_view fees_column = "fees")

为每一对相邻估值返回一个现金流调整后的简单收益率。

输出以每对估值中较晚的时间戳为索引，并将小数收益率存储在 returns 下。期间收益率为 (closing - end_flows) / (opening + start_flows) - 1；在 fee_treatment::gross 下，期末资本还包含记录在期末估值日的费用。现金流和费用必须落在估值日；同日的条目会相加，而首个估值日上的非零条目会被拒绝。

参数:

• valuations -- Valuation frame with a required double value_column, at least two rows and a strictly increasing, unique index. Values must be finite and non-negative, and every value except the last must be positive.

• cashflows -- Optional ledger with double amount_column and timing_column columns. Timing 1 marks a start-of-period flow and timing 0 an end-of-period flow.

• fees -- Optional fee ledger with a double fees_column.

• treatment -- Fee treatment used for closing valuations.

• value_column -- Column holding valuations in valuations.

• amount_column -- Column holding signed cashflow amounts in cashflows.

• timing_column -- Column holding the start/end timing flag in cashflows.

• fees_column -- Column holding fee amounts in fees.

抛出:

input_error -- If a column name is empty, the column is absent, not double or misaligned; the valuation index is not strictly increasing; a valuation is non-finite or negative; an opening valuation is not positive; a cashflow or fee date is absent from the valuation index; a timing flag is not 0 or 1; a nonzero cashflow or fee falls on the first valuation date; or a period capital base or return is not representable.

返回:

Cashflow-adjusted simple returns indexed by the later timestamp of each valuation pair.

double fincore::cashflow_adjusted_twr(const dataframe &valuations, const std::optional<dataframe> &cashflows = std::nullopt, const std::optional<dataframe> &fees = std::nullopt, fee_treatment treatment = fee_treatment::net, std::string_view value_column = "value", std::string_view amount_column = "amount", std::string_view timing_column = "timing", std::string_view fees_column = "fees")

返回复合后的现金流调整时间加权收益率。

复合过程将 cashflow_adjusted_returns() 返回的各期收益率按 1 + r 连乘后减去 1。

参数:

• valuations -- Valuation frame accepted by cashflow_adjusted_returns().

• cashflows -- Optional cashflow ledger accepted by cashflow_adjusted_returns().

• fees -- Optional fee ledger accepted by cashflow_adjusted_returns().

• treatment -- Fee treatment used for closing valuations.

• value_column -- Column holding valuations in valuations.

• amount_column -- Column holding signed cashflow amounts in cashflows.

• timing_column -- Column holding the start/end timing flag in cashflows.

• fees_column -- Column holding fee amounts in fees.

抛出:

input_error -- If cashflow_adjusted_returns() rejects the inputs or the compounded value is not representable.

返回:

Decimal cumulative time-weighted return over all periods.

double fincore::mwr(const dataframe &cashflows, std::optional<double> period = std::nullopt, std::string_view amount_column = "cashflow")

返回周期性现金流的资金加权收益率。

以行顺序而非时间戳作为期间轴。第一行为第零期，其后每一行都晚 period 个期间。零金额在位置确定后被丢弃。仅对恰好有一次符号变化的现金流求解利率。

参数:

• cashflows -- Frame whose rows are cashflow periods.

• period -- Optional positive finite interval between rows; defaults to 1.0.

• amount_column -- Double column of signed cashflow amounts.

抛出:

input_error -- If the column is invalid, fewer than two amounts are present, an amount is non-finite, or period is not positive and finite.

返回:

Decimal per-period internal rate of return, or NaN when the flows are not conventional or no representable root is found.

std::string fincore::render_disclosure(const disclosure_context &context)

返回确定性的、以换行分隔的披露块。

各行按以下顺序出现：convention、return type、units、frequency、sample period、data quality、fees、cashflows、benchmark、risk-free 和 annualized。非空的备注列表会追加末尾的 Notes: 行，其条目以 ; 连接；该最后一行没有尾随换行符。

参数:

context -- Disclosure values to render.

返回:

Plain-text disclosure block.

std::pair<double, double> fincore::sharpe_confidence_interval(const dataframe &returns, double risk_free = 0.0, double z = 1.96, std::string_view column = returns_column)

返回每期夏普比率的正态近似置信区间。

区间为 S - z * SE 到 S + z * SE，使用 sharpe_standard_error() 所描述的夏普比率和标准误。非 NaN 观测少于两个时返回 {NaN, NaN}。不进行年化。

参数:

• returns -- Frame containing periodic simple returns.

• risk_free -- Per-period risk-free rate subtracted from each return.

• z -- Normal quantile multiplier, such as 1.96 for a 95% interval.

• column -- Double column of returns.

抛出:

input_error -- If the column name is empty, the column is absent, not a double column, or does not match the frame index length.

返回:

Lower and upper interval bounds.

double fincore::sharpe_standard_error(const dataframe &returns, double risk_free = 0.0, std::string_view column = returns_column)

返回每期夏普比率的标准误。

每个非 NaN 观测都按 risk_free 平移。夏普比率为平移后的均值除以样本标准差（当该标准差至多为 1e-15 时取零），标准误为 sqrt((1 + 0.5 * S^2) / n)。非 NaN 观测少于两个时返回 NaN。不进行年化。

参数:

• returns -- Frame containing periodic simple returns.

• risk_free -- Per-period risk-free rate subtracted from each return.

• column -- Double column of returns.

抛出:

input_error -- If the column name is empty, the column is absent, not a double column, or does not match the frame index length.

返回:

Standard error of the per-period Sharpe ratio.

double fincore::standard_error_of_mean(const dataframe &values, std::string_view column = returns_column)

返回 column 样本均值的标准误。

丢弃 NaN 观测。结果为样本标准差（分母为 n - 1）除以 sqrt(n)。非 NaN 观测少于两个时返回 NaN。

参数:

• values -- Frame containing the observations.

• column -- Double column of observations.

抛出:

input_error -- If the column name is empty, the column is absent, not a double column, or does not match the frame index length.

返回:

Standard error in the same units as column.

double fincore::twr(const dataframe &returns, std::string_view column = returns_column)

返回 column 的总时间加权收益率。

对所有非 NaN 观测按 1 + r 连乘后减去 1。NaN 观测会被跳过；无穷值和小于等于 -1 的收益率按原样使用。空序列或仅含 NaN 的序列返回 0.0。

参数:

• returns -- Frame containing the return series.

• column -- Double column of periodic simple returns.

抛出:

input_error -- If the column name is empty, the column is absent, not a double column, or does not match the frame index length.

返回:

Decimal cumulative simple return.

double fincore::xirr(const dataframe &cashflows, std::string_view amount_column = "cashflow")

返回带日期现金流的年化内部收益率。

现金流按 UTC 日历日汇总并按日期排序；每日合计为零的会被丢弃。期间分数使用实际经过的天数除以；仅对恰好有一次符号变化的现金流求解利率，当没有可表示的根满足求解器的残差预算时，结果被拒绝。

参数:

• cashflows -- Frame whose index holds cashflow dates.

• amount_column -- Double column of signed cashflow amounts.

抛出:

input_error -- If the column is invalid, an amount is non-finite, or fewer than two distinct UTC cashflow dates are present.

返回:

Decimal annualized rate, or NaN when the flows are not conventional (not exactly one sign change) or no representable root is found.