https://github.com/ropensci/rb3
A bunch of downloaders and parsers for data delivered from B3
https://github.com/ropensci/rb3
brazil exchange-data finance financial-data financial-services market-data r
Last synced: 5 months ago
JSON representation
A bunch of downloaders and parsers for data delivered from B3
- Host: GitHub
- URL: https://github.com/ropensci/rb3
- Owner: ropensci
- License: other
- Created: 2014-12-15T11:04:39.000Z (almost 11 years ago)
- Default Branch: main
- Last Pushed: 2024-08-14T09:33:49.000Z (about 1 year ago)
- Last Synced: 2024-08-14T10:48:30.947Z (about 1 year ago)
- Topics: brazil, exchange-data, finance, financial-data, financial-services, market-data, r
- Language: R
- Homepage: https://docs.ropensci.org/rb3/
- Size: 41.1 MB
- Stars: 70
- Watchers: 13
- Forks: 28
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: NEWS.md
- Contributing: Contributing.md
- License: LICENSE
- Codemeta: codemeta.json
Awesome Lists containing this project
- awesome-quant - rb3 - A bunch of downloaders and parsers for data delivered from B3. (R / Data Sources)
README
# rb3 
[](https://www.repostatus.org/#active)
[](https://app.codecov.io/gh/wilsonfreitas/rb3?branch=main)
[](https://github.com/ropensci/rb3/actions)
[](https://CRAN.R-project.org/package=rb3)
[](https://cran.r-project.org/package=rb3)
[](https://github.com/ropensci/software-review/issues/534)
## Overview
[B3](https://www.b3.com.br) is the main financial exchange in Brazil,
offering access to trading systems for stocks, futures, options, and
other financial instruments. The `rb3` package provides tools for
downloading, processing, and analyzing market data from B3, including:
- **Stocks & Equities**: Historical price data through COTAHIST files
- **Futures Contracts**: Settlement prices for futures contracts
- **Yield Curves**: Historical yield curves calculated from futures
contracts
- **ETFs & BDRs**: Data for Exchange Traded Funds and Brazilian
Depositary Receipts
- **REITs (FIIs)**: Data for Brazilian Real Estate Investment Trusts
- **Options**: Equity and index options contracts
- **Market Indices**: B3 indices composition and historical data
The package uses webscraping tools to obtain data directly from [B3’s
website](https://www.b3.com.br), making it accessible in R as structured
datasets. These datasets are valuable for financial analysis, academic
research, and investment decision-making.
## Installation
``` r
# From CRAN (stable version)
install.packages("rb3")
# Development version from GitHub
if (!require(devtools)) install.packages("devtools")
devtools::install_github("ropensci/rb3")
```
## Basic Usage
### Downloading Data
Execute the following code to download all data you need to start
working with `rb3`:
``` r
# Set the rb3.cachedir folder - it must be executed before loading rb3 package
options(rb3.cachedir = "/path/to/your/custom/folder")
library(rb3)
library(bizdays)
# download COTAHIST data from 2000 to 2025
fetch_marketdata("b3-cotahist-yearly", year = 2000:2025)
# download futures settlement prices from 2000 to 2025
fetch_marketdata("b3-futures-settlement-prices", refdate = bizseq("2000-01-01", Sys.Date(), "Brazil/B3"))
# download yield curves from 2018 to 2025
fetch_marketdata("b3-reference-rates",
refdate = bizseq("2018-01-01", Sys.Date(), "Brazil/B3"),
curve_name = c("DIC", "DOC", "PRE")
)
# download indexes composition data - it is necessary to execute `indexes_get()`
fetch_marketdata("b3-indexes-composition")
# download current portfolio for all indexes
fetch_marketdata("b3-indexes-current-portfolio", index = indexes_get(), throttle = TRUE)
# download theoretical portfolio for all indexes
fetch_marketdata("b3-indexes-theoretical-portfolio", index = indexes_get(), throttle = TRUE)
# download historical data for all indexes
fetch_marketdata("b3-indexes-historical-data", index = indexes_get(), year = 2000:2025, throttle = TRUE)
```
### Market Data Templates
The `rb3` package uses a template system to standardize the downloading
and processing of different data types. To see available templates:
``` r
library(tidyverse)
library(bizdays)
library(rb3)
# List available templates
list_templates()
#> # A tibble: 9 × 2
#> Template Description
#>
#> 1 b3-bvbg-086 Arquivo de Preços de Mercado - BVBG-086
#> 2 b3-cotahist-daily Cotações Históricas do Pregão de Ações - Arq…
#> 3 b3-cotahist-yearly Cotações Históricas do Pregão de Ações - Arq…
#> 4 b3-futures-settlement-prices Preços de Ajustes Diários de Contratos Futur…
#> 5 b3-indexes-composition Composição dos índices da B3
#> 6 b3-indexes-current-portfolio Carteira teórica corrente dos índices da B3 …
#> 7 b3-indexes-historical-data Dados históricos e estatísticas dos índices …
#> 8 b3-indexes-theoretical-portfolio Carteira Teórica dos índices da B3 com pesos…
#> 9 b3-reference-rates Taxas referenciais
```
### Downloading Market Data
The main function for fetching data is `fetch_marketdata()`, which
downloads data based on a template and parameters:
``` r
# Download yield curve data for specific dates
fetch_marketdata("b3-reference-rates",
refdate = as.Date("2024-01-31"),
curve_name = "PRE"
)
# Download futures settlement prices
fetch_marketdata("b3-futures-settlement-prices",
refdate = as.Date("2024-01-31")
)
# Download yearly COTAHIST files
fetch_marketdata("b3-cotahist-yearly", year = 2023)
```
### Working with Historical Equity Data
``` r
# Access the data
ch <- cotahist_get("yearly")
# Filter for stocks
eq <- ch |>
filter(year(refdate) == 2023) |>
cotahist_filter_equity() |>
collect()
```
``` r
# Get top 10 most traded stocks
symbols <- eq |>
group_by(symbol) |>
summarise(volume = sum(volume)) |>
arrange(desc(volume)) |>
head(10) |>
pull(symbol)
# show top 10 most traded stocks
symbols
#> [1] "VALE3" "PETR4" "ITUB4" "BBDC4" "BBAS3" "B3SA3" "PRIO3" "PETR3" "RENT3"
#> [10] "MGLU3"
```
``` r
# Plot the most traded stocks grouped by month
eq |>
filter(symbol %in% symbols) |>
mutate(refdate = floor_date(refdate, "month")) |>
group_by(refdate, symbol) |>
summarise(volume = sum(volume)) |>
# Plot
ggplot(aes(x = refdate, y = volume, color = symbol)) +
geom_line() +
labs(
title = "Top 10 Most Traded Stocks in 2023",
x = "Date",
y = "Volume"
) +
scale_y_continuous(labels = scales::comma)
#> `summarise()` has grouped output by 'refdate'. You can override using the
#> `.groups` argument.
```
### Yield Curve Analysis
``` r
# Get Brazilian nominal yield curve (PRE)
yc_data <- yc_brl_get() |>
filter(refdate == "2024-01-31") |>
collect()
```
``` r
# Plot the yield curve
ggplot(yc_data, aes(x = forward_date, y = r_252)) +
geom_line() +
labs(
title = "Brazilian Yield Curve (PRE)",
x = "Forward Date",
y = "Annual Interest Rate"
) +
scale_y_continuous(labels = scales::percent)
```
### Futures Contracts
``` r
# Get futures settlement prices
futures_data <- futures_get() |>
filter(commodity == "DI1") |>
collect()
```
``` r
# Calculate implied rates
di1_futures <- futures_data |>
mutate(
maturity_date = maturitycode2date(maturity_code),
business_days = bizdays(refdate, maturity_date, "Brazil/ANBIMA"),
implied_rate = (100000 / price)^(252 / business_days) - 1
)
# Plot the implied rates
ggplot(di1_futures, aes(x = maturity_date, y = implied_rate)) +
geom_line() +
geom_point() +
labs(
title = "Implied Rates for DI1 Futures",
x = "Maturity Date",
y = "Implied Rate"
) +
scale_y_continuous(labels = scales::percent)
```
## Documentation
For comprehensive documentation and examples, visit:
- [Package Website](https://ropensci.github.io/rb3/)
- Vignettes (in-depth tutorials):
- [Getting
Started](https://ropensci.github.io/rb3/articles/Getting-started.html)
- [Fetching Historical Equity
Data](https://ropensci.github.io/rb3/articles/Fetching-historical-equity-data.html)
- [Analyzing B3 Index
Data](https://ropensci.github.io/rb3/articles/Fetching-historical-index-data.html)
- [How to Compute Historical Rates from B3 Future
Prices](https://ropensci.github.io/rb3/articles/Fetching-historical-future-rates.html)
- [Fetching B3 Yield
Curves](https://ropensci.github.io/rb3/articles/Fetching-historical-yield-curve.html)
## Citation
If you use `rb3` in your research, please cite it:
To cite rb3 in publications use:
Download and parse public files released by B3 and convert them into
useful formats and data structures common to data analysis
practitioners.
A BibTeX entry for LaTeX users is
@Manual{rb3-package,
title = {Download and Parse Public Data Released by B3 Exchange},
author = {Wilson Freitas and Marcelo Perlin},
year = {2023},
note = {R package version 0.0.8},
url = {https://github.com/ropensci/rb3},
}