Skip to content

Commit 646763a

Browse files
attack68attack68
authored
DOC: bond updates (#206) (#1122)
1 parent 9ea9f6d commit 646763a

File tree

3 files changed

+183
-9
lines changed

3 files changed

+183
-9
lines changed

‎python/rateslib/instruments/bonds/conventions/__init__.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ class BondCalcMode:
8484
&AI_y = \\xi_y c_i \\qquad \\text{if not ex-dividend} \\\\
8585
&AI_y = (\\xi_y - 1) c_i \\qquad \\text{if ex-dividend} \\\\
8686
87-
Where in both these formula :math:`c_i` currently always uses the real ``cashflow`` method
87+
Where in both these formulae :math:`c_i` currently always uses the real ``cashflow`` method
8888
(see below).
8989
9090
These two methods are almost always the same, but for an example where they differ consider
@@ -162,7 +162,7 @@ def _linear_days(obj, settlement, acc_idx, *args) -> float:
162162
.. math::
163163
164164
P &= v_1 \\left ( c_1 + 100 \\right ), \\quad n = 1 \\\\
165-
P &= v_1 \\left ( c_1 + v3(c_n + 100) \\right ), \\quad n = 2 \\\\
165+
P &= v_1 \\left ( c_1 + v_3 (c_n + 100) \\right ), \\quad n = 2 \\\\
166166
P &= v_1 \\left ( c_1 + \\sum_{i=2}^{n-1} c_i v_2^{i-2} v_{2,i} + c_nv_2^{n-2}v_3 + 100 v_2^{n-2}v_3 \\right ), \\quad n > 2 \\\\
167167
Q &= P - AI_y
168168

‎python/rateslib/instruments/bonds/fixed_rate_bond.py‎

Lines changed: 29 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,35 @@
4242

4343
class FixedRateBond(_BaseBondInstrument):
4444
"""
45-
A *interest rate swap (IRS)* composing a :class:`~rateslib.legs.FixedLeg`
46-
and a :class:`~rateslib.legs.FloatLeg`.
45+
A *fixed rate bond* composed of a :class:`~rateslib.legs.FixedLeg`.
46+
47+
.. rubric:: Examples
48+
49+
.. ipython:: python
50+
:suppress:
51+
52+
from rateslib.instruments import FixedRateBond
53+
from datetime import datetime as dt
54+
55+
.. ipython:: python
56+
57+
frb = FixedRateBond(
58+
effective=dt(2000, 1, 1),
59+
termination="2y",
60+
spec="us_gb",
61+
fixed_rate=2.0,
62+
)
63+
frb.cashflows()
64+
65+
.. rubric:: Pricing
66+
67+
A *FixedRateBond* requires one *disc curve*. The following input formats are
68+
allowed:
69+
70+
.. code-block:: python
71+
72+
curves = curve | [curve] # a single curve is repeated for all required curves
73+
curves = {"disc_curve": disc_curve} # dict form is explicit
4774
4875
.. role:: red
4976
@@ -118,10 +145,6 @@ class FixedRateBond(_BaseBondInstrument):
118145
The local settlement currency of the *Instrument* (3-digit code).
119146
notional : float, Dual, Dual2, Variable, :green:`optional (set by 'defaults')`
120147
The initial leg notional, defined in units of *reference currency*.
121-
amortization: float, Dual, Dual2, Variable, str, Amortization, :green:`optional (set as zero)`
122-
Set a non-constant notional per *Period*. If a scalar value, adjusts the ``notional`` of
123-
each successive period by that same value. Should have
124-
sign equal to that of notional if the notional is to reduce towards zero.
125148
126149
.. note::
127150

‎python/rateslib/instruments/bonds/float_rate_note.py‎

Lines changed: 152 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,158 @@
4545

4646
class FloatRateNote(_BaseBondInstrument):
4747
"""
48-
Create a floating rate note (FRN) security.
48+
A *floating rate note (FRN)* composed of a :class:`~rateslib.legs.FloatLeg`.
49+
50+
.. rubric:: Examples
51+
52+
.. ipython:: python
53+
:suppress:
54+
55+
from rateslib.instruments import FloatRateNote
56+
from datetime import datetime as dt
57+
58+
.. ipython:: python
59+
60+
frn = FloatRateNote(
61+
effective=dt(2000, 1, 1),
62+
termination="2y",
63+
frequency="A",
64+
currency="usd",
65+
fixing_method="rfr_observation_shift",
66+
method_param=5,
67+
convention="Act360",
68+
calendar="nyc|fed",
69+
float_spread=25.0,
70+
)
71+
frn.cashflows()
72+
73+
.. rubric:: Pricing
74+
75+
A *FloatRateNote* requires a *disc curve* and a *rate curve*. The following input formats are
76+
allowed:
77+
78+
.. code-block:: python
79+
80+
curves = curve | [curve] # a single curve is repeated for all required curves
81+
curves = [rate_curve, disc_curve] # a sequence of two curves
82+
curves = { # dict form is explicit
83+
"disc_curve": disc_curve,
84+
"rate_curve": rate_curve,
85+
}
86+
87+
.. role:: red
88+
89+
.. role:: green
90+
91+
Parameters
92+
----------
93+
.
94+
95+
.. note::
96+
97+
The following define generalised **scheduling** parameters.
98+
99+
effective : datetime, :red:`required`
100+
The unadjusted effective date. If given as adjusted, unadjusted alternatives may be
101+
inferred.
102+
termination : datetime, str, :red:`required`
103+
The unadjusted termination date. If given as adjusted, unadjusted alternatives may be
104+
inferred. If given as string tenor will be calculated from ``effective``.
105+
frequency : Frequency, str, :red:`required`
106+
The frequency of the schedule.
107+
If given as string will derive a :class:`~rateslib.scheduling.Frequency` aligning with:
108+
monthly ("M"), quarterly ("Q"), semi-annually ("S"), annually("A") or zero-coupon ("Z"), or
109+
a set number of calendar or business days ("_D", "_B"), weeks ("_W"), months ("_M") or
110+
years ("_Y").
111+
Where required, the :class:`~rateslib.scheduling.RollDay` is derived as per ``roll``
112+
and business day calendar as per ``calendar``.
113+
stub : StubInference, str in {"ShortFront", "LongFront", "ShortBack", "LongBack"}, :green:`optional`
114+
The stub type used if stub inference is required. If given as string will derive a
115+
:class:`~rateslib.scheduling.StubInference`.
116+
front_stub : datetime, :green:`optional`
117+
The unadjusted date for the start stub period. If given as adjusted, unadjusted
118+
alternatives may be inferred.
119+
back_stub : datetime, :green:`optional`
120+
The unadjusted date for the back stub period. If given as adjusted, unadjusted
121+
alternatives may be inferred.
122+
See notes for combining ``stub``, ``front_stub`` and ``back_stub``
123+
and any automatic stub inference.
124+
roll : RollDay, int in [1, 31], str in {"eom", "imm", "som"}, :green:`optional`
125+
The roll day of the schedule. If not given or not available in ``frequency`` will be
126+
inferred for monthly frequency variants.
127+
eom : bool, :green:`optional`
128+
Use an end of month preference rather than regular rolls for ``roll`` inference. Set by
129+
default. Not required if ``roll`` is defined.
130+
modifier : Adjuster, str in {"NONE", "F", "MF", "P", "MP"}, :green:`optional`
131+
The :class:`~rateslib.scheduling.Adjuster` used for adjusting unadjusted schedule dates
132+
into adjusted dates. If given as string must define simple date rolling rules.
133+
calendar : calendar, str, :green:`optional`
134+
The business day calendar object to use. If string will call
135+
:meth:`~rateslib.scheduling.get_calendar`.
136+
payment_lag: Adjuster, int, :green:`optional`
137+
The :class:`~rateslib.scheduling.Adjuster` to use to map adjusted schedule dates into
138+
a payment date. If given as integer will define the number of business days to
139+
lag payments by.
140+
payment_lag_exchange: Adjuster, int, :green:`optional`
141+
The :class:`~rateslib.scheduling.Adjuster` to use to map adjusted schedule dates into
142+
additional payment date. If given as integer will define the number of business days to
143+
lag payments by.
144+
ex_div: Adjuster, int, :green:`optional`
145+
The :class:`~rateslib.scheduling.Adjuster` to use to map adjusted schedule dates into
146+
additional dates, which may be used, for example by fixings schedules. If given as integer
147+
will define the number of business days to lag dates by.
148+
convention: str, :green:`optional (set by 'defaults')`
149+
The day count convention applied to calculations of period accrual dates.
150+
See :meth:`~rateslib.scheduling.dcf`.
151+
152+
.. note::
153+
154+
The following define generalised **settlement** parameters.
155+
156+
currency : str, :green:`optional (set by 'defaults')`
157+
The local settlement currency of the *Instrument* (3-digit code).
158+
notional : float, Dual, Dual2, Variable, :green:`optional (set by 'defaults')`
159+
The initial leg notional, defined in units of *reference currency*.
160+
161+
.. note::
162+
163+
The following are **rate parameters**.
164+
165+
fixing_method: FloatFixingMethod, str, :green:`optional (set by 'defaults')`
166+
The :class:`~rateslib.enums.parameters.FloatFixingMethod` describing the determination
167+
of the floating rate for each period.
168+
method_param: int, :green:`optional (set by 'defaults')`
169+
A specific parameter that is used by the specific ``fixing_method``.
170+
fixing_frequency: Frequency, str, :green:`optional (set by 'frequency' or '1B')`
171+
The :class:`~rateslib.scheduling.Frequency` as a component of the
172+
:class:`~rateslib.data.fixings.FloatRateIndex`. If not given is assumed to match the
173+
frequency of the schedule for an IBOR type ``fixing_method`` or '1B' if RFR type.
174+
fixing_series: FloatRateSeries, str, :green:`optional (implied by other parameters)`
175+
The :class:`~rateslib.data.fixings.FloatRateSeries` as a component of the
176+
:class:`~rateslib.data.fixings.FloatRateIndex`. If not given inherits attributes given
177+
such as the ``calendar``, ``convention``, ``method_param`` etc.
178+
float_spread: float, Dual, Dual2, Variable, :green:`optional (set as 0.0)`
179+
The amount (in bps) added to the rate in each period rate determination.
180+
spread_compound_method: SpreadCompoundMethod, str, :green:`optional (set by 'defaults')`
181+
The :class:`~rateslib.enums.parameters.SpreadCompoundMethod` used in the calculation
182+
of the period rate when combining a ``float_spread``. Used **only** with RFR type
183+
``fixing_method``.
184+
rate_fixings: float, Dual, Dual2, Variable, Series, str, :green:`optional`
185+
See XXX (working with fixings).
186+
The value of the rate fixing. If a scalar, is used directly. If a string identifier, links
187+
to the central ``fixings`` object and data loader.
188+
189+
.. note::
190+
191+
The following are **meta parameters**.
192+
193+
curves : XXX
194+
Pricing objects passed directly to the *Instrument's* methods' ``curves`` argument.
195+
calc_mode : str or BondCalcMode
196+
A calculation mode for dealing with bonds under different conventions. See notes.
197+
spec: str, :green:`optional`
198+
A collective group of parameters. See
199+
:ref:`default argument specifications <defaults-arg-input>`.
49200
50201
"""
51202

0 commit comments

Comments
 (0)