bizdays - Business day calculations with the Brazilian ANBIMA calendar

Igor, thanks for your work on this

I’ve written a finance library and stopped short of implementing the AMBIMA calendar.

I reached out to @kip , maintainer of tempo for tips on how to work with calendars and he wrote a recipe for AMBIMA.

I suggest you take a look. As working with calendars is far from obvious.

Thanks, Roberto, and thanks to @kip for writing that recipe! I hadn’t seen it, and Tempo’s set algebra over intervals is a really nice way to express it.

I read it carefully and noticed two differences that are worth knowing if someone is choosing between the two:

1. Interval convention. The recipe counts [from, to) (start included, end excluded). Bizdays.count/3 uses (from, to] (start excluded, end included), which is how business days are usually counted between a settlement date and a maturity. When both dates are business days, which is the normal case, the two give the same number. They differ when exactly one endpoint falls on a non-business day. For example, from Saturday 2026-02-14 to Wednesday 2026-02-18 (Carnival in between), (from, to] gives 1 and [from, to) gives 0.

2. Holiday source. The recipe loads an .ics file converted from ANBIMA’s spreadsheet with a Python script. bizdays has no data file: holidays are generated from rules at compile time, and the test suite checks all 1,263 dates against the official spreadsheet. So there is nothing to download or convert, and no dependencies, at the cost of doing much less than Tempo.

I see them as complementary. Tempo is the general toolkit, and bizdays is a small, focused piece for people who only need the ANBIMA calendar and the 252 convention. For interop, Bizdays.holidays(calendar, year) returns the dates, so they can be fed into Tempo.

I’m curious about your finance library: what would you have needed from a calendar to keep going? CDI/Selic accrual on top of the calendar is the next thing I’m considering, and I’d like it to fit real use cases.

Igor,

1. I really can’t tell you which convention is correct.

2. As for the source, it comes down to whether you want updates at compile time or runtime. If there is a new holiday, one approach requires a new version of the library, while the other requires a new reference file (the latter also requires runtime parsing and safety checks, which are already solved in a compiled solution).

The Finance library was my first project in Elixir and it essentially ported what I had used in Ruby in the past: a set of functions implementing Excel’s XIRR formula. When I expanded the reach of Finance, I got into some functions that required fractional years. There are many different ways to calculate these: 30/actual, 30/360, etc. bizdays/252 is the Brazilian convention. I didn’t delve into calendar parsing or holiday compiling like you did, and stopped there.

But there is an open door. Finance exposes a DayCount behaviour that simply takes two dates and expects a float. bizdays could solve that as:

defmodule Bizdays252 do
  @behaviour Finance.DayCount
  
  @impl true
  def year_fraction(from, to, _opts) do
    # Using your (from, to] convention directly
    Bizdays.count(Bizdays.anbima(), from, to) / 252
  end
end

# And then feed it to the financial functions:
Finance.CashFlow.xirr(flows, basis: Bizdays252)

For actual CDI accrual, you would need a historical calendar of rates and the dates they changed, allowing you to compound the value across the various rate windows in the period. Kinda like this.

Roberto, this is really useful!

Good point on compile time vs runtime. I went with compile time on purpose: ANBIMA’s national calendar changes rarely, and when it does (like November 20 in 2024) it is announced well in advance, so a new patch release felt safer than parsing a file at runtime.

I tried your snippet as-is with bizdays 0.1.0 and Finance 1.8.0, and it works. For a -1000 / +1100 pair from 2025-01-02 to 2026-01-02 (exactly 252 business days), xirr(flows, basis: Bizdays252) returns {:ok, 0.1}, matching 1.1^(252/n) - 1. One behaviour worth documenting: the ANBIMA calendar covers 2001–2099, so a cash flow outside that range raises an ArgumentError from bizdays through xirr instead of returning {:error, _}.

I’ll add a “Using with Finance” section to the bizdays docs with your example. If you think it makes sense, a link from Finance’s DayCount docs would help people looking for BUS/252 find it. Happy to open a PR for that if you’d like.

On CDI: agreed, that needs the rate history (the daily CDI series from the Central Bank), which is runtime data. So it probably belongs in a separate package built on top of bizdays, not inside it. Thanks for the pointer.