How to use GetTDData

Information regarding prices and yields of bonds issued by the Brazilian government can be downloaded manually as excel files from the Tesouro Direto website. However, it can be painful to aggregate all of this data into something useful as the files don’t have an uniform format and are all divided by year and asset code.

Package GetTDData makes the process of importing data from Tesouro direto much easier. All you need is the name of fixed income assets (LFT, LTN, NTN-C, NTN-B, NTN-B Principal, NTN-F).

How to use GetTDData

Suppose you need financial data (prices and yields) for a bond of type LTN with a maturity (end of contract) at 2023-01-01. This bullet bond is the most basic debt contract the Brazilian government issues. It does not pay any value (coupon) during its lifetime and will pay 1000 R$ at maturity.

In order to get the data, all you need to do is to run the following code in R:

library(GetTDData)

asset.codes <- 'LTN'   # Identifier of assets 
cache_folder <- paste0(tempdir(), '/TD_cache')

my.flag <- download.TD.data(asset.codes = asset.codes, 
                            dl.folder = cache_folder)

## Warning in download.TD.data(asset.codes = asset.codes, dl.folder =
## cache_folder): Folder /tmp/RtmpkijwPg/TD_cache was not found. Creating a it..

## 
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2005.xls (1-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2006.xls (2-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2007.xls (3-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2008.xls (4-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2009.xls (5-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2010.xls (6-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2011.xls (7-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2012.xls (8-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2013.xls (9-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2014.xls (10-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2015.xls (11-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2016.xls (12-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2017.xls (13-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2018.xls (14-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2019.xls (15-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2020.xls (16-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2021.xls (17-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2022.xls (18-19) Downloading...
## Downloading file /tmp/RtmpkijwPg/TD_cache/LTN_2023.xls (19-19) Downloading...

my.df <- read.TD.files(dl.folder = cache_folder)

## 
## Reading xls data and saving to data.frame
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2005.xls
##     Reading Sheet LTN 040105
##     Reading Sheet LTN 010405
##     Reading Sheet LTN 010705
##     Reading Sheet LTN 011005
##     Reading Sheet LTN 010106
##     Reading Sheet LTN 010406
##     Reading Sheet LTN 010706
##     Reading Sheet LTN 011006
##     Reading Sheet LTN 010107
##     Reading Sheet LTN 010407
##     Reading Sheet LTN 010707
##     Reading Sheet LTN 010108
##     Reading Sheet LTN 010708
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2006.xls
##     Reading Sheet LTN 010406
##     Reading Sheet LTN 010706
##     Reading Sheet LTN 011006
##     Reading Sheet LTN 010107
##     Reading Sheet LTN 010407
##     Reading Sheet LTN 010707
##     Reading Sheet LTN 011007
##     Reading Sheet LTN 010108
##     Reading Sheet LTN 010408
##     Reading Sheet LTN 010708
##     Reading Sheet LTN 010109
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2007.xls
##     Reading Sheet LTN 010407
##     Reading Sheet LTN 010707
##     Reading Sheet LTN 011007
##     Reading Sheet LTN 010108
##     Reading Sheet LTN 010408
##     Reading Sheet LTN 010708
##     Reading Sheet LTN 011008
##     Reading Sheet LTN 010109
##     Reading Sheet LTN 010709
##     Reading Sheet LTN 011009
##     Reading Sheet LTN 010110
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2008.xls
##     Reading Sheet LTN 010408
##     Reading Sheet LTN 010708
##     Reading Sheet LTN 011008
##     Reading Sheet LTN 010109
##     Reading Sheet LTN 010409
##     Reading Sheet LTN 010709
##     Reading Sheet LTN 011009
##     Reading Sheet LTN 010110
##     Reading Sheet LTN 010710
##     Reading Sheet LTN 010111
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2009.xls
##     Reading Sheet LTN 010409
##     Reading Sheet LTN 010709
##     Reading Sheet LTN 011009
##     Reading Sheet LTN 010110
##     Reading Sheet LTN 010710
##     Reading Sheet LTN 010111
##     Reading Sheet LTN 010112
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2010.xls
##     Reading Sheet LTN 010710
##     Reading Sheet LTN 010111
##     Reading Sheet LTN 010711
##     Reading Sheet LTN 010112
##     Reading Sheet LTN 010113
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2011.xls
##     Reading Sheet LTN 010711
##     Reading Sheet LTN 010112
##     Reading Sheet LTN 010113
##     Reading Sheet LTN 010114
##     Reading Sheet LTN 010115
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2012.xls
##     Reading Sheet LTN 010113
##     Reading Sheet LTN 010114
##     Reading Sheet LTN 010115
##     Reading Sheet LTN 010116
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2013.xls
##     Reading Sheet LTN 010114
##     Reading Sheet LTN 010115
##     Reading Sheet LTN 010116
##     Reading Sheet LTN 010117
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2014.xls
##     Reading Sheet LTN 010115
##     Reading Sheet LTN 010116
##     Reading Sheet LTN 010117
##     Reading Sheet LTN 010118
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2015.xls
##     Reading Sheet LTN 010116
##     Reading Sheet LTN 010117
##     Reading Sheet LTN 010118
##     Reading Sheet LTN 010121
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2016.xls
##     Reading Sheet LTN 010117
##     Reading Sheet LTN 010118
##     Reading Sheet LTN 010119
##     Reading Sheet LTN 010121
##     Reading Sheet LTN 010123
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2017.xls
##     Reading Sheet LTN 010118
##     Reading Sheet LTN 010119
##     Reading Sheet LTN 010120
##     Reading Sheet LTN 010121
##     Reading Sheet LTN 010123
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2018.xls
##     Reading Sheet LTN 010119
##     Reading Sheet LTN 010120
##     Reading Sheet LTN 010121
##     Reading Sheet LTN 010123
##     Reading Sheet LTN 010125
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2019.xls
##     Reading Sheet LTN 010120
##     Reading Sheet LTN 010121
##     Reading Sheet LTN 010122
##     Reading Sheet LTN 010123
##     Reading Sheet LTN 010125
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2020.xls
##     Reading Sheet LTN 010121
##     Reading Sheet LTN 010122
##     Reading Sheet LTN 010123
##     Reading Sheet LTN 010125
##     Reading Sheet LTN 010126
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2021.xls
##     Reading Sheet LTN 010122
##     Reading Sheet LTN 010123
##     Reading Sheet LTN 010724
##     Reading Sheet LTN 010125
##     Reading Sheet LTN 010126
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2022.xls
##     Reading Sheet LTN 010123
##     Reading Sheet LTN 010724
##     Reading Sheet LTN 010125
##     Reading Sheet LTN 010126
##     Reading Sheet LTN 010129
##  Reading File = /tmp/RtmpkijwPg/TD_cache/LTN_2023.xls
##     Reading Sheet LTN 010724
##     Reading Sheet LTN 010125
##     Reading Sheet LTN 010126
##     Reading Sheet LTN 010129

Let’s plot the prices to check if the code worked:

library(ggplot2)
library(dplyr)

## 
## Attaching package: 'dplyr'

## The following objects are masked from 'package:stats':
## 
##     filter, lag

## The following objects are masked from 'package:base':
## 
##     intersect, setdiff, setequal, union

# filter  LTN 
my_asset_code <- "LTN 010123"
first_date <- as.Date("2015-01-01")

my.df <- my.df %>%
  filter(ref.date >= first_date)

LTN <- my.df %>%
  filter(asset.code  ==  my_asset_code,
         ref.date >= first_date)

p <- ggplot(data = LTN, 
            aes(x = as.Date(ref.date), 
                y = price.bid, 
                color = asset.code)) + 
  geom_line(size = 1) + scale_x_date() + labs(title = '', x = 'Dates')

## Warning: Using `size` aesthetic for lines was deprecated in ggplot2 3.4.0.
## ℹ Please use `linewidth` instead.

print(p)

As expected, the prices from this bond will converge to its face value, 1000 R$, at the maturity date. We can also look at its time-varying annual yield:

p <- ggplot(data = LTN, 
            aes(x = as.Date(ref.date), 
                y = yield.bid, 
                color = asset.code)) + 
  geom_line(size = 1) + 
  scale_x_date() + 
  labs(title = '', 
       x = 'Dates')

print(p)

By default, GetTDData downloads all available data from the website. Suppose we wanted to look at the prices of all available maturities for bonds of type LTN. Since the data is already downloaded, all we need to do is to plot the prices and yields of the different debt contracts:

# plot data (prices)
p <- ggplot(data = my.df, 
            aes(x = as.Date(ref.date), y = price.bid, color = asset.code)) + 
  geom_line() + 
  scale_x_date() + 
  labs(title = '', x = 'Dates', y = 'Prices' )

print(p)

# plot data (yields)
p <- ggplot(data = my.df, 
            aes(x = as.Date(ref.date), y = yield.bid, color = asset.code)) + 
  geom_line() + 
  scale_x_date() + 
  labs(title = '', x = 'Dates', y = 'Yields' )

print(p)

How to use GetTDData

Marcelo Perlin

2023-01-03

How to use GetTDData