asdfree: an index of R packages for official survey data

asdfree is a catalogue, not a library you load in R

The repository named ajdamico/asdfree is not a library you install and then call from a session. It is a bookdown book, an online reference rendered from R Markdown sources, whose job is to index a family of small R packages, each built around a single statistical programme. The README puts it plainly, since the book can be read at http://asdfree.com/ and contributions arrive as new metadata entries. The top level of the repository is the giveaway. There is index.Rmd, there is _bookdown.yml, there is _output.yml, there is book.bib and packages.bib, and there is one Rmd file per survey, named after it. Files such as acs.Rmd, ahs.Rmd, anes.Rmd, atus.Rmd, ahrf.Rmd, brfss.Rmd, ces.Rmd, cog.Rmd, cps.Rmd, faers.Rmd, gss.Rmd, meps.Rmd and nhanes.Rmd sit side by side, along with posts/, docs/ and a metadata/ directory. The practical question for an analyst is therefore not whether to install asdfree. It is which of these per-survey packages to reach for, and whether the catalogue tells you enough to decide.

One metadata line per survey is the whole contract

Contributions do not flow through the prose. The README asks for new entries to be styled like the ones already sitting in the metadata directory, and each entry is a single line: a survey slug, a licence badge, and a link into the package repository. The rendered pages are a view over that list, which is why the entry list reads like a table rather than an essay. Here is one entry exactly as it is printed.

american-community-survey-acs: <p><a href="https://www.gnu.org/licenses/gpl-3.0"><img src="https://img.shields.io/badge/License-GPLv3-blue.svg" alt="License: GPL v3" /></a> <a href="https://github.com/asdfree/acs/actions"><img src="https://github.com/asdfree/acs/actions/workflows/r.yml/badge.svg" alt="Github Actions Badge"></a></p>

The first token is the survey slug, the licence badge is the same on every entry, and the second badge points at the GitHub Actions workflow of the matching package repository. That is the entire agreement between the book and the packages: the index does not host the data code, and the packages do not know the index exists. A new entry is cheap to add, and equally cheap to get wrong.

The contributor path is a fork and one file

The route in for contributors is short, and it runs through the same metadata directory.

# You can contribute to this book by submitting new entries styled like https://github.com/ajdamico/asdfree/tree/master/metadata/

Once an entry lands, the book is rebuilt and published, because the repository ships its own _build.sh and _deploy.sh scripts along with a CNAME file for the asdfree.com domain. The result is a set of pages, one per survey, that a reader can browse without an R installation. What that workflow does not produce is a released artefact of the book. The repository has no GitHub releases, so there is no tagged version of the documentation to pin a citation to, and no changelog describing when a given survey page last changed. The same is true of the data packages: each lives elsewhere, under its own history, so the index can only ever point, never pin.

There is no install command, so the first step is finding your package

Getting at the data is where the book stops and the individual packages begin. There is no installation command for asdfree itself anywhere in the README, and the catalogue entries do not carry one either. Each programme is a separate R package in a separate repository under the asdfree organisation, for instance github.com/asdfree/acs, github.com/asdfree/gss and github.com/asdfree/meps, and the package names visible in the badge URLs run from acs and ahrf through brfss, cog, cps, enade, enem, faers, gss, mcbs, meps, mlces, nbs and naws. The honest first step for a new user is to open the entry for the survey, follow the link to that package repository, and read the install instructions there, because those are the only install instructions the project provides. The book saves you the search, not the setup. The entry pages list no function names either, so the concrete API surface has to be read in the package repository rather than in the book.

Badge types reveal where the testing is uneven

The badges make the unevenness visible. Most entries carry a link to a workflow file named r.yml in the package repository, which points at a machine-run check of some kind. Others show a badge reading Tested Locally Windows Laptop instead, and the packages marked that way in the listing include anes, chis, ess, hrs and naws. The distinction matters if you are deciding whether to trust a package before pointing a report at it. One group has an automated check and the other has a manual pass on a single operating system, with no record of the R version or of when that manual pass happened. A badge is also a statement about the code, never about the data, so it says nothing about whether an upstream statistical agency has changed the layout of its files. Read the badge as a hint about the wrapper, and check the survey's own documentation for the data itself.

Where the catalogue runs out of road

asdfree is the wrong tool in several ordinary situations. If the data you need are not one of the listed programmes, there is no package to find and the metadata scheme offers nothing. If you need a single reproducible environment across many surveys, the layout works against you, since every programme lives in its own repository with its own dependency set, and pinning versions for twenty surveys means tracking twenty packages. If you need the newest release of a survey that nobody has wrapped yet, the catalogue only helps after a contributor has added the entry and the package has caught up with the agency. The entry list also stops mid-line partway through the alphabetical run, so the tail of the catalogue has to be read on the site rather than in the README. The trade-off is the one any index makes: a curated list saves you from writing a downloader, and it also fixes a pace set by whoever maintains that particular package.

A hand written downloader versus a curated wrapper

The alternative most analysts already have is to write the download themselves: point at the agency's file, fetch it, unpack it, read it into a data frame. That route carries no dependency and no waiting for a maintainer, and it fails in the familiar way, silently and only later, when an agency renames a file or shifts a column. The asdfree approach inverts the burden. Each package absorbs the format of one programme, keeps that knowledge in its own history, and can be corrected without touching the other entries. The catalogue adds a third layer on top, an index that makes the set of options visible in one place. Whether that layer earns its keep depends on how many of the programmes you actually need, since one survey makes the index redundant while a dozen makes it the point.

Licence, releases and the shape of the upkeep

Every entry carries the same licence badge, GPL v3, and the repository itself is published under GPL-3.0. That is worth noting in a practical rather than a legalistic way: the code is copyleft, so redistribution of a modified package carries obligations, while the statistics you pull through it remain the work of the publishing agency. Maintenance is easier to pin down here than most projects allow. The repository is not archived, and the last push was on 2026-09-01. That is a recent commit for a collection of documentation files, but it says only that the index changed. It does not tell you when the acs package or the gss package last changed, because each of those lives in its own repository with its own timeline. Checking the individual package repositories remains the only way to know whether a given wrapper still matches the current agency release.

Editorial conclusion

Adopt asdfree when you work with one of the listed official surveys and want a maintained download path without writing your own fetcher, and skip it when your data sit outside the catalogue or when you need one version-pinned environment across many programmes. Before committing, open the entry for your survey and read the linked package repository, since the catalogue itself carries no version numbers, no release artefacts, and no function documentation.

Frequently asked questions

Official sources

1. ajdamico/asdfree on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README