Pular para conteúdo

LTN

data(date)

Fetch the LTN Anbima indicative rates for the given reference date.

Parameters:

Name Type Description Default
date DateScalar

The reference date for fetching the data.

 required

Returns:

Type Description
DataFrame

pd.DataFrame: DataFrame with columns "MaturityDate" and "IndicativeRate".

Examples:

>>> from pyield import ltn
>>> ltn.data("23-08-2024")
   ReferenceDate BondType MaturityDate  IndicativeRate       Price
0     2024-08-23      LTN   2024-10-01        0.104416  989.415342
1     2024-08-23      LTN   2025-01-01        0.107171  964.293046
2     2024-08-23      LTN   2025-04-01        0.110866  938.943013
3     2024-08-23      LTN   2025-07-01        0.113032  913.849158
4     2024-08-23      LTN   2025-10-01        0.114374  887.394285
5     2024-08-23      LTN   2026-01-01        0.114654  863.026594
6     2024-08-23      LTN   2026-04-01        0.114997  840.232741
7     2024-08-23      LTN   2026-07-01        0.115265  818.020491
8     2024-08-23      LTN   2026-10-01        0.115357  795.185488
9     2024-08-23      LTN   2027-07-01        0.115335  733.981131
10    2024-08-23      LTN   2028-01-01        0.115694  693.647778
11    2024-08-23      LTN   2028-07-01        0.116417    655.6398
12    2024-08-23      LTN   2030-01-01        0.117436  554.331151
Source code in pyield/tn/ltn.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
def data(date: DateScalar) -> pd.DataFrame:
    """
    Fetch the LTN Anbima indicative rates for the given reference date.

    Args:
        date (DateScalar): The reference date for fetching the data.

    Returns:
        pd.DataFrame: DataFrame with columns "MaturityDate" and "IndicativeRate".

    Examples:
        >>> from pyield import ltn
        >>> ltn.data("23-08-2024")
           ReferenceDate BondType MaturityDate  IndicativeRate       Price
        0     2024-08-23      LTN   2024-10-01        0.104416  989.415342
        1     2024-08-23      LTN   2025-01-01        0.107171  964.293046
        2     2024-08-23      LTN   2025-04-01        0.110866  938.943013
        3     2024-08-23      LTN   2025-07-01        0.113032  913.849158
        4     2024-08-23      LTN   2025-10-01        0.114374  887.394285
        5     2024-08-23      LTN   2026-01-01        0.114654  863.026594
        6     2024-08-23      LTN   2026-04-01        0.114997  840.232741
        7     2024-08-23      LTN   2026-07-01        0.115265  818.020491
        8     2024-08-23      LTN   2026-10-01        0.115357  795.185488
        9     2024-08-23      LTN   2027-07-01        0.115335  733.981131
        10    2024-08-23      LTN   2028-01-01        0.115694  693.647778
        11    2024-08-23      LTN   2028-07-01        0.116417    655.6398
        12    2024-08-23      LTN   2030-01-01        0.117436  554.331151

    """
    return anbima.tpf_data(date, "LTN")

di_spreads(date)

Calculates the DI spread for the LTN based on ANBIMA's indicative rates.

This function fetches the indicative rates for the NTN-F bonds and the DI futures rates and calculates the spread between these rates in basis points.

Parameters:

Name Type Description Default
date DateScalar

The reference date for the spread calculation.

 required

Returns:

Type Description
DataFrame

pd.DataFrame: DataFrame with the columns "MaturityDate" and "DISpread" (in bps).

Examples:

>>> from pyield import ltn
>>> spreads = ltn.di_spreads("22-08-2024")
>>> spreads["DISpread"] = spreads["DISpread"] * 10000  # Convert to bps
>>> spreads
   MaturityDate  DISpread
0    2024-10-01     -3.06
1    2025-01-01     -9.95
2    2025-04-01     -8.28
3    2025-07-01      -6.1
4    2025-10-01     -2.57
5    2026-01-01     -1.57
6    2026-04-01     -0.86
7    2026-07-01      2.83
8    2026-10-01      4.17
9    2027-07-01      3.72
10   2028-01-01      6.19
11   2028-07-01      8.68
12   2030-01-01     14.96
Source code in pyield/tn/ltn.py 
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
def di_spreads(date: DateScalar) -> pd.DataFrame:
    """
    Calculates the DI spread for the LTN based on ANBIMA's indicative rates.

    This function fetches the indicative rates for the NTN-F bonds and the DI futures
    rates and calculates the spread between these rates in basis points.

    Parameters:
        date (DateScalar, optional): The reference date for the
            spread calculation.

    Returns:
        pd.DataFrame: DataFrame with the columns "MaturityDate" and "DISpread" (in bps).

    Examples:
        >>> from pyield import ltn
        >>> spreads = ltn.di_spreads("22-08-2024")
        >>> spreads["DISpread"] = spreads["DISpread"] * 10000  # Convert to bps
        >>> spreads
           MaturityDate  DISpread
        0    2024-10-01     -3.06
        1    2025-01-01     -9.95
        2    2025-04-01     -8.28
        3    2025-07-01      -6.1
        4    2025-10-01     -2.57
        5    2026-01-01     -1.57
        6    2026-04-01     -0.86
        7    2026-07-01      2.83
        8    2026-10-01      4.17
        9    2027-07-01      3.72
        10   2028-01-01      6.19
        11   2028-07-01      8.68
        12   2030-01-01     14.96
    """
    # Fetch DI Spreads for the reference date
    df = tools.pre_spreads(date)
    df.query("BondType == 'LTN'", inplace=True)
    df.sort_values(["MaturityDate"], ignore_index=True, inplace=True)
    return df[["MaturityDate", "DISpread"]]

dv01(settlement, maturity, rate)

Calculate the DV01 (Dollar Value of 01) for an LTN in R$.

Represents the price change in R$ for a 1 basis point (0.01%) increase in yield.

Parameters:

Name Type Description Default
settlement DateScalar

The settlement date in 'DD-MM-YYYY' format or a pandas Timestamp.

 required
maturity DateScalar

The maturity date in 'DD-MM-YYYY' format or a pandas Timestamp.

 required
rate float

The discount rate used to calculate the present value of the cash flows, which is the yield to maturity (YTM) of the LTN.

 required

Returns:

Name Type Description
float float

The DV01 value, representing the price change for a 1 basis point increase in yield.

Examples:

>>> from pyield import ltn
>>> ltn.dv01("26-03-2025", "01-01-2032", 0.150970)
0.2269059999999854
Source code in pyield/tn/ltn.py 
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
def dv01(
    settlement: DateScalar,
    maturity: DateScalar,
    rate: float,
) -> float:
    """
    Calculate the DV01 (Dollar Value of 01) for an LTN in R$.

    Represents the price change in R$ for a 1 basis point (0.01%) increase in yield.

    Args:
        settlement (DateScalar): The settlement date in 'DD-MM-YYYY' format
            or a pandas Timestamp.
        maturity (DateScalar): The maturity date in 'DD-MM-YYYY' format or
            a pandas Timestamp.
        rate (float): The discount rate used to calculate the present value of
            the cash flows, which is the yield to maturity (YTM) of the LTN.

    Returns:
        float: The DV01 value, representing the price change for a 1 basis point
            increase in yield.

    Examples:
        >>> from pyield import ltn
        >>> ltn.dv01("26-03-2025", "01-01-2032", 0.150970)
        0.2269059999999854
    """
    price1 = price(settlement, maturity, rate)
    price2 = price(settlement, maturity, rate + 0.0001)
    return price1 - price2

historical_premium(date, maturity)

Calculate the premium of the LTN bond over the DI Future rate for a given date.

Parameters:

Name Type Description Default
date DateScalar

The reference date to fetch the rates.

 required
maturity DateScalar

The maturity date of the LTN bond.

 required

Returns:

Name Type Description
float float

The premium of the LTN bond over the DI Future rate for the given date. If the data is not available, returns NaN.

Examples:

>>> from pyield import ltn
>>> ltn.historical_premium("22-08-2024", "01-01-2030")
1.0120718007994287
Source code in pyield/tn/ltn.py 
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
def historical_premium(
    date: DateScalar,
    maturity: DateScalar,
) -> float:
    """
    Calculate the premium of the LTN bond over the DI Future rate for a given date.

    Args:
        date (DateScalar): The reference date to fetch the rates.
        maturity (DateScalar): The maturity date of the LTN bond.

    Returns:
        float: The premium of the LTN bond over the DI Future rate for the given date.
               If the data is not available, returns NaN.

    Examples:
        >>> from pyield import ltn
        >>> ltn.historical_premium("22-08-2024", "01-01-2030")
        1.0120718007994287

    """
    # Convert input dates to a consistent format
    date = dc.convert_input_dates(date)
    maturity = dc.convert_input_dates(maturity)

    # Retrieve LTN rates for the reference date
    df_anbima = data(date)
    if df_anbima.empty:
        return float("NaN")

    # Extract the LTN rate for the specified maturity date
    ltn_rates = df_anbima.query("MaturityDate == @maturity")["IndicativeRate"]
    if ltn_rates.empty:
        return float("NaN")
    ltn_rate = float(ltn_rates.iloc[0])

    # Retrieve DI rate for the reference date and maturity
    di_rate = di1.interpolate_rate(date=date, expiration=maturity, extrapolate=True)
    if pd.isnull(di_rate):  # Check if the DI rate is NaN
        return float("NaN")

    # Calculate and return the premium using the extracted rates
    return premium(ltn_rate, di_rate)

maturities(date)

Fetch the bond maturities available for the given reference date.

Parameters:

Name Type Description Default
date DateScalar

The reference date for fetching the data.

 required

Returns:

Type Description
Series

pd.Series: A Series of bond maturities available for the reference date.

Examples:

>>> from pyield import ltn
>>> ltn.maturities("22-08-2024")
0    2024-10-01
1    2025-01-01
2    2025-04-01
3    2025-07-01
4    2025-10-01
5    2026-01-01
6    2026-04-01
7    2026-07-01
8    2026-10-01
9    2027-07-01
10   2028-01-01
11   2028-07-01
12   2030-01-01
dtype: datetime64[ns]
Source code in pyield/tn/ltn.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def maturities(date: DateScalar) -> pd.Series:
    """
    Fetch the bond maturities available for the given reference date.

    Args:
        date (DateScalar): The reference date for fetching the data.

    Returns:
        pd.Series: A Series of bond maturities available for the reference date.

    Examples:
        >>> from pyield import ltn
        >>> ltn.maturities("22-08-2024")
        0    2024-10-01
        1    2025-01-01
        2    2025-04-01
        3    2025-07-01
        4    2025-10-01
        5    2026-01-01
        6    2026-04-01
        7    2026-07-01
        8    2026-10-01
        9    2027-07-01
        10   2028-01-01
        11   2028-07-01
        12   2030-01-01
        dtype: datetime64[ns]

    """
    df_rates = data(date)
    s_maturities = df_rates["MaturityDate"]
    s_maturities.name = None
    return s_maturities

premium(ltn_rate, di_rate)

Calculate the premium of the LTN bond over the DI Future rate using provided rates.

Parameters:

Name Type Description Default
ltn_rate float

The annualized LTN rate.

 required
di_rate float

The annualized DI Future rate.

 required

Returns:

Name Type Description
float float

The premium of the LTN bond over the DI Future rate.

Examples:

Reference date: 22-08-2024 LTN rate for 01-01-2030: 0.118746 DI (JAN30) Settlement rate: 0.11725

>>> from pyield import ltn
>>> ltn.premium(0.118746, 0.11725)
1.0120718007994287
Source code in pyield/tn/ltn.py 
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
def premium(ltn_rate: float, di_rate: float) -> float:
    """
    Calculate the premium of the LTN bond over the DI Future rate using provided rates.

    Args:
        ltn_rate (float): The annualized LTN rate.
        di_rate (float): The annualized DI Future rate.

    Returns:
        float: The premium of the LTN bond over the DI Future rate.

    Examples:
        Reference date: 22-08-2024
        LTN rate for 01-01-2030: 0.118746
        DI (JAN30) Settlement rate: 0.11725
        >>> from pyield import ltn
        >>> ltn.premium(0.118746, 0.11725)
        1.0120718007994287
    """
    # Cálculo das taxas diárias
    ltn_daily_rate = (1 + ltn_rate) ** (1 / 252) - 1
    di_daily_rate = (1 + di_rate) ** (1 / 252) - 1

    # Retorno do cálculo do prêmio
    return ltn_daily_rate / di_daily_rate

price(settlement, maturity, rate)

Calculate the LTN price using Anbima rules.

Parameters:

Name Type Description Default
settlement DateScalar

The settlement date in 'DD-MM-YYYY' format or a pandas Timestamp.

 required
maturity DateScalar

The maturity date in 'DD-MM-YYYY' format or a pandas Timestamp.

 required
rate float

The discount rate used to calculate the present value of the cash flows, which is the yield to maturity (YTM) of the NTN-F.

 required

Returns:

Name Type Description
float float

The LTN price using Anbima rules.
References
  • https://www.anbima.com.br/data/files/A0/02/CC/70/8FEFC8104606BDC8B82BA2A8/Metodologias%20ANBIMA%20de%20Precificacao%20Titulos%20Publicos.pdf

Examples:

>>> from pyield import ltn
>>> ltn.price("05-07-2024", "01-01-2030", 0.12145)
535.279902
Source code in pyield/tn/ltn.py 
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def price(
    settlement: DateScalar,
    maturity: DateScalar,
    rate: float,
) -> float:
    """
    Calculate the LTN price using Anbima rules.

    Args:
        settlement (DateScalar): The settlement date in 'DD-MM-YYYY' format
            or a pandas Timestamp.
        maturity (DateScalar): The maturity date in 'DD-MM-YYYY' format or
            a pandas Timestamp.
        rate (float): The discount rate used to calculate the present value of
            the cash flows, which is the yield to maturity (YTM) of the NTN-F.

    Returns:
        float: The LTN price using Anbima rules.

    References:
        - https://www.anbima.com.br/data/files/A0/02/CC/70/8FEFC8104606BDC8B82BA2A8/Metodologias%20ANBIMA%20de%20Precificacao%20Titulos%20Publicos.pdf

    Examples:
        >>> from pyield import ltn
        >>> ltn.price("05-07-2024", "01-01-2030", 0.12145)
        535.279902
    """

    # Validate and normalize dates
    settlement = dc.convert_input_dates(settlement)
    maturity = dc.convert_input_dates(maturity)

    # Calculate the number of business days between settlement and cash flow dates
    bdays = bday.count(settlement, maturity)

    # Calculate the number of periods truncated as per Anbima rule
    num_of_years = tools.truncate(bdays / 252, 14)

    discount_factor = (1 + rate) ** num_of_years

    # Truncate the price to 6 decimal places as per Anbima rules
    return tools.truncate(FACE_VALUE / discount_factor, 6)