DOCSEARCHbyAlgolia
Submit Docs

cot_reports Python Library

repository·main·Indexed 41 days ago

https://github.com/ndelventhal/cot_reports

A Python library for fetching and aggregating Commitments of Traders (COT) reports from the Commodity Futures Trading Commission (CFTC). It provides functions like cot_hist(), cot_year(), and cot_all() to access historical and current report data—including Legacy, Supplemental, Disaggregated, and Traders in Financial Futures reports—returned as pandas DataFrames.

Tokens
2K
Snippets
9
Records
13
Agent score
2%

What's inside cot_reports

  1. Understand COT report types and availability

    main

    The cot_reports library provides access to four distinct types of Commitment of Traders (COT) reports published by the CFTC. Choosing the right type depends on the asset class and the historical depth required:

    1. Legacy: Includes both physical and non-physical contracts. Best for long-term historical analysis (available from 1986/1995). Classifications: non-commercial and commercial.
    2. Supplemental: Focuses on selected agricultural commodities and includes index traders. Available from 2006. Available in short format.
    3. Disaggregated: Focuses on physical contracts (e.g., agriculture, petroleum, natural gas). Available from 2006. Classifications include Producer/Merchant/Processor/User, Swap Dealers, Managed Money, and Other Reportable.
    4. Traders in Financial Futures: Focuses on non-physical (financial) contracts. Available from 2006. Classifications include Dealer/Intermediary, Asset Manager/Institutional, Leveraged Funds, and Other Reportable.

    Note on Formats: Reports are available in long and short formats. The library defaults to the long format unless the report type is Supplemental, in which case it uses the short format.

  2. Legacy report trader classifications

    main

    In Legacy COT reports, market participants are categorized into three main groups:

    • Commercials: Participants using futures for hedging (e.g., gold mining companies). They are engaged in business activities that can be hedged by futures/options.
    • Non-commercials: Participants with speculative interest (e.g., managed funds, pension funds, institutional investors). They are not considered commercials.
    • Non-reportable: Participants holding positions below the CFTC reporting levels. While not explicitly reported by firms, their aggregate positions can be derived from open interest data.

  4. Install cot_reports

    main

    You can install the cot_reports library using pip from PyPI or directly from the GitHub repository.

    To install from PyPI:

    pip install cot_reports

    To install from the GitHub repository:

    pip install git+https://github.com/NDelventhal/cot_reports

  5. Use cot_hist() to download historical bulk COT data

    main

    The cot_hist() function downloads the historical bulk file for a specified report type. It returns the data as a pandas DataFrame. In the example below, it is used to fetch the 'Traders in Financial Futures Futures-and-Options Combined' report.

    # Example: cot_hist()
# cot_hist() downloads the historical bulk file for the specified report type, 
# in this example the Traders in Financial Futures Futures-and-Options Combined report.
# Returns the data as dataframe.

df = cot_hist('Traders in Financial Futures Futures-and-Options Combined')

  6. Use cot_all() to download all available COT data

    main

    The cot_all() function downloads the historical bulk file AND all remaining single year files for the specified report type. It returns the combined data as a pandas DataFrame.

    # Example: cot_all()
# cot_all() downloads the historical bulk file and all remaining single year files 
# of the specified report type. Returns the data as dataframe.

df = cot_all('Traders in Financial Futures Futures-and-Options Combined')

  7. Use cot_year() to download a single year of COT data

    main

    The cot_year() function downloads the single year file for a specified report type and a specific year. It returns the data as a pandas DataFrame.

    # Example: cot_year()
# cot_year() downloads the single year file of the specified report type and year.
# Returns the data as dataframe.

df = cot_year('Traders in Financial Futures Futures-and-Options Combined', 2020)

  8. Collect COT data for a range of years

    main

    To collect data for multiple specific years, you can iterate through a range and call cot_year() for each year. The following example demonstrates collecting data from 2017 to 2020 for a specified report.

    # Example for collecting data of a few years, here from 2017 to 2020, 
# of a specified report:

import pandas as pd

report_type = 'Traders in Financial Futures Futures-and-Options Combined'
years = range(2017, 2021)

df_list = [cot_year(report_type, year) for year in years]
df = pd.concat(df_list)

  10. Use cot_hist() to download historical bulk data

    main

    The cot_hist(cot_report_type) function downloads compressed bulk files for a specified report type, covering historical data from 1986 (depending on the report type) up to 2016. It returns the data as a pandas DataFrame.

    import cot_reports as cot

# Downloads historical bulk file for TFF Futures-and-Options Combined
df = cot.cot_hist(cot_report_type='traders_in_financial_futures_futopt')

  11. Use cot_year() to download data for a specific year

    main

    The cot_year(year, cot_report_type) function downloads the single year file for the specified report type and year. If you specify the current year, it fetches the latest published data. It returns the data as a pandas DataFrame.

    import cot_reports as cot

# Downloads the single year file for TFF Futures-only for the year 2020
df = cot.cot_year(year=2020, cot_report_type='traders_in_financial_futures_fut')

  12. Use cot_all() to download all available data for a report type

    main

    The cot_all(cot_report_type) function downloads the historical bulk file AND all remaining single year files for the specified report type, including the latest data. It returns the combined data as a pandas DataFrame.

    import cot_reports as cot

# Downloads all available data for Legacy Report Futures-only
df = cot.cot_all(cot_report_type='legacy_fut')