可复现宏微观研究数据源 lixingr2

脚手架
作者

谭长德

发布日期

2024年2月4日

修改日期

2025年8月31日

从 Word 体系迁移到 Quarto 体系的主要好处是:以可复现、版本可控的文本与代码同源(literate programming)工作流,将文档、数据分析与可视化自动化集成,轻松一键输出多格式(HTML/PDF/Docx/幻灯片),从而大幅提升协作、可追溯性与长期可维护性。

1 初心动机

一切可以自动化的都应当自动化。但案头研究工作,充斥着拖拉点拽复制粘贴。因为对办公软件而言,使用方式越直观,上手越快,越能吸引用户。但要享受内容创作,就得让创作的归创作,机械的归机械。我们可以借鉴“文学化编程”,将“可复现科学研究”应用于“可复现行业研究”。

“可复现研究”让你在一份文档中,混排文字与代码,且最终渲染文档会嵌入代码生成内容。借助代码,整洁数据任君差遣,而不必从头整理。复杂数据处理、图表绘制不在话下,并有迹可循。代码也是文本,外显研究过程均以文本记录,杜绝了交互操作。这意味着,任何人拿到项目文本,都可以重新生成同样的报告。使用版本控制工具,还可以记录版本,识别任何版本间的改动。修改迭代再也不必瞻前顾后。

Quarto 是“可复现研究”的软件工程实现。利用 Quarto,可以做到“一处写就,多处成就”,即同一文件输出多种格式文件。本文,乃至本站,均由文本自动渲染部署而成。这样一来,你只需专心创作内容,而不必分心散力于机械重复事务。无需担心学习时间成本,借助大语言模型,连滚带爬用起来一周足矣。

综合数据质量与使用成本,我将理杏仁 API 封装成了 R 程序包:lixingr2。较 lixingrlixingr2 实现了参数联想、更多样的数据返回格式,以及更完整的错误提示,并完善了函数文档。目前已完成中国大陆上市公司、中国香港上市公司部分 API 封装,期待你试用、反馈,共同完善。

2 先睹为快

利用 lixingr2 包调用理杏仁 API,按年查询 2018 年以来顺丰控股 PE TTM。

library(dplyr)
library(lixingr2)

lxr_cn_com_fs_non_financial(
  token = Sys.getenv("LIXINGR_TOKEN"),
  start_date = "2018-01-01",
  stock_codes = "002352",
  metrics_list = "y.bs.pe_ttm.t",
  options = list(call_config = list(return_format = "tibble"))
) |>
  select(-c(date, reportDate))
#> # A tibble: 7 × 5
#>   currency reportType    standardDate              stockCode y.bs.pe_ttm.t
#>   <chr>    <chr>         <chr>                     <chr>             <dbl>
#> 1 CNY      annual_report 2024-12-31T00:00:00+08:00 002352             21.0
#> 2 CNY      annual_report 2023-12-31T00:00:00+08:00 002352             24.8
#> 3 CNY      annual_report 2022-12-31T00:00:00+08:00 002352             40.7
#> 4 CNY      annual_report 2021-12-31T00:00:00+08:00 002352             95.9
#> 5 CNY      annual_report 2020-12-31T00:00:00+08:00 002352             56.8
#> 6 CNY      annual_report 2019-12-31T00:00:00+08:00 002352             28.1
#> 7 CNY      annual_report 2018-12-31T00:00:00+08:00 002352             34.8

3 环境配置

  1. 安装 R 与 RStudio

    请参考这个资料,并了解 RStudio 基础用法。

  2. 验证安装

    打开命令行工具,在 Windows 上是命令提示符或 PowerShell,在 macOS 或 Linux 上是终端。输入以下代码并按下回车键运行:

    R --version

    如果 R 成功安装,这个命令会返回 R 版本信息。如果系统提示 R 不是内部或外部命令,也不是可运行程序或类似消息,那么 R 可能没有成功安装,或者 R 的安装目录没有添加到系统环境变量中。

  3. 安装 devtools

    因为 lixingr2 还未发布到 CRAN,所以需要通过 GitHub 安装。打开 RStudio,在 Console 中运行:

    install.packages("devtools")
  4. 安装 lixingr2

    通过 devtools 包,我们可以将托管在 GitHub 上的 lixingr2 包安装到本地。

    devtools::install_github("tanchangde/lixingr2")
  5. 配置理杏仁 API

    注册并登录到理杏仁,然后从开放平台获取 Token。在 Console 运行:

    file.edit("~/.Renviron")

    在打开的文件中添加一行新内容:

    LIXINGR_TOKEN = "已获取的 Token"

    保存并关闭 .Renviron 文件,重启 RStudio 。这样我们使用 lixingr2 包时,就不用显式声明 Token,分享项目代码更安全。

  6. 加载包

    新建一个 R 脚本文件,执行如下代码,将 lixingr2 包加载到当前环境:

    library(lixingr2)

    若未报错则成功加载,尽情玩耍吧。

4 用法提示

lixingr2 包封装的理杏仁 API 函数以 lxr_ 为前缀。除特别冗长外,函数名称基本取自 API 请求 URL 个性化后缀,并做适当缩写。如股票信息 API: https://open.lixinger.com/api/cn/company,对应函数名称则为 lxr_cn_com

个别复杂 API 参数文档,不在 R 包函数文档中赘述,请跳转对应理杏仁 API 文档查看。API 会以驼峰命名法返回参数相关错误提示,但lixingr2 仅接受对应下划线命名参数。lixingr2 会检查输入参数是否有效、必要参数是否缺失。

理杏仁 API 文档标识为数组的参数,需以字符向量提供,函数将自行转换。

比如,查询多家大陆上市公司基础信息,文档要求查询参数如下:

{
    "token": "......",
    "stockCodes": [
        "300750",
        "600519"
    ]
}

lixingr2 包,则需要这样写:

lxr_cn_com_profile(
  token = Sys.getenv("LIXINGR_TOKEN"),
  stock_codes = c("300750", "600519")
)

5 参考资料

回到顶部