# Getting started with aieconindex

# Getting started

`aieconindex` provides tidy R access to the Anthropic Economic Index (AEI) dataset hosted on Hugging Face. The AEI is a recurring release from Anthropic that maps usage of the Claude family of large language models to occupations and tasks using the O*NET taxonomy and the Standard Occupational Classification (SOC) system.

## Installation

    # install.packages("remotes")
    remotes::install_github("charlescoverdale/aieconindex")
    library(aieconindex)

## Discovering releases

The Anthropic Economic Index is released as dated snapshots (typically every few months). `aei_releases()` lists the snapshots available on Hugging Face.

    aei_releases()

You can fetch the file tree of any single release with `aei_files()`. This is useful when you want to know exactly what is available before downloading anything.

    aei_files("2025-03-27", recursive = FALSE)

## Fetching a usage table

`aei_index()` is the convenience wrapper for the canonical usage table of a release. The shape and exact filename of that table varies across releases (the AEI restructured its directory layout in late 2025); this function papers over that variation.

    df <- aei_index("latest", source = "claude_ai", variant = "raw")
    head(df)

The `source` argument selects between Claude.ai consumer traffic (`"claude_ai"`) and first-party API traffic (`"1p_api"`). The `variant` argument selects between raw counts (`"raw"`) and tables already enriched with O*NET and SOC metadata (`"enriched"`).

## Fetching arbitrary files

For files that aren’t covered by `aei_index()`, use `aei_download()`:

    soc <- aei_download("2025-03-27", "SOC_Structure.csv")
    hierarchy <- aei_download("2025-09-15",
                              "data/output/request_hierarchy_tree_claude_ai.json")

CSV files come back as data frames; JSON files come back as parsed lists.

## The aei_tbl class

All data-returning functions emit an object of class `aei_tbl`: a `data.frame` with provenance metadata stored in the `aei_query` attribute. Inspect it directly:

    attr(df, "aei_query")

The class also dispatches a custom `print()`, `summary()`, and `[` method that preserves the metadata when the table is subset.

## Caching

Downloaded files are cached under `tools::R_user_dir("aieconindex", "cache")`. Override with `options(aieconindex.cache_dir = "/your/path")` before the first call. Inspect the cache with `aei_cache_info()` and clear it with `aei_cache_clear()`.

## Citing the data

The Anthropic Economic Index dataset is released under Creative Commons Attribution 4.0 International (CC-BY-4.0). When you use the data in published work, cite it.

    aei_cite("2026-03-24", format = "bibtex")

`aei_cite()` accepts `format = c("text", "bibtex", "bibentry")` and either a release id or `"all"` (the default) to cite the project as a whole.