Metadata-Version: 2.4
Name: python-quanta
Version: 0.8.2
Summary: A quantitative analysis project for financial data.
Author-email: Porco Rosso <porcorossobaojie@gmail.com>
Project-URL: Homepage, https://github.com/porcorossobaojie/quanta.git
Keywords: quantitative,finance,data-analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pandas>=1.3.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: tomlkit>=0.11.0
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: python-box>=5.4.0
Requires-Dist: duckdb>=0.8.0
Requires-Dist: jqdatasdk>=1.8.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: pymysql>=1.0.0
Requires-Dist: sqlalchemy>=1.4.0
Requires-Dist: statsmodels>=0.13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.910; extra == "dev"
Requires-Dist: ipython>=8.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"

# quanta

Summary
-------
    A local-first quantitative research framework designed for:
        -- providing specialized financial analysis modules and functions.
        -- abstracting database connectivity to streamline data access for researchers.
        -- deep integration with JoinQuant (JQData) for professional-grade data support.
        -- supporting industry-standard factor models (e.g., Barra - Completed Style Factors).

How Install
-----------

    pip install python-quanta -i https://pypi.org/simple

How Initial Local Settings
--------------------------

    I new docoument like:
        your project
        |-- .env                                 <-- build by user
             |-- account.yaml                    <-- build by user if you have
             |-- libs.yaml                       <-- must build

    II if having join quant account, create file <account.yaml>:
        account.yaml
        ----
        joinquant:
            username: 'your_user_name'
            password: 'your_password'

    III set up your database env, create file <libs.yaml>:
        libs.yaml
        ----
        db:
            recommand_settings: DuckDB            # recommand database type
            DuckDB:
                recommand_settings:
                    path: 'E:/ProgramData/DuckDB' # path of database file
                    database: Locals              # name of database file
                    schema: jq_data               # schema name

    For technical details on the underlying database abstraction and supported engines, see:
    [Database Abstraction Layer](src/quanta/libs/db/README.md)

    For a detailed explanation of all configuration fields, see:
    [Configuration Definitions](src/quanta/config/README.md)

Why python-quanta
-----------------

    I provide local database construct automatically
        all you need is just running:
            -- quanta.data.daily()
        including:
            -- trading data: stock, index(not in CSI), etf
            -- finance data: stock

        For details on data provider integration and table logic, see:
        [Data Management](src/quanta/data/README.md)

    II specialized financial analytical extensions (based on pandas.DataFrame)
        -- DataFrame.gen
                        .group()                 # quick-grouping based on multi-factor theory
                        .portfolio()             # get returns of each group generated by function above
        -- DataFrame.rollings
                        .sth()                   # specialized rolling, e.g., "get 3 max volume in 21 days"
        -- DataFrame.stats
                        .neutral()               # OLS or factor neutralization (e.g., .stats.neutral)

        For a full reference of available accessors and metrics, see:
        [Analytical Extensions](src/quanta/libs/_pandas/README.md)

    III more powerful functions with database
        if user have join quant account, python-quanta will be more powerful:
        -- DataFrame.f.listing                   # filter portfolio by listed date
                       not_st                    # filter portfolio by ST status
                       tradestatus               # filter portfolio by trade status
                       index_members             # get index constituents (e.g., '300', '500')
                       label                     # get industry classifications (e.g., "swl1_code")
                       ic                        # Information Coefficient (IC)
                       ir                        # Information Ratio (IR, annual)
                       port / test               # rapid group return calculation and backtesting

        For a deep dive into research interfaces and Pandas extensions, see: 
        [Research Flow Layer](src/quanta/libs/_flow/README.md) --> _extra_pandas
        
    IV high-efficiency research workflow (quanta.flow)
        The `flow` module provides a high-level abstraction for factor/strategy research:
        -- quanta.flow.astock("key")             # unified interface for price and financial data
        -- quanta.flow.astock._help              # metadata lookup for tables, columns, and comments
        -- quanta.flow.astock.help("keyword")    # fuzzy search within metadata (e.g., "oper" for operating data)

        For a deep dive into research interfaces and Pandas extensions, see:
        [Research Flow Layer](src/quanta/libs/_flow/README.md) --> _extra_pandas

    V standard factor library (faclib)
        Benchmark factors for risk modeling and strategy comparison:
        -- Barra USA4 Style Factors (Completed): 
           Size, Beta, Momentum, Residual Volatility, Liquidity, Earnings Yield, Growth, Leverage, etc.
        -- Alpha 101 (Roadmap)

Notices
-------
    welcome for advise! ^_^
    if you want data for testing python-quanta, please mail: porcorossobaojie@gmail.com

---

# quanta (中文版)

Summary
-------
    本地优先的量化研究框架, 旨在:
        -- 提供针对金融场景优化的专业分析模块与函数.
        -- 抽象化数据库连接细节, 使研究员能够高效获取所需数据.
        -- 深度集成聚宽 (JQData) API, 提供强大的专业数据支持.
        -- 支持行业标准因子模型 (如 Barra 风险模型 - 已完成风格因子).

How Install
-----------

    pip install python-quanta -i https://pypi.org/simple

How Initial Local Settings
--------------------------

    I 新建配置文件:
        你的项目目录/
        |-- .env                                 <-- 环境变量配置文件
             |-- account.yaml                    <-- 聚宽账户凭据 (可选)
             |-- libs.yaml                       <-- 数据库配置 (必填)

    II 若有聚宽账户, 创建 <account.yaml>:
        account.yaml
        ----
        joinquant:
            username: 'your_user_name'
            password: 'your_password'

    III 配置数据库环境 <libs.yaml>:
        libs.yaml
        ----
        db:
            recommand_settings: DuckDB            # 推荐使用的存储引擎
            DuckDB:
                recommand_settings:
                    path: 'E:/ProgramData/DuckDB' # 本地数据库存放路径
                    database: Locals              # 数据库文件名
                    schema: jq_data               # Schema 名称

    有关底层数据库抽象及支持引擎的技术详情, 请参阅:
    [数据库抽象层详解](src/quanta/libs/db/README.md)

    有关所有配置字段的详细定义说明, 请参阅:
    [配置定义详解](src/quanta/config/README.md)

Why python-quanta
-----------------

    I 提供自动化本地数据库构建
        仅需运行以下指令即可全自动同步 ETL:
            -- quanta.data.daily()
        包含数据:
            -- 交易数据: 股票, 指数(非中证系列), ETF.
            -- 财务数据: 全量股票财务报表.

        有关数据供应商集成及表逻辑的详细说明, 请参阅:
        [数据管理详解](src/quanta/data/README.md)

    II 专业金融分析扩展 (基于 pandas.DataFrame)
        -- DataFrame.gen
                        .group()                 # 基于多因子理论的高效分组函数
                        .portfolio()             # 计算基于分组结果的投资组合收益
        -- DataFrame.rollings
                        .sth()                   # 专用滚动窗口函数(如: "获取21日内成交量最大的3个交易日")
        -- DataFrame.stats
                        .neutral()               # 因子中性化处理及截面 OLS 回归

        有关可用访问器及指标的完整参考, 请参阅:
        [专业分析扩展详解](src/quanta/libs/_pandas/README.md)

    III 数据库增强型高级功能
        需配合聚宽账户以实现更强大的分析能力:
        -- DataFrame.f.listing                   # 根据上市日期过滤
                       not_st                    # 剔除 ST/退市风险警示股票
                       tradestatus               # 根据交易状态过滤
                       index_members             # 获取指数成分股(如 '300', '500')
                       label                     # 获取行业分类信息(如申万一级)
                       ic                        # 因子 IC (Information Coefficient) 计算
                       ir                        # 因子 IR (Information Ratio, 年化) 计算
                       port / test               # 快速计算分组收益及策略回测

        有关研究接口及 Pandas 扩展功能的深入说明, 请参阅:
        [研究流层详解](src/quanta/libs/_flow/README.md)  --> _extra_pandas

    IV 高效研究流工具 (quanta.flow)
        `flow` 模块为因子与策略研发提供高层抽象:
        -- quanta.flow.astock("key")             # 获取价格或财务数据的统一接口
        -- quanta.flow.astock._help              # 快速查询数据库表, 字段及注释信息
        -- quanta.flow.astock.help("key")        # 模糊搜索元数据(如搜索 "oper" 获取营业相关字段)

        有关研究接口及 Pandas 扩展功能的深入说明, 请参阅:
        [研究流层详解](src/quanta/libs/_flow/README.md)  --> _main

    V 标准因子库 (faclib)
        持续集成行业标准因子以供对比与测试:
        -- Barra USA4 风格因子 (已完成): 
           包含市值、贝塔、动量、残差波动率、流动性、盈利、成长、杠杆等 10 大风格因子.
        -- Alpha 101 系列因子 (发展路线).

Notices
-------
    欢迎任何建议与反馈! ^_^
    如需测试数据或技术咨询, 请联系: porcorossobaojie@gmail.com
