tidyquant: financial analysis that speaks the tidyverse

The shape mismatch between xts and a tibble

The R quantitative finance ecosystem has a good collection of tools and a persistent annoyance: most of them work with zoo or xts objects, which carry an index and a time series structure that does not fit a data frame. The tidyverse works the other way, with data frames that are easy to filter, join and group.

tidyquant exists to sit between them. The package description says it integrates the best resources for collecting and analyzing financial data using zoo, xts, quantmod, TTR and PerformanceAnalytics, and that the tidy data infrastructure of the tidyverse allows for interaction between each, so that complete financial analyses can be done in the tidyverse.

That framing matters for what you get. You are not getting a new source of financial data or new financial mathematics. You are getting a translation layer. The mathematics and the data come from the packages underneath, and the tidyquant contribution is the conversion between representations.

The stated design goal is that it is built for modeling and scaling analyses using the tidyverse tools described in R for Data Science, which is a hint about who the intended user is: an analyst who already thinks in dplyr verbs and wants financial data in that shape, rather than a quant developer who wants maximum control over the time series object.

tq_get and the web dependency

tq_get is the entry point for data collection, described as a one stop shop for getting web based financial data in a tidy data frame format. The listed coverage is broad: daily stock prices, historical key statistics, real-time key statistics, historical key ratios, financial statements, dividends, splits, economic data from FRED, and foreign exchange rates from Oanda.

That breadth is also the risk. Every one of those is a network call to a provider, which means your analysis depends on connectivity, on the provider's response and on the provider's terms of use. The package documentation documents no caching or offline layer, so if reproducibility of a historical result matters, you need to save the data frames yourself rather than assume you can re-fetch the same values later.

The credential angle is worth thinking about too. Providers generally require an API key or account, and the package wraps that configuration without hiding it. Where your key lives and whether it ends up in a shared script is a decision you have to make, not one the package makes for you.

The data itself arrives in the standard tidy shape, one row per observation with columns for the symbol and the date, which is exactly what makes the next step easy.

tq_mutate and tq_transmute: the distinction that trips people up

Two functions cover the manipulation side, and the difference between them is the one detail worth memorising.

tq_mutate adds a column to the data frame. Use it when you want a technical indicator or a derived column alongside the existing ones, so you end up with price and a moving average side by side.

tq_transmute returns a new data frame instead, and the documentation gives the reason: it is necessary for periodicity changes. If you are resampling daily data to monthly, or you are computing something that produces a different time grid than the input, mutating a column in place cannot express it, so the result replaces the frame.

Both integrate financial functions from xts, zoo, quantmod, TTR and PerformanceAnalytics. The distinction matters because reaching for the wrong one produces a result that looks plausible but has the wrong time grid, and that kind of error tends to survive review because the numbers still look reasonable.

Once you have the indicators in the frame, the plotting side comes from ggplot2, and the package describes implementing ggplot2 functionality for financial visualizations. Volatility comparisons across several symbols and the cumulative growth of a fixed notional investment across different stocks are both shown as examples, the latter framed as how a ten thousand dollar investment in various stocks would have performed.

Performance and portfolio analysis through PerformanceAnalytics

The newest additions to the family are tq_performance and tq_portfolio, which integrate the PerformanceAnalytics package.

tq_performance converts investment returns into performance metrics. tq_portfolio aggregates a group, or multiple groups, of asset returns into one or more portfolios. The portfolio example in the documentation builds four portfolios by varying the weights of FB, AMZN, NFLX and GOOG, with each portfolio holding a zero in one position and larger weights in others, and then visualises the blended returns.

Those four examples exist to show that the group of returns becomes a single comparable series. The workflow is: fetch prices for the tickers, compute returns, aggregate the returns into portfolios with the specified weights, then chart the result with ggplot2. Because everything sits in data frames along the way, the portfolio construction step is a group and summarise operation rather than a bespoke portfolio engine.

This is where tidyquant differs most from the underlying package. PerformanceAnalytics on its own speaks in terms of its own return objects; through tq_performance and tq_portfolio you get the same metrics expressed over tidy data, which means you can join them to other tables, filter by symbol, or feed them into a model with the rest of your pipeline.

Installing, versions and the documentation set

There are two installation routes and the difference between them matters if you need the newest functions.

The CRAN approved version is the standard one.

install.packages("tidyquant")

The development version with the latest features goes through devtools and GitHub.

# install.packages("devtools")
devtools::install_github("business-science/tidyquant")

Since tq_performance and tq_portfolio are described as the newest additions, a team that needs them may find that the CRAN build lags, and the devtools route becomes the practical option with the usual trade-off that you are no longer on a published release.

The release history shows why that tension exists. The listed versions are 1.0.12 from 2026-03-16, 1.0.10 from 2025-01-08 and 1.0.6 from 2022-11-17. The repository is not archived and the last push was on 2026-10-01, so development is current even when the tagged versions are not.

For learning, the package ships a set of vignettes with a consistent numbering, from TQ00 which introduces the package through TQ01 on core functions, TQ02 on the quantitative package integrations, TQ03 on scaling and modelling, TQ04 on charting and TQ05 on performance analysis. There is also a pkgdown site at business-science.github.io/tidyquant, and the README is generated from README.Rmd, so the source of the documentation is the R Markdown file rather than the rendered README.

Where tidyquant is the wrong tool

Three situations call for something else.

If you need a hard guarantee about where the numbers came from, the web path is a problem. A tidyquant pipeline that fetches live data is convenient for exploration and shaky for anything that has to be reproduced or audited six months later. Saving the frames is the workaround, and once you are saving every frame you may find that the tidy layer adds less than it costs.

If you already work fluently in xts and quantmod without dplyr, the translation is overhead. The functions you need already exist in the underlying packages, and the wrappers add a layer between you and the documentation of those packages.

If your requirement is heavy performance work on large price histories, the tidy representation itself is the cost. Data frames are wonderful to work with and expensive to hold in memory when you have millions of rows and frequent resampling. Nothing in the tidyquant documentation claims to solve that, and the way to find out whether it matters is to look at your own row counts.

There is a licensing point to check as well. The licence field on the repository records a custom type that GitHub cannot classify, with a LICENSE file at the root, so read it rather than assuming a standard CRAN licence applies. The repository also carries CRAN-RELEASE, CRAN-SUBMISSION and cran-comments.md files, which are the artefacts of submitting to CRAN, and a revdep/ directory for reverse dependency checks.

Editorial conclusion

Adopt tidyquant if your R work already lives in the tidyverse and you need financial data in a data frame rather than an xts object, because the whole point of the package is removing the reshape step between quantmod and dplyr. Do not adopt it if you need guaranteed data provenance or offline analysis, since the primary data path is a web call, or if you are starting from scratch and can work directly in xts, because the tidy wrappers add a dependency layer. Verify first that your provider access works from your network, that the CRAN version covers the functions you need, since the newest feature additions such as tq_performance and tq_portfolio may only exist in the development version, and that you read the licence file, because the licence field on the repository records a custom type that GitHub cannot classify.

Frequently asked questions

Official sources

1. business-science/tidyquant on GitHub
2. Issues
3. Project website
4. README
5. Releases