Title:	A Financial Calculator
Version:	0.1.4
Maintainer:	Xianying Tan <shrektan@126.com>
Description:	A financial calculator that provides very fast implementations of common financial indicators using 'Rust' code. It includes functions for bond-related indicators, such as yield to maturity ('YTM'), modified duration, and Macaulay duration, as well as functions for calculating time-weighted and money-weighted rates of return (using 'Modified Dietz' method) for multiple portfolios, given their market values and profit and loss ('PnL') data. 'fcl' is designed to be efficient and accurate for financial analysis and computation. The methods used in this package are based on the following references: https://en.wikipedia.org/wiki/Modified_Dietz_method, https://en.wikipedia.org/wiki/Time-weighted_return.
URL:	https://github.com/shrektan/fcl, https://shrektan.github.io/fcl/
BugReports:	https://github.com/shrektan/fcl/issues
SystemRequirements:	Cargo (Rust's package manager), rustc
Biarch:	true
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.2
Suggests:	testthat (≥ 3.0.0)
Imports:	xts, ymd
Config/testthat/edition:	3
Config/rextendr/version:	0.3.1.9001
Depends:	R (≥ 4.2)
NeedsCompilation:	yes
Packaged:	2025-04-15 08:10:12 UTC; shrektan
Author:	Xianying Tan [aut, cre], Raymon Mina [ctb] (find_root.rs, xirr.rs), The authors of the dependency Rust crates [ctb] (see inst/AUTHORS file for details)
Repository:	CRAN
Date/Publication:	2025-04-15 08:20:02 UTC

Create Fixed Bond Object

Description

Create Fixed Bond Object

Usage

fixed_bond(value_date, mty_date, redem_value, cpn_rate, cpn_freq)

Arguments

Value

it returns an environment containing the following objects:

• .self: an external pointer of the Rust object.

• len(): a function returns the length of the internal bonds object.

• ytm_dur(ref_date, clean_price): a function returns a data.frame, with three columns, 'YTM' (Yield to Maturity), 'MODD' (Modified Duration) and 'MACD' (Macaulay Duration).

• cf(ref_date): a function returns the schedualed bond cashflows, in xts format.

Note

• all arguments must be the same length or 1.

• The date input will be converted to Date object via ymd::ymd().

• It doesn't take the day count convention into account for now.

• There's no support for business day calendar. The dates in the cashflow projection are the same days in the next few months (see ymd::edate()). It considers different days in each month but no weekend date adjustment.

• The 'YTM' value is the cashflow's 'IRR' (internal rate of return) value. Thus, it doesn't equal to the Excel's Yield value, which is adjusted using this formula YTM (fcl) = (1 + frac{Yield (Excel)}{n})^n - 1, where n is the the coupon payment frequency, when the remaining life of the bond is larger than 1.

• When the bond is going to mature within one year, the Yield (Excel) = frac{Cashflow}{Price} - 1.

Examples

bond <- fixed_bond(
  value_date = 210101,
  mty_date = c(250101, 300201),
  redem_value = 100,
  cpn_rate = c(0.05, 0.03),
  cpn_freq = c(0, 1)
)
bond$ytm_dur(
  ref_date = c(220101, 220201),
  clean_price = 100
)
bond$cf(
  ref_date = c(220101, 220131)
)

Create a Return Object

Description

By providing a "group" (ids) of dates, mvs and pls, calucating the Time-weighted Rate of Return (TWRR) or Modified Dietz Rate of Return (DIETZ).

Usage

make_rtn(date, mv, pl, id = 1L)

Arguments

Value

A list of functions, with signature of from, to and id, all of which are only allowed to accept a scalar. They all return an xts object with one column.

• twrr_cr: the cumulative Time-weighted Return

• twrr_dr: the daily Time-weighted Return

• dietz: the Modified Dietz Return

• dietz_avc: the denominator used to calculate the 'Modifie Dietz Return

• cum_pl: the cumulative PnL

Cash flow handling

• The cash flow is not provided externally. Instead, it's deducted via market value and PnL, with the equation \Delta MV = \Delta PnL + CF.

• The cash inflow is treating as if it happens at the beginning of the day, while the cash outflow is at the end of the day. The reasons are two. The first is to reduce the possibility of having a close-to-zero denominator. The second is the cash is usually not usable for the whole day.

• The calculation is based on calendar days. No business calendar or weekday considers. You can't change the calculation frequency, either. However, this is possible in the future version.

Note

All the input vector must be 1 or the same length.

References

Modified Dietz Method: https://en.wikipedia.org/wiki/Modified_Dietz_method

Time weighed Return: https://en.wikipedia.org/wiki/Time-weighted_return

Examples

rtn <- make_rtn(date = c(210101, 210105, 210110), mv = c(100, 123, 140), pl = c(0, 3, 7))
rtn$twrr_cr(210102, 210110)
rtn$twrr_dr(210102, 210110)
rtn$dietz(210102, 210110)
rtn$dietz_avc(210102, 210110)