finagg: Python 的金融聚合
finagg 是一个 Python 包,提供了流行且免费的金融 API 实现,用于将这些 API 的历史数据聚合到 SQL 数据库中的工具,以及将聚合数据转换为适用于分析和人工智能/机器学习的特征的工具。
- 文档:https://theogognf.github.io/finagg/
- PyPI:https://pypi.org/project/finagg/
- 代码库:https://github.com/theOGognf/finagg
快速开始
安装
使用 pip 安装最新稳定版本。
pip install finagg
从 GitHub 安装最新不稳定版本。
git clone https://github.com/theOGognf/finagg.git
pip install ./finagg/
可选择安装推荐的数据集(经济数据、公司财务、股票历史等)从第三方 API 到本地 SQL 数据库。
finagg install -ss economic -ts indices -z -r
安装过程会指导您如何获取每个需要的 API 的免费 API 密钥,并将这些 API 密钥写入本地 .env
文件以存储。
运行 finagg install --help
查看更多安装选项和详情。
基本用法
以下只是 finagg 的使用示例。查看文档了解所有支持的 API 和功能。
直接探索 API
这些方法需要互联网访问和 API 密钥/用户代理声明。
获取经济分析局(BEA)数据。
>>> finagg.bea.api.gdp_by_industry.get(year=[2019]).head(5)
table_id freq year quarter industry industry_description ...
0 1 Q 2019 1 11 农业、林业、渔业和狩猎 ...
1 1 Q 2019 1 111CA 农场 ...
2 1 Q 2019 1 113FF 林业、渔业和相关活动 ...
3 1 Q 2019 1 21 采矿 ...
4 1 Q 2019 1 211 石油和天然气开采 ...
获取联邦储备经济数据(FRED)。
>>> finagg.fred.api.series.observations.get(
... "CPIAUCNS",
... realtime_start=0,
... realtime_end=-1,
... output_type=4
... ).head(5)
realtime_start realtime_end date value series_id
0 1949-04-22 1953-02-26 1949-03-01 169.5 CPIAUCNS
1 1949-05-23 1953-02-26 1949-04-01 169.7 CPIAUCNS
2 1949-06-24 1953-02-26 1949-05-01 169.2 CPIAUCNS
3 1949-07-22 1953-02-26 1949-06-01 169.6 CPIAUCNS
4 1949-08-26 1953-02-26 1949-07-01 168.5 CPIAUCNS
获取证券交易委员会(SEC)文件。
>>> finagg.sec.api.company_facts.get(ticker="AAPL").head(5)
end value accn fy fp form filed ...
0 2009-06-27 895816758.0 0001193125-09-153165 2009 Q3 10-Q 2009-07-22 ...
1 2009-10-16 900678473.0 0001193125-09-214859 2009 FY 10-K 2009-10-27 ...
2 2009-10-16 900678473.0 0001193125-10-012091 2009 FY 10-K/A 2010-01-25 ...
3 2010-01-15 906794589.0 0001193125-10-012085 2010 Q1 10-Q 2010-01-25 ...
4 2010-04-09 909938383.0 0001193125-10-088957 2010 Q2 10-Q 2010-04-21 ...
使用安装的原始数据探索最受欢迎的特征
这些方法需要互联网访问、API 密钥/用户代理声明,并通过 finagg install
或 finagg <api/subpackage> install
命令下载和安装原始数据。
在一个数据框中获取最受欢迎的 FRED 特征。
>>> finagg.fred.feat.economic.from_raw().head(5)
CIVPART LOG_CHANGE(CPIAUCNS) LOG_CHANGE(CSUSHPINSA) FEDFUNDS ...
date ...
2014-10-06 62.8 0.0 0.0 0.09 ...
2014-10-08 62.8 0.0 0.0 0.09 ...
2014-10-13 62.8 0.0 0.0 0.09 ...
2014-10-15 62.8 0.0 0.0 0.09 ...
2014-10-20 62.8 0.0 0.0 0.09 ...
从 SEC 数据中获取季度报告特征。
>>> finagg.sec.feat.quarterly.from_raw("AAPL").head(5)
LOG_CHANGE(Assets) LOG_CHANGE(AssetsCurrent) ...
fy fp filed ...
2010 Q1 2010-01-25 0.182629 -0.023676 ...
Q2 2010-04-21 0.000000 0.000000 ...
Q3 2010-07-21 0.000000 0.000000 ...
2011 Q1 2011-01-19 0.459174 0.278241 ...
Q2 2011-04-21 0.000000 0.000000 ...
获取特定股票代码的季度和每日特征的聚合。
>>> finagg.fundam.feat.fundam.from_raw("AAPL").head(5)
PriceBookRatio PriceEarningsRatio
date
2010-01-25 0.175061 2.423509
2010-01-26 0.178035 2.464678
2010-01-27 0.178813 2.475448
2010-01-28 0.177154 2.452471
2010-01-29 0.173825 2.406396
使用安装的特征探索精炼的原始数据聚合
这些方法需要通过 finagg install
或 finagg <api/subpackage> install
命令安装精炼数据。
获取股票所属行业的平均季度报告特征。
>>> finagg.sec.feat.quarterly.industry.from_refined(ticker="AAPL").head(5)
mean ...
name AssetCoverageRatio BookRatio DebtEquityRatio ...
fy fp filed ...
2014 Q1 2014-05-15 10.731301 9.448954 0.158318 ...
Q2 2014-08-14 10.731301 9.448954 0.158318 ...
Q3 2014-11-14 10.731301 9.448954 0.158318 ...
2015 Q1 2015-05-15 16.738972 9.269250 0.294238 ...
Q2 2015-08-13 16.738972 9.269250 0.294238 ...
获取股票的行业平均季度报告特征。
>>> finagg.sec.feat.quarterly.normalized.from_refined("AAPL").head(5)
NORM(LOG_CHANGE(Assets)) NORM(LOG_CHANGE(AssetsCurrent)) ...
fy fp filed ...
2010 Q2 2010-04-21 0.000000 0.000000 ...
Q3 2010-07-21 0.000000 0.000000 ...
2011 Q1 2011-01-19 0.978816 0.074032 ...
Q2 2011-04-21 0.000000 0.000000 ...
Q3 2011-07-20 -0.353553 -0.353553 ...
获取按行业平均季度报告特征排序的股票代码。
>>> finagg.sec.feat.quarterly.normalized.get_tickers_sorted_by(
... "NORM(EarningsPerShareBasic)",
... year=2019
... )[:5]
['XRAY', 'TSLA', 'SYY', 'WHR', 'KMB']
获取按行业平均基本面特征排序的股票代码。
>>> finagg.fundam.feat.fundam.normalized.get_tickers_sorted_by(
... "NORM(PriceEarningsRatio)",
... date="2019-01-04"
... )[:5]
['AMD', 'TRGP', 'HPE', 'CZR', 'TSLA']
配置
API 密钥和用户代理
大多数 API 都需要 API 密钥和用户代理声明。您可以设置环境变量来向 finagg 公开您的 API 密钥和用户代理,或者您可以以编程方式将 API 密钥和用户代理传递给已实现的 API。以下环境变量用于配置 API 密钥和用户代理:
BEA_API_KEY
用于经济分析局的 API 密钥。您可以从 BEA API 网站 获取免费的 API 密钥。FRED_API_KEY
用于联邦储备经济数据 API 密钥。您可以从 FRED API 网站 获取免费的 API 密钥。INDICES_API_USER_AGENT
用于从维基百科抓取热门指数成分,应等同于浏览器的用户代理声明。这默认为一个硬编码的值,但可能并不总是有效。SEC_API_USER_AGENT
用于证券交易委员会的 API。这应该采用名字 姓氏 电子邮件
的格式。
数据位置
finagg 的根路径、HTTP 缓存路径和数据库路径都可以通过环境变量进行配置。默认情况下,所有与 finagg 相关的数据都放在根目录相对的 ./findata
目录中。您可以通过修改相应的环境变量来更改这些位置:
FINAGG_ROOT_PATH
指向./findata
目录的父目录。默认为您当前的工作目录。FINAGG_HTTP_CACHE_PATH
指向 HTTP 请求缓存的 SQLite 存储。默认为./findata/http_cache.sqlite
。FINAGG_DATABASE_URL
指向 finagg 数据存储。默认为./findata/finagg.sqlite
。
其他
您可以使用其他环境变量更改一些 finagg 行为:
FINAGG_DISABLE_HTTP_CACHE
:将其设置为"1"
或"True"
以禁用 HTTP 请求缓存。将使用默认的未缓存用户会话来处理所有请求,而不是可缓存的会话。
依赖项
- pandas 用于快速、灵活和富有表现力的关系数据表示。
- requests 用于向第三方 API 发送 HTTP 请求。
- requests-cache 用于缓存 HTTP 请求以避免被第三方 API 服务器限制。
- SQLAlchemy 用于 SQL Python 接口。
- yfinance 用于从 Yahoo! Finance 获取历史股票数据。
API 参考
相关项目
- FinRL 是一个金融强化学习环境和工具的集合。
- fredapi 是 FRED API 的一个实现。
- OpenBBTerminal 是彭博终端的开源版本。
- sec-edgar 是基于文件的 SEC EDGAR 解析器的实现。
- sec-edgar-api 是 SEC EDGAR REST API 的实现。
常见问题
我应该从哪里开始?
汇总一些数据,创建一些分析笔记本,或使用已实现的数据特征和 SQL 表创建一些强化学习环境。这个项目最初是为金融应用创建强化学习环境而创建的,但后来将其目的集中在仅汇总金融数据和特征上。也就是说,所有已实现的特征都以便于开发金融 AI/ML 的方式定义,所以我们鼓励您这样做!
为什么某些特定股票代码或经济数据系列的特征没有被安装?
已实现的 API 可能相对较新,可能无法为特定股票代码或经济数据系列提供数据。例如,可能无法通过 SEC EDGAR API 访问所有公司的每股收益。在某些情况下,API 可能会引发 HTTP 错误,导致安装跳过该股票代码或系列。此外,并非所有股票代码和经济数据系列都包含足够的数据用于特征归一化。如果一个股票代码或系列只有一个数据点,在计算特征(如百分比变化)时可能会丢弃该数据点,导致没有数据被安装。
支持哪些 Python 版本?
支持 Python 3.10 及以上版本。我们不打算支持更低的版本,因为 3.10 引入了一些很好的生活质量更新,这些更新在整个包中都有使用。
支持哪些操作系统?
该包在 Linux 和 Windows 上都进行了开发和测试,但我们建议在实践中使用 Linux 或 WSL。该包执行大量的 I/O 和进程间操作,这可能会导致 Windows 上的性能明显下降。