Dates and periods

This page lists everything you need to turn market lengths into dates: tenors such as 3M and 2Y as values, the month arithmetic that adds them to a date, forward tenors such as 2Y2Y, and the dates markets name rather than count, such as IMM dates, CDS dates and nth weekdays.

Quick example

This reads six tenor spellings and shows each one's canonical form and its length in months or in days.

Rust

use helixrs::{
    ForwardTenor, Period,
};

fn tenor(spelling: &str) -> Period {
    spelling.parse().expect("a tenor spelling")
}

fn show(value: Option<i32>) -> String {
    value.map_or_else(|| "-".to_owned(), |v| v.to_string())
}

fn main() -> Result<(), Box<dyn std::error::Error>> {

    // A tenor is a count and a unit letter. The spelling is read
    // case-insensitively and written back canonically; a month or year tenor
    // has a length in months, a day or week tenor a length in days, and neither
    // has both.
    println!("{:<9} {:<10} {:>6} {:>5}", "spelling", "canonical", "months", "days");
    for spelling in ["3m", "1Y", "18M", "2w", "7D", "-1Y"] {
        let period = tenor(spelling);
        let (months, days) = (period.in_months(), period.in_days());
        println!(
            "{spelling:<9} {:<10} {:>6} {:>5}",
            period.to_string(),
            show(months),
            show(days)
        );
    }

    Ok(())
}

Python

import helixio as hlx

dates = hlx.dates

def show(value: object) -> str:
    return "-" if value is None else str(value)

# A tenor is a count and a unit letter. The spelling is read case-insensitively
# and written back canonically; a month or year tenor has a length in months,
# a day or week tenor a length in days, and neither has both.
print(f"{'spelling':<9} {'canonical':<10} {'months':>6} {'days':>5}")
for spelling in ("3m", "1Y", "18M", "2w", "7D", "-1Y"):
    period = dates.Period(spelling)
    months, days = period.in_months(), period.in_days()
    print(f"{spelling:<9} {period!s:<10} {show(months):>6} {show(days):>5}")

spelling  canonical  months  days
3m        3M              3     -
1Y        1Y             12     -
18M       18M            18     -
2w        2W              -    14
7D        7D              -     7
-1Y       -1Y           -12     -

A month or year tenor has a length in months, a day or week tenor a length in days, and neither has both. Spellings are read case-insensitively and written back canonically.

API

Name	Meaning	Rust	Python
tenor	a signed count and a unit, compared by duration	`Period`, parsed from its spelling	`dates.Period`
month arithmetic	add a tenor to a date, clamping the day	`add_period`	`dates.add_period`
a month's last day	the clamp's limit	`last_day_of_month`	`dates.last_day_of_month`
forward tenor	a forward start and a term	`ForwardTenor`	`dates.forward_tenor`
IMM date	the third Wednesday of an IMM month	`next_imm_date`, `is_imm_date`, `imm_code_of`	`dates.next_imm_date`, `dates.is_imm_date`, `dates.imm_code_of`
IMM code	the period starting on the coded IMM date	`imm_code_to_dates`	`dates.imm_code_to_dates`
CDS date	the twentieth of an IMM month	`next_cds_imm_date`, `cds_standard_maturity`	`dates.next_cds_imm_date`, `dates.cds_standard_maturity`
roll convention	snap a date inside its month	`RollConvention`	`dates.roll`, `dates.RollConvention`

Argument	Type	Default	Meaning
`Period(spelling)`	`str`	required	`"3M"`, `"1Y"`, `"2W"`, `"7D"`, signed with `-`; a compound such as `"1Y3M"` is the sum of its segments
`add_period(date, tenor)`	`date`, `Period` or `str`	required	month arithmetic for months and years, calendar days for days and weeks
`forward_tenor(spelling)`	`str`	required	a forward start and a term, such as `"2Y2Y"`
`next_imm_date(date, cycle=)`	`date`, `str`	`cycle="Quarterly"`	the next IMM date strictly after `date`; `"Monthly"` uses every month
`is_imm_date(date, cycle=)`	`date`, `str`	`cycle="Quarterly"`	whether `date` is an IMM date of the cycle
`imm_date(month, year, cycle=, day=)`	`int`, `int`, `str`, `str`	`cycle="Quarterly"`, `day="ThirdWednesday"`	the IMM date of a month; `day="WednesdayOnOrAfterNinth"` is the other day rule
`imm_code_of(date)`	`date`	required	the code, such as `MAR26`, of an IMM date
`imm_code_to_dates(code, cycle=)`	`str`, `str`	`cycle="Quarterly"`	the period that starts on the coded date and runs to the next IMM date
`next_cds_imm_date(date)`	`date`	required	the next twentieth of an IMM month
`cds_standard_maturity(date, tenor_years)`	`date`, `int`	required	the on-the-run CDS maturity for a trade date
`nth_weekday(n, weekday, year, month)`	`int`, `str`, `int`, `int`	required	the `n`th named weekday of a month
`roll(date, roll_convention)`	`date`, `RollConvention` or `str`	required	snaps a date inside its month, such as `"EOM"` or `"IMM20"`

Defaults and limits

Clamping. Adding months keeps the day and clamps it to the target month's length. Clamping loses information: two one-month steps from 31 January land on 28 March, one two-month step lands on 31 March. That's why a schedule measures every boundary from one anchor.
Tenors compare by duration. 12M equals 1Y and 7D equals 1W. Comparing a month tenor with a day tenor, such as one month against thirty days, is refused rather than guessed.
Compound tenors sum descending segments of one family: "1Y3M" is fifteen months, "2W3D" seventeen days. Mixing months with days is refused.
IMM codes name a period, not a day: MAR26 runs from the March IMM date to the June one, the same period a futures template's reference period gives.
CDS maturities roll twice a year. The trade date moves to the next roll date, 20 March or 20 September, the tenor is added, and the result steps back to the 20 June or 20 December on or before it. So an on-the-run 5Y maturity can sit up to three months short of five years: 2026-03-19 matures on 2030-12-20.
Two IMM day rules. By default an IMM date is the third Wednesday. "WednesdayOnOrAfterNinth" is the 9th rolled forward to a Wednesday, the 9th itself included; in a month whose 9th is a Wednesday, the two rules land a week apart.

!!! warning "2Y3M means different things in different places" As a Period, "2Y3M" is one compound tenor, twenty-seven months. A swap builder's with_maturity reads the same spelling as a forward tenor: three months starting in two years. Write "27M" for a 27-month maturity, so the intent can't be misread.

More examples

Every feature above in one program: month arithmetic against the clamping rule, forward tenors, IMM dates and codes, CDS dates either side of the March roll, nth weekdays and rolls, compound tenors, and the two IMM day rules. The example reads no shared data.