Skip to content

Instantly share code, notes, and snippets.

@markqiu

markqiu/utils 代码注释.md

Created April 25, 2024 11:08
Show Gist options
  • Save markqiu/f173a78eadf35a8bcc02ee0e44353cb1 to your computer and use it in GitHub Desktop.
Save markqiu/f173a78eadf35a8bcc02ee0e44353cb1 to your computer and use it in GitHub Desktop.
Download ZIP
utils 代码注释
Raw
utils 代码注释.md
命名空间 函数名称 功能说明 入参及说明 出参及说明
services.utils create_empyt_price_dataframe 创建一个空的价格数据DataFrame。 stock_codes: set[str]
股票代码集合。		 pd.DataFrame
创建的空的价格数据DataFrame。
services.utils get_price_data 获取价格数据。 stock_codes: set[str]
股票代码集合。
observe_time: str
观察时间。
event_type: str
事件类型。		 pd.DataFrame
获取的价格数据。
services.utils filter_by_symbols 根据股票代码过滤DataFrame。 df: pd.DataFrame
需要过滤的DataFrame。
symbol_list: list
股票代码列表。		 pd.DataFrame
过滤后的DataFrame。
services.utils get_price_data_for_code 获取指定股票代码的价格数据。 reader: object
数据读取器。
code: str
股票代码。
observe_time: str
观察时间。		 pd.DataFrame
获取的价格数据。
services.utils get_backup_price_data 获取备份的价格数据。 client: object
客户端对象。
code: str
股票代码。		 pd.DataFrame
获取的备份价格数据。
services.utils process_price_data 处理价格数据。 event_type: str
事件类型。
reader: object
数据读取器。
stock_codes: set[str]
股票代码集合。
observe_time: str
观察时间。		 pd.DataFrame
处理后的价格数据。
services.utils get_stock_codes 从DataFrame中获取股票代码。 df: pd.DataFrame
DataFrame对象。
column_name: str
列名。		 list[str]
获取的股票代码列表。
services.utils merge_dependencies 合并依赖项。 df: pd.DataFrame
DataFrame对象。
`good_price: pd.DataFrame		 None<br>好价格数据（可选）。<br>risk_control: pd.DataFrame
services.utils merge_latest_price_data 获取最新的价格数据并合并到持仓计划DataFrame中。 portfolio_df: pd.DataFrame
当前的持仓计划DataFrame。
symbols: set[str]
需要查询价格的证券代码集合。
observation_time: str
观察时间点，用于获取价格数据。
event_type: str
事件类型，用于指定价格数据的获取方式。		 pd.DataFrame
合并了最新价格数据的持仓计划DataFrame。
services.交易管理.params crate_empty_trade_plan 创建并返回一个空的交易计划数据帧。 observe_time: str，观察时间，将用作数据帧的索引。 empty_trade_plan_df: pandas.DataFrame，包含一个空的交易计划的表格数据。
services.交易管理.utls merge_price_data 将股票价格数据与目标数据框按证券代码合并 df (pd.DataFrame): 目标数据框
price_data (pd.DataFrame): 股票价格数据框		 pd.DataFrame：合并后的数据框
services.交易管理.utls merge_holdings_data 将持仓数据与交易计划数据框按证券代码合并，并填充成本价 plan (pd.DataFrame): 交易计划数据框
holdings (pd.DataFrame): 持仓数据框		 pd.DataFrame：合并后的交易计划数据框
services.交易管理.utls merge_previous_trade_data 将之前交易数据、交易流水与交易计划数据框合并，计算相关指标并填充缺失值 observe_time (str): 观测时间
plan (pd.DataFrame): 交易计划数据框
plan_ptr (pd.DataFrame): 之前交易数据
transaction_flow (pd.DataFrame): 交易流水		 pd.DataFrame：合并后的交易计划数据框
services.交易管理.utls set_index_and_return 为数据框设置日期索引（观察时间），并返回 plan (pd.DataFrame): 数据框
observe_time (str): 观察时间		 pd.DataFrame：设置索引后的数据框
services.交易管理.utls filter_stocks 根据控制类型筛选股票数据 df (pd.DataFrame): 股票数据框
control_type (str): 控制类型		 pd.DataFrame：筛选后的股票数据框
services.交易管理.utls safe_division 安全除法，当除数为0时返回0 x (float): 被除数
y (float): 除数		 float：计算结果或0
services.交易管理.utls create_sell_plan 根据持仓、持仓计划和旧交易计划创建卖出计划 持仓_CTR (pd.DataFrame): 持仓数据
持仓计划_CTR (pd.DataFrame): 持仓计划数据
old_trade_plan (pd.DataFrame): 旧交易计划
observe_time (str): 观察时间
event_type (str): 事件类型		 pd.DataFrame：卖出计划数据框
services.交易管理.utls cal_build_plan 根据观察时间、参数计算并构建交易计划 plan (pd.DataFrame): 交易计划数据框
observe_time (str): 观察时间
params (dict): 参数		 pd.DataFrame：计算后的交易计划数据框
services.交易管理.utls extract_symbol_list 从多个数据框中提取并去重证券代码 持仓计划_CTR (pd.DataFrame): 持仓计划数据
持仓_CTR (pd.DataFrame): 持仓数据
交易管理_PTR (pd.DataFrame): 交易管理数据		 list[str]：去重后的证券代码列表
services.交易管理.utls update_summary_status 更新汇总计划的状态 old_plan (pd.DataFrame): 旧交易计划数据框 pd.DataFrame：更新状态后的交易计划数据框
services.交易管理.utls filter_trade_plan_by_active_stocks 根据活跃股票代码过滤交易计划 持仓_CTR (pd.DataFrame): 持仓数据
持仓计划_CTR (pd.DataFrame): 持仓计划数据
交易流水_CTR (pd.DataFrame): 交易流水数据
old_trade_plan (pd.DataFrame): 旧交易计划		 pd.DataFrame：过滤后的交易计划数据框
services.交易管理.utls final_merge_trade_plans 合并卖出计划、新交易计划、更新后交易计划，排序、设置索引 sell_plan_df (pd.DataFrame): 卖出计划
new_trade_plan (pd.DataFrame): 新交易计划
updated_trade_plan (pd.DataFrame): 更新后交易计划
observe_time (str): 观察时间		 pd.DataFrame：最终交易计划数据框
services.交易管理.utls fill_missing_stock_names 填充最终交易计划中缺失的证券名称 final_trade_plan (pd.DataFrame): 最终交易计划
交易管理_PTR (pd.DataFrame): 交易管理数据
持仓计划_CTR (pd.DataFrame): 持仓计划数据		 pd.DataFrame：填充证券名称后的交易计划数据框
services.交易管理.utls set_execution_status 根据条件设置交易计划的执行状态 df (pd.DataFrame): 交易计划数据框 pd.DataFrame：设置执行状态后的交易计划数据框
services.交易管理.utls initialize_build_plan 初始化构建交易计划的数据框 plan_df (pd.DataFrame): 交易计划数据框 pd.DataFrame：初始化后的交易计划数据框
services.交易管理.utls merge_dataframes 合并两个数据框，按证券代码填充缺失值 df1 (pd.DataFrame): 数据框1
df2 (pd.DataFrame): 数据框2		 pd.DataFrame：合并并填充缺失值后的数据框
services.交易管理.utls calculate_and_adjust_plan_shares 计算并调整交易计划的股票数量 df (pd.DataFrame): 交易计划数据框 pd.DataFrame：调整股票数量后的交易计划数据框
services.好价格.utils get_unique_stock_codes 从多个DataFrame中提取唯一的证券代码列表。 dataframes：一个包含多个DataFrame的列表，其中每个DataFrame应包含证券代码。 一个包含所有唯一证券代码的列表。
services.好价格.utils get_latest_annual_report_dates 获取最近观察点的年报报告期。 observe_time：观察点的时间字符串，格式为YYYY-MM-DD。
symbols：证券代码字符串，一般以"sh"或"sz"开头，后跟6位数字。		 如果找到最近的年报报告期，则返回日期字符串（YYYY-MM-DD），否则返回None。
services.持仓计划.utils finalize_merge_trades 整合并结算交易数据，计算每只证券的总成交金额、总成交数量、成交均价和最后一次成交时间。 trading_data: pandas.DataFrame
包含交易数据的DataFrame，预期包含的列有：证券代码、成交金额、成交数量、交易方向和成交时间。		 pandas.DataFrame
包含每只证券的结算数据，列包括证券代码、成交金额合计、成交数量合计、成交均价、成交时间以及交易方向。
services.持仓计划.utils prepare_current_portfolio_from_previous 从上期持仓计划继承并更新数据，构建本期持仓计划基础。
  • prev_portfolio: DataFrame, 上一期的持仓计划。
  • trades: DataFrame, 最新的交易记录。
  • obs_time: datetime, 观察时间点，用于更新最新交易时间。
  • position_ctr: DataFrame, 默认持仓设置，用于新标的初始化。
  • columns: list, 持仓计划所需的列名列表。
 DataFrame, 更新后的持仓计划，作为本期持仓计划的基础。
services.持仓计划.utils add_t1_postfix_and_copy 给指定DataFrame添加_T1后缀，并复制指定的列。
  • df: pandas.DataFrame对象，需要处理的数据框。
 pandas.DataFrame对象，已添加新列并复制了指定列的数据框。
services.持仓计划.utils merge_or_set_default_position 基于持仓_CTR进行处理。如果持仓_CTR不为空，则通过"证券代码"合并两个数据帧；如果为空，则为持仓计划_PTR的"持有股数"和"成本价"设定默认值0。 持仓计划_PTR: Pandas DataFrame，表示持仓计划的数据帧，包含至少"证券代码"列。
持仓_CTR: Pandas DataFrame，表示当前持仓的数据帧，包含至少"证券代码"、"持有股数"、"成本价"和"收盘价"列。		 Pandas DataFrame: 表示处理后的持仓计划数据帧，会根据持仓_CTR的情况进行合并或设置默认值。
services.持仓计划.utils update_portfolio_plan 根据交易流水更新持仓计划。 - 持仓计划_PTR: pd.DataFrame 类型，包含当前的持仓计划信息。
- 交易流水_CTR: pd.DataFrame 类型，包含交易流水信息。
- observe_time: 时间戳，表示当前观察的时间点。		 更新后的持仓计划DataFrame。
services.持仓计划.utils get_balance_base 根据指定的仓位平衡模式计算基础平衡仓位。 选股票_CTR： pandas.DataFrame对象，包含选中的股票及其控制信号。
params: 包含仓位平衡模式和最大持股数等参数的对象。		 返回值:
int，根据仓位平衡模式计算得到的基础平衡仓位数量。
services.持仓计划.utils filter_and_prepare_stocks_for_portfolio 根据止盈止损条件、好价格原则和风控信号筛选和准备股票，以制定持仓计划。 - portfolio_plan (pd.DataFrame): 持仓计划PTR，用于判断是否有持仓，进行止盈止损。包含证券代码、持仓状态等信息。
- stock_signals (pd.DataFrame): 选股信号，包含证券代码、排名等信息。
- params (Params): 持仓计划参数，包含止盈点、止损点等参数。
- good_price (pd.DataFrame): 好价格信号，可选，用于增强股票筛选逻辑。
- risk_control (pd.DataFrame): 风控信号，可选，用于控制风险，如避开有风险的股票。		 - pd.DataFrame: 处理后的信号，可用来制定持仓计划CTR。包含经过筛选后的股票信息。
services.持仓计划.utils apply_stop_loss_profit 应用止盈止损规则，更新持仓计划中的股票是否符合继续持有的条件。 - portfolio_plan (pd.DataFrame): 当前持仓计划。包含股票的成本价和收盘价等信息。
- params: 包含止盈点和止损点的参数对象。用于设定触发止盈或止损的条件。		 - pd.DataFrame: 更新后的持仓计划，标记了不符合持有条件的股票。新增了"涨跌幅"和"涨跌幅状态"两列，其中"涨跌幅状态"列指示股票应止盈、止损还是继续持有。
services.持仓计划.utils filter_stocks_by_management_mode 根据股票管理模式和持有情况筛选股票。 - stock_signals (pd.DataFrame)：
合并后的股票信号，包括风控、好价格信号和持有股数。此数据帧应包含证券代码、是否风险控制、是否好价格、当前持有股数等列。
- params: 包含股票管理模式和最大持股数的参数对象。预期此对象有股票管理模式（如“风险控制模式”或“最大化持仓模式”）和最大持股数属性。
- portfolio_plan (pd.DataFrame)：
投资组合计划，包含证券代码和持有股数等信息。用于确定当前持有的股票。		 - pd.DataFrame：
根据管理模式和持有情况筛选后的股票信号。返回的数据帧将包含满足特定筛选条件的股票信息。
services.持仓计划.utils format_holdings 格式化投资组合数据，以便于观察和分析 holdings: 原始投资组合数据
observe_time: 观察的时间点
columns: 需要保留并在结果中显示的列名列表		 格式化后的投资组合数据，包含了指定的列，并进行了日期格式化、零仓位移除等处理
services.持仓计划.utils get_stock_lists 根据选股票控制台和持仓计划指针获取现有持仓和新建仓的股票列表 选股票_CTR: 包含股票信息的数据结构，至少包含“证券代码”列
持仓计划_PTR: 包含当前持仓信息的数据结构，至少包含“证券代码”列		 existing_holdings: 现有持仓的证券代码列表
new_positions: 待新建仓的股票信息DataFrame，不包含现有持仓的股票
services.持仓计划.utils calculate_allocation_percentages 计算并返回当前期和上一期的股票类资产配置比例 资产配置_CTR: 包含当前期资产配置信息的字典，其中应有一个键为"股票类资产比例"，其值为当前期股票类资产比例的百分数。 current_alloc_pct: 当前期股票类资产配置比例，为浮点数。prev_alloc_pct: 上一期股票类资产配置比例，为浮点数。
services.持仓计划.utils initialize_holdings 初始化持仓DataFrame和已使用仓位 columns: 一个列表，指定DataFrame列的名称 existing_holdings: 一个空的DataFrame，用于记录持仓信息；used_position: 初始化为0的整数，表示已使用的仓位
services.持仓计划.utils calculate_positions 根据持有股票计算市值、当前仓位和已使用仓位 existing_holdings: 字典，包含股票的持有信息，至少包括“收盘价”和“持有股数”两个键。
total_asset: 浮点数，表示总资产。		 existing_holdings: 更新后的字典，包含每个股票的市值信息。
used_position: 浮点数，表示已使用的仓位比例。
services.持仓计划.utils process_existing_holdings 处理需要继续持有的股票，并计算已使用的仓位。 - portfolio_df: pandas.DataFrame，包含股票组合的信息，至少包含证券代码、收盘价和持有股数列。
- existing_holdings: list，需要继续持有的股票代码列表。
- total_asset: float，总的资产值。		 - existing_holdings: pandas.DataFrame，经过筛选后，包含需要继续持有的股票的详细信息，新增市值和当前仓位列。
- used_position: float，已使用的仓位比例。
services.持仓计划.utils allocate_new_purchases 为新买入的股票分配计划仓位和金额 new_positions: 字典，记录新股票位置信息
suggested_position: 浮点数，建议的股票仓位
total_asset: 浮点数，总资产
group_ratio: 浮点数，股票所在组资产占比
current_alloc_pct: 浮点数，当前资产类别占总资产百分比
total_asset_group: 浮点数，投资组总资产		 更新后的new_positions字典，包括计划仓位占比整体、分配金额、已使用金额、计划仓位占比本类别、计划仓位占比本分组等信息。
services.持仓计划.utils calculate_suggested_position 根据可用仓位和参数设置计算每只新买入股票的建议仓位。 - current_alloc_pct (float): 资产配置建议仓位，表示投资组合中该资产类别的百分比。\n- available_position (float): 可用的仓位比例，表示可用于购买新股票的资产比例。\n- params: 包含单只股票最大投资仓位、仓位平衡基准等参数的对象。其中，\n - 单只股票最大投资仓位 (float): 表示单只股票可以持有的最大仓位百分比。\n - 仓位平衡基准 (int): 用于平衡仓位的基数。\n- balance_base (int): 仓位平衡基准，用于计算每只股票应该占据的理论仓位比例。\n- existing_holdings_count (int): 已保持的股票数量。 - float: 计算得到的每只新买入股票的建议仓位比例，此比例表示购买新股票时应使用的资产百分比。
services.持仓计划.utils integrate_initial_holdings 在初次制定持仓计划时整合账户中已有的持仓股票 - rebalanced_holdings (pd.DataFrame): 更新后的持仓数据，包含了投资者想要的新的持仓配置。
- holdings_df (pd.DataFrame): 实际持仓数据，即当前的持仓情况，包含了持有股数和收盘价等信息。		 - pd.DataFrame: 更新后的持仓数据，此数据包含了已有持仓的初始市值和已使用金额的更新信息。
services.持仓计划.utils update_investment_progress 更新投资进度 holdings: 字典或类似字典的数据结构，包含投资信息，需要有"已使用金额"和"分配金额"两个键。 更新后的holdings，添加了"投资进度"这一键值，表示投资的进度百分比（保留两位小数），范围在0-100之间。
services.持仓计划.utils adjust_dates_and_positions 调整日期和仓位变化的函数。 -holdings: 包含仓位和分配金额信息的DataFrame，其中应至少包含“分配金额”和“分配金额_T1”两列。
- observe_time: 观察到仓位变化的日期，格式应与holdings中其他日期列相匹配。		 返回已更新的holdings DataFrame，其中包含最新的调整日期。
services.持仓计划.utils format_date_columns 格式化指定的日期列 -holdings (包含日期数据的DataFrame)
- date_columns (需要格式化的日期列的名称列表)		 格式化后的DataFrame，其中指定的日期列已被转换为datetime类型
services.持仓计划.utils remove_zero_positions 移除仓位占比为0的标的 holdings: 一个字典或者DataFrame，包含标的及其对应的计划仓位占比信息。 返回一个新的字典或者DataFrame，移除了仓位占比为0的标的。
services.持仓计划.utils merge_security_names 根据持仓计划和选股票数据，合并证券代码和证券名称到一个字典中。 - 持仓计划_PTR (DataFrame): 包含持仓计划的数据，至少包含"证券代码"和"证券名称"两列。
  • 选股票_CTR (DataFrame): 包含选股票的数据，至少包含"证券代码"和"证券名称"两列。 | dict: 一个字典，键是证券代码，值是证券名称。 | | services.选股票.base_utils | get_single_day_market_data | 获取指定交易日的市场数据 | reader (数据读取接口), factor_names (市场因子名称列表), trade_date (交易日期), symbols (股票代码列表), dropna_factors (需删除含空值列的因子名称列表) | DataFrame 包含市场数据 | | services.选股票.base_utils | get_financial_data | 获取指定期间的财务指标数据 | reader (数据读取接口), factor_names (财务因子名称列表), start_date (开始日期), trade_date (结束日期), report_dates (报告日期列表), symbols (股票代码列表) | DataFrame 包含财务指标数据 | | services.选股票.base_utils | financial_factor | 通用财务因子函数 | reader (数据读取接口), trade_date (交易日期), currently_listed_companies (当前上市公司的列表), factor_name (财务因子名称), num_period (时间周期), filter_type ("same_period" 或其他过滤方式) | DataFrame 包含财务因子数据 | | services.选股票.base_utils | calculate_trimmed_statistic | 计算给定数据的修剪均值或修剪中位数，支持标准差方法、四分位数范围（IQR）方法和百分位数方法 | data (包含数据的一维数组或列表), method ("std", "iqr", 或 "percentile"), lower_bound (下界值或标准差倍数), upper_bound (上界值或标准差倍数), use_median (是否计算修剪中位数，默认为 False) | 修剪后的均值或中位数 | | services.选股票.base_utils | is_single_day_data | 检查数据是否为单日数据 | data (DataFrame，包含财务数据), date_column (日期列的名称，默认为 "timestamp") | 布尔值，表示是否为单日数据 | | services.持仓计划.base_utils | calculate_start_date | 计算开始日期 | trade_date (交易日期), years_back (回溯年数) | 开始日期 |
    | services.持仓计划.base_utils | get_filtered_report_dates | 获取过滤后的报告日期 | trade_date (交易日期), num_periods (报告日期的数量), filter_type ("end_of_year"/"same_period"/"all") | 筛选后的报告日期列表 |
    | services.持仓计划.base_utils | remove_non_positive_values | 移除指定指标非正值的数据 | market_data (包含市场数据的 DataFrame), indicator_key (要检查的指标列名) | 清洗后的 DataFrame |
    | services.持仓计划.base_utils | calculate_growth_rate | 计算增长率（复合增长率或算术平均增长率） | profits (利润序列), n_years (年数), method ("CAGR"/"average") | 增长率 |
    | services.持仓计划.base_utils | get_multi_year_data | 获取过去n年的财务数据或因子计算结果 | reader (数据读取接口), factor_or_function (财务因子名称或执行因子计算的函数), trade_date (计算数据的截止日期), selected_symbols (股票代码列表), n_years (考虑的年数) | 多年的财务数据或因子计算结果的列表 |
    | services.持仓计划.base_utils | calculate_average_from_data | 计算提供的数据列表的均值 | df (包含多年财务数据或因子计算结果的DataFrame) | 计算得到的均值的pandas DataFrame |
    | services.持仓计划.base_utils | get_multi_year_single_day_data | 获取过去n年的数据 | reader (数据读取接口), factor_name (因子名称或列表), trade_date (计算数据的截止日期), selected_symbols (股票代码列表), n_years (考虑的年数), dropna_factors (需删除含空值列的因子名称列表) | 多年每日数据或因子计算结果的列表 |
    | services.持仓计划.base_utils | prepare_query_parameters | 准备SQL查询所需的参数 | start_date (开始日期字符串), end_date (结束日期字符串), symbol_list (股票代码列表) | 开始时间、结束时间、股票代码条件字符串 |
    | services.持仓计划.base_utils | convert_code_to_sql | 将特定格式的代码字符串转换为SQL更新语句列表 | code: 需要转换的代码字符串 | 返回一个由多条SQL更新语句组成的字符串，每条语句用于更新t表中指定列的数据，根据symbol上下文进行分组 | | services.持仓计划.factor_analysis | calculate_financial_growth_rate | 计算指定财务指标的同比增长率，单位：%。 | reader: 数据读取接口
    trade_date: 交易日期
    currently_listed_companies: 当前上市公司列表
    factor_name: 要分析的财务指标，默认为'净利润TTM'
    num_periods: 考虑的时期数，默认为8，用于计算增长率
    filter_type: 筛选类型，默认为'same_period' | 返回同比增长率的 DataFrame。 |
    | services.持仓计划.factor_analysis | calculate_dividend_ratio_factor | 计算股息率因子 | reader: 数据读取接口
    trade_date: 交易日期
    symbols: 股票代码列表 | 返回股息率因子的 DataFrame。 |
    | services.持仓计划.factor_analysis | calculate_dividend_ratio_years_factor | 计算近N年股息率因子 | reader: 数据读取接口
    trade_date: 交易日期
    symbols: 股票代码列表
    years: 年数，默认为3 | 返回近N年股息率因子的 DataFrame。 |
    | services.持仓计划.factor_analysis | calculate_dividend_factor | 计算股息因子，单位：元 | reader: 数据读取接口
    trade_date: 交易日期
    symbols: 股票代码列表 | 返回股息因子的 DataFrame。 |
    | services.持仓计划.factor_analysis | calculate_dividend_payout_ratio | 计算股息支付率，单位：%。低股息支出率可能意味着公司正在将大部分利润再投资于业务中，以实现增长。高股息支出率可能表明公司向股东支付了较多的股息，但这也可能意味着较少的利润被再投资回公司。 | reader: 数据源读取器
    trade_date: 交易日期
    currently_listed_companies: 当前上市公司列表
    factor_name: 财务因子名称，默认为'净利润TTM'
    num_period: 时期数，默认为1 | 返回一个包含股息支付率的DataFrame。 |
    | services.持仓计划.factor_analysis | calculate_debt_to_equity_ratio | 计算负债净值比，单位：% | reader: 数据源读取器
    trade_date: 交易日期
    symbols: 股票代码列表 | 返回负债净值比的 DataFrame。 |
    | services.持仓计划.factor_analysis | calculate_tax_pre_net_rate | 计算税前净利率，单位：% | reader: 数据源读取器
    trade_date: 交易日期
    symbols: 股票代码列表 | 返回税前净利率的 DataFrame。 |
    | services.持仓计划.factor_analysis | calculate_n_year_avg_growth | 计算N年的增长率，可以是复合增长率或算术平均增长率，单位：% | finance_df: 包含净利润数据的 DataFrame
    n_years: 考虑的年份范围
    method: 计算方法，默认为"CAGR" | 返回包含N年增长率的 DataFrame。 |
    | services.持仓计划.factor_analysis | calculate_relative_price_change | 计算指定股票相对于基准股票的价格变化百分比 | reader: 数据读取接口
    symbols: 要分析的股票代码列表
    trade_date: 观察的交易日期
    base_symbol: 基准股票代码
    lookback_period: 回望期间（月） | 包含相对价格变化百分比的 DataFrame |
    | services.持仓计划.factor_analysis | period_expense_margin_ratio | 期间费用毛利比 | reader: 数据读取接口
    trade_date: 交易日期
    years: 年数
    selected_symbols: 选中的股票代码列表 | 返回期间费用毛利比的 DataFrame（单位：%） |
    | services.持仓计划.factor_analysis | calculate_liquid_assets_to_liquid_debt | 流动资产比流动负债 | reader: 数据读取接口
    trade_date: 交易日期
    selected_symbols: 选中的股票代码列表 | 返回流动资产比流动负债的 DataFrame（单位：%） |
    | services.持仓计划.factor_analysis | debt_equity_ratio | 负债权益比率 | reader: 数据读取接口
    trade_date: 交易日期
    years: 年数
    selected_symbols: 选中的股票代码列表 | 返回负债权益比率的 DataFrame（单位：%） |
    | services.持仓计划.factor_analysis | capital_outlay_to_retained_profits | 资本支出占比净利润 | reader: 数据读取接口
    trade_date: 交易日期
    years: 年数
    selected_symbols: 选中的股票代码列表 | 返回资本支出占比净利润的 DataFrame（单位：%） |
    | services.持仓计划.factor_analysis | income_tax_rate | 所得税率 | reader: 数据读取接口
    trade_date: 交易日期
    years: 年数
    selected_symbols: 选中的股票代码列表 | 返回所得税率的 DataFrame（单位：%） |
    | services.持仓计划.factor_analysis | interest_expense_to_trading_profit | 利息支出占比营业利润 | reader: 数据读取接口
    trade_date: 交易日期
    years: 年数
    selected_symbols: 选中的股票代码列表 | 返回利息支出占比营业利润的 DataFrame（单位：%） |
    | services.持仓计划.factor_analysis | deprecition_and_amortize_to_gross_margin | 折旧与摊销占比毛利 | reader: 数据读取接口
    trade_date: 交易日期
    years: 年数
    selected_symbols: 选中的股票代码列表 | 返回折旧与摊销占比毛利的 DataFrame（单位：%） |
    | services.持仓计划.factor_analysis | calculate_total_borrow_to_net_liquid_assets | 总借款比净流动资产，单位：% | reader：数据读取接口； trade_date：交易日期； selected_symbols：股票代码列表 | 返回包含总借款比净流动资产比率的pandas DataFrame，每一列为一个股票代码及其对应的比率值。 |
    | services.持仓计划.factor_analysis | calculate_interest_debt | 计算有息负债，单位：元 | reader：数据读取接口； trade_date：交易日期； selected_symbols：股票代码列表 | 返回包含有息负债金额的pandas DataFrame，每一列为一个股票代码及其对应的有息负债金额。 |
    | services.持仓计划.factor_analysis | calculate_company_value | 计算企业价值，单位：元 | reader：数据读取接口； trade_date：交易日期； selected_symbols：股票代码列表 | 返回包含企业价值的pandas DataFrame，每一列为一个股票代码及其对应的企业价值。 |
    | services.持仓计划.factor_analysis | calculate_company_income_rate | 计算企业收益率，单位：% | reader：数据读取接口； trade_date：交易日期； selected_symbols：股票代码列表 | 返回包含企业收益率的pandas DataFrame，每一列为一个股票代码及其对应的企业收益率。 |
    | services.持仓计划.factor_analysis | calculate_traded_market_value | 计算流通市值，单位：元 | reader：数据读取接口； trade_date：交易日期； selected_symbols：股票代码列表 | 返回包含流通市值的pandas DataFrame，每一列为一个股票代码及其对应的流通市值。 |
    | services.持仓计划.factor_analysis | calculate_price_change_from_max | 计算股价与过去N个月最高价的涨跌百分比 | reader：数据读取接口； trade_date：交易日期； selected_symbols：股票代码列表； num_months：过去的月份数 | 返回包含涨跌百分比的DataFrame，每一列为一个股票代码及其对应的涨跌百分比。 |
    | services.持仓计划.factor_analysis | calculate_net_current_assets | 计算净流动资产，单位：元 | reader：数据读取接口； trade_date：交易日期； selected_symbols：股票代码列表 | 返回包含净流动资产的pandas DataFrame，每一列为一个股票代码及其对应的净流动资产金额。 |
    | services.持仓计划.factor_analysis | calculate_total_long_term_debt | 计算长期负债合计，单位：元 | reader：数据读取接口； trade_date：交易日期； selected_symbols：股票代码列表 | 返回包含长期负债合计的pandas DataFrame，每一列为一个股票代码及其对应的长期负债合计金额。 |
    | services.持仓计划.factor_analysis | calculate_market_cap_to_asset_ratio | 计算总市值相对于特定类型资产的比率，单位：% | reader：数据读取接口； trade_date：交易日期； selected_symbols：股票代码列表； asset_type：资产类型 | 返回包含每个股票市值比特定类型资产比率的pandas DataFrame，每一列为一个股票代码及其对应的比率值。 |
    | services.持仓计划.factor_analysis | calculate_peg | 计算价格盈利增长比率（PEG），单位：% | reader：数据读取接口； trade_date：交易日期； selected_symbols：股票代码列表； growth_period_years：年数 | 返回包含每个股票PEG值的pandas Series，每一列为一个股票代码及其对应的PEG值。 |
    | services.持仓计划.factor_analysis | calculate_debt_to_stockholder_equities | 计算负债占股东权益的比率，单位：% | reader：数据读取接口； trade_date：交易日期； selected_symbols：股票代码列表 | 返回包含每个股票负债占股东权益比率的pandas DataFrame，每一列为一个股票代码及其对应的比率值。 |
    | services.持仓计划.factor_analysis | calculate_expect_income_increase_rate | 计算预期收益增长率，单位：% | reader：数据读取接口； trade_date：交易日期； selected_symbols：股票代码列表 | 返回包含预期收益增长率的pandas DataFrame，每一列为一个股票代码及其对应的预期收益增长率。 |
    | services.持仓计划.factor_analysis | calculate_adjust_factor | 计算利率调整因子 | reader：数据读取接口； trade_date：交易日期 | 返回利率调整因子的数值。 |
    | services.持仓计划.factor_analysis | calculate_inherent_value | 计算股票的内在价值因子 | - reader: 数据读取器，用于获取财务数据和市场数据
    - trade_date: 交易日期
    - pe: 市盈率
    - safe: 安全因子
    - selected_symbols: 选择的股票代码列表 | - inherent_value: 返回一个DataFrame，包含选定股票的内在价值 |
    | services.持仓计划.factor_analysis | calculate_indicator_key_to_market | 计算内在价值与市值的比例指标 | - reader: 数据读取器，用于获取财务数据和市场数据
    - trade_date: 交易日期
    - pe: 市盈率
    - safe: 安全因子
    - selected_symbols: 选择的股票代码列表 | - indicator_key_to_market: 返回一个DataFrame，包含选定股票的内在价值与市值比例 |
    | services.持仓计划.factor_analysis | calculate_Debt_net_worth_ratio | 计算负债净值比（负债合计/股东权益合计），单位：% | - reader: 数据读取器，用于获取财务数据
    - trade_date: 交易日期
    - selected_symbols: 选择的股票代码列表 | - Debt_net_worth_ratio: 返回一个DataFrame，包含选定股票的负债净值比 |
    | services.持仓计划.factor_analysis | calculate_trading_profit_to_all_profit | 计算营业利润TTM与利润总额TTM的比值，单位：% | - reader: 数据读取器，用于获取财务数据
    - trade_date: 交易日期
    - selected_symbols: 选择的股票代码列表 | - trading_profit_to_all_profit: 返回一个DataFrame，包含选定股票的营业利润比率 | | services.选股票.params | get_end_year | 计算观察时间所在的学习年份。若观察时间在5月及以后，认为是当前年份；否则为前一年。 | - observe_time: pendulum.Date, 观察的时间点，默认为当前日期。 | - int, 观察时间所在的学习年份。 | | services.选股票.params | get_all_periods | 计算给定开始和结束日期之间的所有时期。时期定义为从开始日期到结束日期每年的结束年份（包含开始年和结束年）。 | - start_date: pendulum.Date, 开始日期。
    - end_date: pendulum.Date, 结束日期。 | - list[int], 包含所有时期年份的列表。 | | services.选股票.params | stock_selection_output | 整合和处理股票选择结果，返回一个按日期和排名排序的DataFrame。 | - stock_selection_res: list[pd.DataFrame], 包含股票选择结果的DataFrame列表。 | - pd.DataFrame, 整合并按日期和排名排序后的股票选择结果。 | | services.选股票.stock_selector | get_still_active_companies | 获取在给定的交易日和交易日减去特定年份仍然上市的股票集合。 |
    • reader: 数据读取器对象，用于访问股票数据。
    • symbols: 股票代码列表。
    • trade_date: 指定的交易日（datetime 类型）。
    • years_offset: 从交易日向前回溯的年数。
    | 在两个日期都上市的股票集合。 | | services.选股票.stock_selector | select_stocks_based_on_financial_indicator | 根据给定财务指标数据选择股票。此函数允许使用不同的基准（如市场平均值或中位数）和阈值来筛选股票。 |
    • data: 包含财务指标数据的 DataFrame。
    • indicator_name: 用于筛选的财务指标的列名。
    • threshold: 用于筛选的阈值，可以是具体数值或百分比。
    • comparison_operator: 比较运算符，如 "<", ">", "<=", ">="。
    • use_median: 若为 True，则使用市场中位数作为比较基准。
    • apply_threshold_as_percentage: 若为 True，则将 threshold 解释为市场平均值或中位数的百分比。
    | 符合筛选条件的股票代码列表。 | | services.选股票.stock_selector | calculate_market_average | 计算市场平均值。 |
    • finance_pct: DataFrame，包含财务指标的百分比变化
    • market_avg_factor: 计算市场平均值时使用的因子，例如净利润增长率高于市场平均值的百分比
    • use_median: 计算市场平均值时使用的方法，例如百分位数或中位数
    | 计算后的市场平均值 | | services.选股票.stock_selector | filter_symbols_by_condition | 根据市场条件筛选符合条件的股票代码。 |
    • df: DataFrame，包含财务数据
    • column: 要分析的列名
    • selected_symbols: 已选股票列表
    • condition_desc: 中文条件描述（例如，'大于', '小于', '不大于', '不小于'）
    • value: 用于比较的值
    | 符合条件的股票列表 | | services.选股票.stock_selector | calculate_industry_median_and_filter | 根据财务指标和行业数据选择股票，使用条件映射进行筛选。 | - financial_data: 包含财务指标数据的 DataFrame。
    - industry_data: 包含行业分类的 DataFrame。
    - indicator_name: 用于筛选的财务指标的列名（可选）。
    - condition_desc: 条件描述（如 '大于', '小于', '不大于', '不小于'）。
    - benchmark_type: 使用 'median' 或 'mean' 作为行业基准。
    - selected_symbols: 一个可选的股票列表，用于进一步筛选。 | 返回符合筛选条件的股票代码列表。 | | services.选股票.stock_selector | create_stock_selection_dataframe | 创建并返回包含选定股票的 DataFrame。 | - reader: 数据读取接口，用于获取股票名称。
    - trade_date: 交易日期。
    - selected_symbols: 选定的股票代码列表。 | 返回包含股票代码、时间戳、排名和证券名称的 DataFrame。 | | services.选股票.stock_selector | filter_by_recent_yearly_growth | 筛选最近报告期指标值不小于最近年度指标值的股票。 | - reader: 数据读取接口。
    - trade_date: 交易日期。
    - selected_symbols: 已选股票列表。
    - factor_name: 分析的财务指标。
    - condition: 比较条件（如 "不小于"）。 | 返回符合条件的股票列表。 | | services.选股票.stock_selector | filter_non_st_stocks_over_period | 筛选过去N个月内未被ST或退市的股票。 | - reader: 数据读取器，用于获取股票因子数据。
    - end_date: 结束日期，格式为 "YYYY-MM-DD"。
    - months: 指定的月份数，用于定义查询的时间范围。
    - initial_symbols: 初始股票代码列表。 | 返回未在过去N个月内被ST或退市的股票代码列表。 | | services.选股票.stock_sort | sort_stock_strategy | 对股票进行排序的通用函数。 | - reader: 数据读取器。
    - trade_date (str): 交易日期。
    - df (pd.DataFrame): 待排序的DataFrame。
    - selected_symbols (list): 被选中的股票代码列表。
    - sort_by (str): 排序依据的字段名。
    - ascending (bool): 排序方式，True为升序，False为降序。
    - is_financial_factor (bool): 是否使用财务因子数据。 | - pd.DataFrame: 排序后的DataFrame。 | | services.选股票.utils | get_cnzvt | 从特定数据源获取数据 | - map: 包含需要查询的字段的字典
    - table: 需要查询的表名
    - reader: 用于执行查询的读取器对象
    - base_condition: 基本的查询条件
    - symbols_condition: 用于过滤符号的条件 | - 查询结果的数据帧（DataFrame） | | services.选股票.utils | get_financel_data | 获取财务数据 | - reader: 数据读取器对象
    - start_date: 开始日期
    - end_date: 结束日期
    - fields_map: 需要查询的字段及其别名的映射
    - report_date_list: 需要的报告日期列表，可选 | - 按指定字段获取的财务数据的数据帧（DataFrame） | | services.选股票.utils | sorting_method | 根据指定的字段对股票进行排序 | - reader: 数据读取器对象
    - selected_stocks: 已选择的股票数据
    - sort_df: 用于排序的数据框架
    - trade_date: 交易日期
    - sorting_fields: 用于排序的字段及其权重的字典
    - all_market_symbol: 所有市场的股票代码列表 | - 排序后的数据框架 | | services.选股票.utils | sort_and_write_to_excel | 统计入选次数，进行最终排序，并将结果写入Excel | - file_path: str，Excel文件的路径
    - screen_year_list: list，需要筛选的年份列表
    - params: object，包含各种参数的对象，例如回看时长
    - sort_columns: list，按哪些列进行排序 | 无 | | services.选股票.utils | filter_special_industries | 排除特定行业，返回一个包含需要排除的行业代码的列表 | 无 | list，需要排除的行业代码列表 | | services.选股票.utils | filter_industries | 根据指定的行业排除股票 | - reader: object，数据读取器
    - selected_stocks: DataFrame，待筛选的股票数据
    - trade_date: str，交易日期 | DataFrame，排除特定行业后的股票数据 | | services.选股票.utils | calculate_variation | 计算数据帧每列的变异系数 | - df: DataFrame，包含数值数据的数据帧 | Series，包含每列变异系数的结果 | | services.选股票.utils | calculate_condition | 根据阈值计算数据帧满足条件的行数 | - df: DataFrame，数据帧
    - number: int，数据帧中要检查的列数
    - threshold: float，阈值 | DataFrame，包含每行满足条件的计数 | | services.选股票.utils | create_year_info | 根据起始日期和结束日期创建年份信息。 | start_date (str): 开始日期，格式为YYYY-MM-DD。
    end_date (str): 结束日期，格式为YYYY-MM-DD。
    params (dict): 包含各种参数的字典，例如回看时长、跟踪时长等。 | 元组，包含报告期日期列表、筛选年份列表、开始时间、结束时间和筛选年份。 | | services.选股票.utils | delete_file | 删除指定路径的文件。 | file_path (str): 文件路径。 | 无 | | services.选股票.utils | format_date | 将日期字符串格式化为YYYY.MM.DDTHH:MM:SS格式。 | date (str): 日期字符串。 | 格式化后的日期字符串。 | | services.选股票.utils | get_etf_hfq_data | 获取ETF的复权日线数据。 | start_date (str): 开始日期，格式为YYYY-MM-DD。
    end_date (str): 结束日期，格式为YYYY-MM-DD。
    symbols (list[str]): 证券代码列表。
    ma_lengths (list[int]): 移动平均线长度列表。 | DataFrame，包含指定日期范围和指标的ETF数据。 | | services.选股票.utils | get_symbol_data | 获取指定日期范围内的所有股票代码。 | start_date (str): 开始日期，格式为YYYY-MM-DD。
    end_date (str): 结束日期，格式为YYYY-MM-DD。 | DataFrame，包含证券代码。 | | services.选股票.utils | percentile_trimmed_mean | 计算给定数据的修剪均值，即剔除掉指定百分位数之外的值后的平均值。 | s (pd.Series): 数据序列。
    lower_percentile (float, default=0.01): 下限百分位数，小于此值的数据将被剔除。
    upper_percentile (float, default=0.99): 上限百分位数，高于此值的数据将被剔除。 | 修剪均值。 | | services.选股票.utils | compute_cagr | 计算复合年增长率 | data (pd.Series): 一个包含N年数据的列表, 按年份顺序排列 (例如: [100, 105, 112, 120, 130] 代表从第一年到第五年的数据) | N年的复合年增长率 | | services.选股票.utils | get_bond_1d_kdata | 从数据库中获取指定日期范围和名称的债券每日行情数据。 | - reader：数据读取器对象，用于执行数据库查询。
    - start_date：开始日期，格式为字符串。
    - end_date：结束日期，格式为字符串。
    - name：债券名称，默认为"中债国债到期收益率：5年"。 | - pandas.DataFrame：包含债券行情数据的DataFrame，如果没有找到数据则返回空的DataFrame。 | | services.选股票.utils | get_industry_info | 获取指定股票或指定日期范围的行业信息。 | - reader：数据读取器对象，用于执行数据库查询。
    - start_date：开始日期，格式为字符串。
    - end_date：结束日期，格式为字符串，可选参数，默认为start_date。
    - symbols：股票代码列表，可选参数，默认为None。 | - pandas.DataFrame：包含股票行业信息的DataFrame。 | | services.选股票.utils | get_stock_selection_dates | 获取选股日的日期列表。 | - start_time：开始时间。
    - end_time：结束时间。
    - event_type：事件类型。
    - reader：数据读取器对象。 | - selection_dates：选股日的日期列表。 | | services.选股票.utils | filter_non_st_stocks | 过滤掉非ST和退市的股票。 | - reader：数据读取器对象。
    - current_date：当前日期。
    - initial_symbols：初始股票代码列表。 | - filtered_symbols：过滤后的股票代码列表。 | | services.选股票.utils | get_cnzvt_data | 从CNZVT数据集中获取特定条件的数据。 | - reader：数据读取器对象，用于执行数据库查询。
    - start_date：开始日期，格式为YYYY-MM-DD。
    - end_date：结束日期，格式为YYYY-MM-DD。
    - symbols：要查询的股票代码列表，格式为['xx','yy']。
    - report_dates：要查询的报告期日期列表，格式为['YYYYMMDD','YYYYMMDD']。
    - zvt_table：在CNZVT数据集中要查询的表格名称。
    - factor_names_str：要查询的因子名称字符串。 | 符合条件的数据结果集。 | | services.选股票.utils | has_dividend_in_last_year | 检查股票在截至 end_date 的过去一年中是否有股息。 | - reader：数据读取器对象，用于执行数据库查询。
    - end_date：截止日期，格式为YYYY-MM-DD。
    - symbols：要查询的股票代码列表，格式为['xx','yy']。 | 有一年股息记录的股票代码列表。 | | services.选股票.utils | has_dividend_in_date_range | 检查股票在start_date 至 end_date 的过去一年中是否有股息。 | - reader：数据读取器对象，用于执行数据库查询。
    - start_date：开始日期，格式为YYYY-MM-DD。
    - end_date：结束日期，格式为YYYY-MM-DD。
    - symbols：要查询的股票代码列表，格式为['xx','yy']。 | 字典，键为日期，值为在该日期过去一年有股息的股票代码列表。 | | services.选股票.utils | calculate_cagr | 计算过去若干年的指定列的复合增长率。 | - data：pandas DataFrame，行索引是报告期，列索引是股票代码，单元格的值是企业的各项指标。
    - column：str，需要计算复合增长率的列名。
    - years：int，计算复合增长率的年数，默认为5。 | growth_df - pandas DataFrame，包含每只股票的复合增长率。 | | services.选股票.utils | get_last_n_report_dates | 获取最近 N 个报告期的报告日期。 | - input_date：输入日期
    - num_periods：需要获取的报告期数量 | 报告日期列表 | | services.风险控制.utils | create_symbol_list | 创建并返回一个股票代码列表，由提供的DataFrames中所有不为None的DataFrame的股票代码唯一值组成 | *dataframes: pd.DataFrame | None - 一个或多个可能为None的pandas DataFrame对象，每个DataFrame应包含股票代码列 | list[str] - 一个包含所有不重复股票代码的列表 | | services.风险控制.utils | get_market_calendar_for_event | 根据事件类型和参数，获取给定事件相关的市场日历 | event - 事件对象，包含事件类型和相关数据
    params - 参数对象，应包含开始和结束日期（针对回测事件）
    reader - 读取器对象，用于从数据源获取市场日历和其他相关信息 | market_calendar, start_time, end_time - 市场日历的pandas DataFrame，以及根据事件类型确定的开始和结束时间 |
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment