finlabR package

Description

Tools for portfolio construction and risk analytics, including mean-variance optimization, conditional value at risk (expected shortfall) minimization, risk parity, regime clustering, correlation analysis, Monte Carlo simulation, and option pricing. Includes utilities for portfolio evaluation, clustering, and risk reporting. Methods are based in part on Markowitz (1952) doi:10.1111/j.1540-6261.1952.tb01525.x, Rockafellar and Uryasev (2000) doi:10.21314/JOR.2000.038, Maillard et al. (2010) doi:10.3905/jpm.2010.36.4.060, Black and Scholes (1973) doi:10.1086/260062, and Cox et al. (1979) doi:10.1016/0304-405X(79)90015-1.

Author(s)

Maintainer: Suyash Jindal jindalsuyash7@gmail.com

American Option Pricing via Binomial Tree

Description

Extends the CRR binomial tree with early exercise at each node. Correctly prices American puts and calls.

Usage

american_option_binomial(
  S,
  K,
  time_to_expiry,
  r,
  sigma,
  n = 200,
  type = "put",
  q = 0
)

Arguments

Value

A list: price, early_exercise_boundary, european_price, early_premium.

Examples

# American put (early exercise premium should be positive for ITM put)
am <- american_option_binomial(S = 100, K = 105, time_to_expiry = 1,
                               r = 0.05, sigma = 0.25, n = 200,
                               type = "put")
cat("American put:", am$price, "  European put:", am$european_price,
    "  Early premium:", am$early_premium, "\n")

Annualise Returns

Description

Annualise Returns

Usage

annualize_returns(returns, freq = 252, type = "geometric")

Arguments

Value

Numeric. Annualised return.

Asset Clustering with Optional PCA Reduction

Description

Groups assets by similarity of their return distributions using k-means or Gaussian mixture EM, with an optional PCA dimensionality reduction step applied before clustering.

Usage

asset_clustering(
  returns,
  method = c("kmeans", "em"),
  k = 3,
  reduce = c("pca", "none"),
  n_components = 3,
  seed = 123
)

Arguments

Value

A list with elements clusters (named integer vector), model (fitted model object), and pca (the prcomp object, or NULL if reduce = "none").

Examples

set.seed(2)
R <- matrix(rnorm(300 * 6, 0.0003, 0.01), 300, 6)
colnames(R) <- paste0("A", 1:6)
res <- asset_clustering(R, method = "kmeans", k = 3)
res$clusters

Correlation Analysis Across Asset Groups

Description

Computes a Pearson, Spearman, or Kendall correlation matrix from either a single return matrix or a named list of return matrices (one per asset group). When a list is supplied, matrices are column-bound and column names are prefixed with the group index.

Usage

asset_correlation(returns_list, method = c("pearson", "spearman", "kendall"))

Arguments

Value

A symmetric numeric correlation matrix (N x N).

Examples

set.seed(1)
R <- matrix(rnorm(300 * 4, 0.0003, 0.01), 300, 4)
colnames(R) <- c("EQ1", "EQ2", "CMD1", "BOND1")
asset_correlation(R)

Compute Cross-Asset Correlation Matrix

Description

Computes the Pearson, Spearman, or Kendall correlation matrix across multiple asset classes (equities, commodities, crypto, bonds).

Usage

asset_correlation_matrix(
  returns,
  method = "pearson",
  use_ = "pairwise.complete.obs"
)

Arguments

Value

A list: cor_matrix, p_values, labels.

Examples

set.seed(42)
R <- matrix(rnorm(300 * 6, 0.0003, 0.01), 300, 6)
colnames(R) <- c("SPY","GLD","BTC","OIL","TLT","ETH")
res <- asset_correlation_matrix(R)
round(res$cor_matrix, 3)

Binomial Tree Option Pricing (European)

Description

Uses the Cox-Ross-Rubinstein (CRR) binomial model.

Usage

binomial_tree_option(S, K, time_to_expiry, r, sigma, n = 100, type = "call")

Arguments

Value

A list: price, u, d, p, tree (stock price tree), option_tree.

Examples

binomial_tree_option(S = 100, K = 100, time_to_expiry = 1,
                     r = 0.05, sigma = 0.20, n = 50)

Bootstrap Returns

Description

Generates a bootstrap distribution of portfolio statistics.

Usage

bootstrap_returns(
  returns,
  weights = NULL,
  stat_fn = NULL,
  n_boot = 1000,
  block_size = 1,
  freq = 252,
  seed = 42
)

Arguments

Value

A list: boot_stat, mean, se, ci_95.

Black-Scholes Option Price

Description

Black-Scholes Option Price

Usage

bs_option_price(S, K, time_to_expiry, r, sigma, type = "call", q = 0)

Arguments

Value

Numeric. Option price.

Examples

bs_option_price(100, 100, 1, 0.05, 0.20, "call")
bs_option_price(100, 105, 0.5, 0.04, 0.25, "put")

Compute Asset Returns from a Price Series

Description

Converts a matrix or data frame of asset prices into a matrix of period returns. The first row is dropped (no prior price to diff against), so the result has one fewer row than the input.

Usage

calc_returns(prices, method = c("log", "simple"), na.rm = TRUE)

Arguments

Value

A numeric matrix of returns with nrow(prices) - 1 rows and ncol(prices) columns. Column names are preserved.

Examples

prices <- get_example_prices()
rets   <- calc_returns(prices[, -1])
rets_s <- calc_returns(prices[, -1], method = "simple")
dim(rets)

CLT Demonstration

Description

Illustrates the Central Limit Theorem by drawing repeated samples of increasing size from a population and plotting the distribution of sample means against the theoretical Normal curve.

Usage

clt_demonstration(
  data,
  n_samples = c(5, 10, 30, 100),
  n_reps = 2000,
  seed = 123
)

Arguments

Value

A list with:

Examples

set.seed(1)
r <- rnorm(500, 0.0004, 0.012)
clt <- clt_demonstration(r)
clt$clt_plot

Evaluate Strategy PnL using CLT Confidence Intervals

Description

Applies the Central Limit Theorem to a vector of simulated daily profit-and-loss values and returns the sample mean together with a symmetric confidence interval.

Usage

clt_pnl_ci(pnl_vector, confidence_level = 0.95)

Arguments

Value

A list with three elements: mean_pnl, lower_ci, and upper_ci.

Examples

set.seed(10)
pnl <- rnorm(252, mean = 50, sd = 300)
clt_pnl_ci(pnl, confidence_level = 0.95)

CLT Sample Means

Description

Returns sample mean statistics for the CLT demonstration.

Usage

clt_sample_means(data, n, n_reps = 1000, seed = 42)

Arguments

Value

Numeric vector of sample means.

Cluster Order Book States using K-Means

Description

Identifies market regimes by running k-means clustering on the four microstructure features produced by extract_features(). Features are z-score scaled before clustering.

Usage

cluster_book_kmeans(features, centers = 4)

Arguments

Value

A list with two elements: model (the kmeans object) and data (the input data frame with a new regime column).

Examples

set.seed(7)
book <- extract_features(simulate_orderbook(500))
result <- cluster_book_kmeans(book, centers = 3)
table(result$data$regime)

Cluster Summary

Description

Cluster Summary

Usage

cluster_summary(cl_obj)

Arguments

Value

Data.frame of cluster statistics.

Compute the Efficient Frontier

Description

Solves a sequence of minimum-variance QP problems (via quadprog) across a grid of target returns to trace the efficient frontier. Returns and risk are annualised.

Usage

compute_efficient_frontier(
  returns,
  n_points = 100,
  allow_short = FALSE,
  risk_free = 0,
  freq = 252
)

Arguments

Value

A list with:

Examples

set.seed(42)
R <- matrix(rnorm(500 * 5, 0.0005, 0.01), 500, 5)
colnames(R) <- paste0("Asset", 1:5)
ef <- compute_efficient_frontier(R)
head(ef$frontier)

Consistency Check

Description

Tests whether an estimator is consistent: SE decreases as n grows.

Usage

consistency_check(estimates_by_n)

Arguments

Value

A data.frame with SE by n and consistency result.

Cross-Asset Correlation Analysis

Description

Comprehensive cross-asset study across equities, commodities, and crypto.

Usage

cross_asset_analysis(returns, asset_classes = NULL, window = 60, freq = 252)

Arguments

Value

A list: static_cor, rolling_cors, within_class, between_class, plots.

Time-Series Cross-Validation for Portfolio Models

Description

Implements rolling-window and expanding-window cross-validation for portfolio construction, measuring out-of-sample Sharpe and consistency / unbiasedness of estimates.

Usage

cross_validate_portfolio(
  returns,
  model_fn,
  n_folds = 5,
  window_type = "expanding",
  min_train = 60,
  eval_period = 21,
  freq = 252
)

Arguments

Value

A list: fold_results, oos_sharpe, consistency, unbiasedness.

Examples

set.seed(42)
R <- matrix(rnorm(500 * 4, 0.0003, 0.012), 500, 4)
colnames(R) <- paste0("A", 1:4)
cv <- cross_validate_portfolio(
  R,
  model_fn = function(r) min_variance_portfolio(r)$weights,
  n_folds  = 5
)
cat("OOS Sharpe:", cv$oos_sharpe, "\n")

CVaR-Return Frontier

Description

Sweeps over target returns to build a CVaR-efficient frontier.

Usage

cvar_frontier(returns, alpha = 0.95, n_points = 30, freq = 252)

Arguments

Value

A data.frame with columns: Return, Risk, CVaR, VaR, Sharpe, weights.

CVaR-Minimising Portfolio (Softmax / Lightweight)

Description

A simpler CVaR minimiser. For long-only portfolios the weights are parameterised through a softmax transformation so the simplex constraint is satisfied automatically (BFGS). For short-selling the weights are optimised directly with box constraints and a quadratic penalty for \sum w = 1 (L-BFGS-B).

Usage

cvar_minimize(
  returns,
  alpha = 0.95,
  allow_short = FALSE,
  bounds = c(-1, 1),
  penalty = 1000,
  max_iter = 500
)

Arguments

Value

A list with elements:

Examples

set.seed(7)
R <- matrix(rnorm(400 * 4, 0.0003, 0.01), 400, 4)
colnames(R) <- c("A", "B", "C", "D")
res <- cvar_minimize(R)
res$weights
res$cvar

Detect Regimes (General Interface)

Description

Detect Regimes (General Interface)

Usage

detect_regimes(returns, method = "kmeans", k = 3, ...)

Arguments

Value

Result list from the chosen method.

Download Prices via quantmod

Description

Wraps quantmod::getSymbols for clean price downloads.

Usage

download_prices(
  symbols,
  from = "2020-01-01",
  to = Sys.Date(),
  src = "yahoo",
  return_type = "returns"
)

Arguments

Value

An xts object.

Examples

prices <- download_prices(c("SPY","GLD","BTC-USD"), from="2021-01-01")

EM (Gaussian Mixture) Clustering

Description

Fits a Gaussian Mixture Model via Expectation-Maximisation using the mclust package. Automatically selects the number of components using BIC if k = NULL.

Usage

em_clustering(X, k = 3, scale_ = TRUE, max_k = 8)

Arguments

Value

A list: labels, probabilities, bic, means, covariances, model.

Examples

if (requireNamespace("mclust", quietly = TRUE)) {
  ok <- tryCatch({
    mclust::Mclust(matrix(rnorm(20), 10, 2), G = 2, verbose = FALSE)
    TRUE
  }, error = function(e) FALSE)
  if (ok) {
    set.seed(42)
    X <- rbind(matrix(rnorm(100*2, c(-2,0), 0.5), 100),
               matrix(rnorm(100*2, c( 2,0), 0.5), 100))
    res <- em_clustering(X, k = 2)
    table(res$labels)
  }
}

EM Algorithm (Gaussian Mixture) Regime Detection

Description

Uses Expectation-Maximisation to fit a Gaussian Mixture Model on rolling features. Requires the mclust package.

Usage

em_regime(returns, k = 3, window = 21, freq = 252)

Arguments

Value

A list: labels, probabilities, model, stats.

Examples

if (requireNamespace("mclust", quietly = TRUE)) {
  ok <- tryCatch({
    mclust::Mclust(matrix(rnorm(20), 10, 2), G = 2, verbose = FALSE)
    TRUE
  }, error = function(e) FALSE)
  if (ok) {
    set.seed(1)
    r <- c(rnorm(200, 0.001, 0.01), rnorm(150, -0.002, 0.02))
    res <- em_regime(r, k = 2)
  }
}

2D Embedding for Visualisation

Description

Projects a numeric matrix down to two dimensions using PCA, UMAP, or t-SNE for visual exploration of asset or regime clusters.

Usage

embedding_2d(X, method = c("pca", "umap", "tsne"), seed = 123)

Arguments

Value

A numeric matrix with two columns (N x 2).

Examples

set.seed(3)
X <- matrix(rnorm(100 * 5), 100, 5)
emb <- embedding_2d(X, method = "pca")
plot(emb, pch = 19, col = "steelblue")

Equal Risk Contribution (Risk Parity) Portfolio

Description

Solves the equal-risk-contribution problem using cyclical coordinate descent. Supports custom risk budgets. Each asset (by default) contributes equally to total portfolio risk.

Usage

equal_risk_contribution(
  returns,
  budget = NULL,
  freq = 252,
  tol = 1e-08,
  max_iter = 1000
)

Arguments

Value

A list with elements: weights, risk_contrib, risk, return, budget, iterations, method.

Examples

set.seed(42)
R <- matrix(rnorm(300 * 4, 0.0003, 0.01), 300, 4)
colnames(R) <- c("SPY", "GLD", "TLT", "VNQ")
rp <- equal_risk_contribution(R)
rp$weights

Example synthetic price dataset

Description

Example synthetic price dataset

Usage

example_prices

Format

A data frame with 1000 rows (dates) and 6 assets. Columns: date, EQ1, EQ2, EQ3, CMD1, CRYPTO1, BOND1

Extract Market Microstructure Features

Description

Appends derived microstructure columns — spread, order-flow imbalance, total depth, and a volatility proxy — to an order book snapshot data frame.

Usage

extract_features(book)

Arguments

Value

The input data.frame with four additional columns: spread, imbalance, depth_total, and volatility.

Examples

set.seed(1)
book <- simulate_orderbook(200)
book <- extract_features(book)
head(book[, c("spread", "imbalance", "volatility")])

Fetch Yahoo Finance close prices (wrapper around quantmod)

Description

Fetch Yahoo Finance close prices (wrapper around quantmod)

Usage

fetch_yahoo_prices(symbols, from, to)

Arguments

Value

xts object of close prices.

Format Portfolio Weights

Description

Prints a formatted weight table with percentages.

Usage

format_weights(weights, digits = 4)

Arguments

Value

Invisibly returns the formatted data.frame.

Gaussian Mixture Model via EM (Diagonal Covariance)

Description

Fits a Gaussian mixture model with diagonal covariance using the Expectation-Maximisation algorithm. Suitable for soft clustering of asset return features.

Usage

gaussian_mixture_em(X, k = 3, max_iter = 100, tol = 1e-06, seed = 123)

Arguments

Value

A list with elements weights, means, variances, loglik, and cluster (hard assignments via which.max).

Examples

set.seed(5)
X <- matrix(rnorm(200 * 3), 200, 3)
res <- gaussian_mixture_em(X, k = 2)
table(res$cluster)

Geometric Brownian Motion Simulation (Rich Output)

Description

Simulates stock price paths under GBM with a choice of exact log-normal or Euler-Maruyama discretisation. Returns paths as a paths x time matrix together with terminal-price summary statistics.

Usage

gbm_simulation(
  S0 = 100,
  mu = 0.08,
  sigma = 0.2,
  time_horizon = 1,
  n_steps = 252,
  n_paths = 1000,
  seed = NULL,
  method = "exact"
)

Arguments

Value

A list with:

Examples

sim <- gbm_simulation(S0 = 100, mu = 0.08, sigma = 0.20, n_paths = 500)
sim$stats$prob_profit

Gradient Descent Maximum Sharpe Portfolio

Description

Maximises the Sharpe ratio using Adam-style gradient descent on the negative Sharpe objective.

Usage

gd_max_sharpe(
  returns,
  risk_free = 0.02,
  lr = 0.001,
  max_iter = 3000,
  tol = 1e-08,
  freq = 252,
  beta1 = 0.9,
  beta2 = 0.999,
  eps_adam = 1e-08
)

Arguments

Value

A list: weights, loss_history, sharpe, risk, return.

Gradient Descent Minimum Variance Portfolio

Description

Minimises portfolio variance using projected gradient descent with simplex projection (long-only constraint).

Usage

gd_min_variance(
  returns,
  lr = 0.01,
  max_iter = 2000,
  tol = 1e-08,
  freq = 252,
  momentum = 0.9,
  verbose = FALSE
)

Arguments

Value

A list: weights, loss_history, convergence, risk, return.

Examples

set.seed(42)
R <- matrix(rnorm(300 * 5, 0.0003, 0.012), 300, 5)
colnames(R) <- paste0("A", 1:5)
gd <- gd_min_variance(R, lr = 0.05, max_iter = 1000)
gd$risk

Example Price Data

Description

Returns a data frame of simulated daily closing prices for six synthetic assets (three equities, one commodity, one crypto, one bond) covering approximately 1 000 trading days starting 2018-01-01.

Usage

get_example_prices()

Value

A data frame with columns date, EQ1, EQ2, EQ3, CMD1, CRYPTO1, and BOND1.

Examples

prices <- get_example_prices()
head(prices)

Compute Returns from Prices

Description

Compute Returns from Prices

Usage

get_returns(prices, type = "log", lag = 1)

Arguments

Value

Returns of the same type as input.

Examples

prices <- c(100, 102, 101, 105, 103)
get_returns(prices)
get_returns(prices, type = "simple")

Simple gradient descent optimizer

Description

Simple gradient descent optimizer

Usage

gradient_descent(f, grad = NULL, x0, lr = 0.01, max_iter = 1000, tol = 1e-06)

Arguments

Value

List with optimized parameters and history.

General Gradient Descent Portfolio (wrapper)

Description

General Gradient Descent Portfolio (wrapper)

Usage

gradient_descent_portfolio(returns, objective = "min_variance", ...)

Arguments

Value

List from the chosen optimisation.

K-Means Market Regime Detection

Description

Clusters market observations into regimes using k-means on engineered features: rolling return, rolling volatility, and rolling Sharpe ratio.

Usage

kmeans_regime(
  returns,
  k = 3,
  window = 21,
  n_starts = 50,
  seed = 42,
  freq = 252
)

Arguments

Value

A list: labels, centers, features, stats, dates (if xts).

Examples

set.seed(42)
r <- c(rnorm(200, 0.001, 0.01),   # bull
       rnorm(100, -0.002, 0.025),  # bear
       rnorm(150, 0.0005, 0.008))  # low-vol
res <- kmeans_regime(r, k = 3)
table(res$labels)

kNN Classifier for Financial Signals

Description

Trains a k-Nearest Neighbours classifier on financial features. Supports time-series aware train/test splitting.

Usage

knn_classify(X, y, k = 5, train_frac = 0.7, scale_ = TRUE, seed = 42)

Arguments

Value

A list: predictions, actual, accuracy, confusion_matrix, k.

Examples

set.seed(42)
X <- matrix(rnorm(500 * 5), 500, 5)
y <- factor(ifelse(rowSums(X[, 1:2]) > 0, "Up", "Down"))
res <- knn_classify(X, y, k = 7)
res$accuracy

kNN Money Flow Analysis

Description

Uses k-Nearest Neighbours to classify future market direction based on historical money-flow features (volume, price momentum, volatility). Provides a regime-based money flow signal.

Usage

knn_money_flow(
  returns,
  volume = NULL,
  k = 5,
  window = 10,
  horizon = 5,
  train_frac = 0.7,
  seed = 42
)

Arguments

Value

A list: predictions, accuracy, confusion_matrix, feature_importance.

Examples

set.seed(1)
r <- rnorm(500, 0.0003, 0.012)
res <- knn_money_flow(r, k = 7, horizon = 5)
cat("Accuracy:", res$accuracy, "\n")

k-Nearest Neighbors prediction

Description

k-Nearest Neighbors prediction

Usage

knn_predict(train_X, train_y, new_X, k = 5)

Arguments

Value

Predictions.

Market Regime Clustering with K-Means on Rolling Features

Description

Detects market regimes by computing rolling distributional features (mean, volatility, skewness, kurtosis) from a return series and applying k-means clustering to the resulting feature matrix.

Usage

market_regime_kmeans(
  returns,
  k = 3,
  window = 60,
  features = c("mean", "vol"),
  seed = 123
)

Arguments

Value

A list with elements features (feature matrix), kmeans (the fitted kmeans object), and labels (integer cluster assignments).

Examples

set.seed(1)
R <- matrix(rnorm(500 * 4, 0.0003, 0.01), 500, 4)
colnames(R) <- paste0("A", 1:4)
res <- market_regime_kmeans(R, k = 3, window = 60)
table(res$labels)

Maximum Sharpe Ratio Portfolio

Description

Finds the tangency portfolio by minimising negative Sharpe ratio via L-BFGS-B optimisation with box constraints.

Usage

max_sharpe_portfolio(
  returns,
  risk_free = 0.02,
  freq = 252,
  allow_short = FALSE
)

Arguments

Value

A list: weights, return, risk, sharpe, method.

Examples

set.seed(1)
R <- matrix(rnorm(252 * 4, 0.0003, 0.012), 252, 4)
colnames(R) <- c("SPY", "GLD", "BTC", "BND")
ms <- max_sharpe_portfolio(R, risk_free = 0.05)
ms$sharpe

Monte Carlo Price / Return Simulation

Description

Simulates portfolio or single-asset cumulative return paths from a historical return series. Computes the terminal return distribution, CLT convergence statistics, and k-fold forward-chain cross-validation estimates of annualised return.

Usage

mc_price_simulation(
  returns,
  n_paths = 5000,
  horizon = 252,
  freq = 252,
  seed = 42,
  use_hist = FALSE,
  n_cv_folds = 5
)

Arguments

Value

A list with elements: paths_matrix, terminal_returns, mu_historical, sg_historical, perc5, perc95, prob_profit, clt_stats (data.frame), cv_estimates (data.frame).

Examples

set.seed(1)
r <- rnorm(500, 0.0004, 0.012)
mc <- mc_price_simulation(r, n_paths = 1000, horizon = 252)
mc$prob_profit

Monte Carlo Return Distribution Table

Description

Extracts a percentile table of annualised terminal returns from the output of mc_price_simulation().

Usage

mc_return_distribution(mc_obj)

Arguments

Value

A data.frame with columns Percentile and AnnReturn.

Monte Carlo Statistics Summary

Description

Prints a formatted console report of key statistics from mc_price_simulation() output, including CLT convergence and cross-validation estimates.

Usage

mc_statistics(mc_obj)

Arguments

Value

Invisibly returns mc_obj.

Global Minimum Variance Portfolio

Description

Solves the unconstrained (or long-only) minimum-variance QP problem. Returns and risk are annualised.

Usage

min_variance_portfolio(returns, freq = 252, allow_short = FALSE)

Arguments

Value

A list: weights, return, risk, sharpe, method.

Examples

set.seed(7)
R <- matrix(rnorm(252 * 6, 0.0002, 0.01), 252, 6)
colnames(R) <- paste0("A", 1:6)
mv <- min_variance_portfolio(R)
mv$risk

Minimise Portfolio CVaR (Multi-Restart)

Description

Uses the Rockafellar-Uryasev linear programming reformulation of CVaR minimisation with multiple random restarts via stats::optim.

Usage

minimize_cvar(
  returns,
  alpha = 0.95,
  target_ret = NULL,
  allow_short = FALSE,
  freq = 252,
  n_restarts = 5
)

Arguments

Value

A list: weights, CVaR, VaR, return, risk.

Examples

set.seed(1)
R <- matrix(rnorm(300 * 5, 0.0004, 0.011), 300, 5)
colnames(R) <- paste0("Asset", 1:5)
result <- minimize_cvar(R, alpha = 0.95)
result$CVaR

Money Flow Index + kNN signal

Description

Money Flow Index + kNN signal

Usage

money_flow_knn(high, low, close, volume, k = 5, horizon = 1)

Arguments

Value

List with MFI series and kNN prediction.

Monte Carlo Option Pricing

Description

Prices European options via GBM simulation.

Usage

monte_carlo_option(
  S,
  K,
  time_to_expiry,
  r,
  sigma,
  n_sim = 1e+05,
  n_steps = 252,
  type = "call",
  seed = NULL
)

Arguments

Value

A list: price, std_error, conf_interval, paths (sample).

Efficient Frontier - Lightweight Scan (Raw Scale)

Description

Traces the efficient frontier by solving a target-return QP at each point. Works on raw (non-annualised) return scale. Prefer compute_efficient_frontier() for annualised, production-grade output.

Usage

mvo_efficient_frontier(
  returns,
  n = 50,
  rf = 0,
  allow_short = FALSE,
  target_returns = NULL
)

Arguments

Value

A list: frontier (data.frame), weights (list), mu, Sigma.

Examples

set.seed(5)
R <- matrix(rnorm(300 * 4, 0.0003, 0.01), 300, 4)
colnames(R) <- c("A", "B", "C", "D")
ef <- mvo_efficient_frontier(R, n = 30)
head(ef$frontier)

Maximum Sharpe Portfolio - Frontier Scan

Description

Identifies the max-Sharpe portfolio by scanning the efficient frontier computed via mvo_efficient_frontier(). A simpler alternative to max_sharpe_portfolio() when a frontier object is already available.

Usage

mvo_max_sharpe(returns, rf = 0, allow_short = FALSE, n = 50)

Arguments

Value

A list: weights, mean (raw-scale), vol (raw-scale), sharpe.

Examples

set.seed(9)
R <- matrix(rnorm(300 * 4, 0.0003, 0.01), 300, 4)
colnames(R) <- c("A", "B", "C", "D")
mvo_max_sharpe(R)

Minimum Variance Portfolio - Lightweight (Raw Scale)

Description

A simpler GMV solver that works on raw (non-annualised) return scale. Uses quadprog directly with a ridge-regularised covariance matrix. Prefer min_variance_portfolio() for annualised results.

Usage

mvo_min_variance(returns, allow_short = FALSE)

Arguments

Value

A list: weights, mean (raw-scale), vol (raw-scale).

Examples

set.seed(3)
R <- matrix(rnorm(300 * 4, 0.0003, 0.01), 300, 4)
colnames(R) <- c("A", "B", "C", "D")
mvo_min_variance(R)

MVO Summary

Description

Prints a formatted summary of the max-Sharpe and min-variance portfolios derived from an efficient frontier object.

Usage

mvo_summary(ef_obj, risk_free = 0.02)

Arguments

Value

Invisibly returns a list with max_sharpe and min_variance rows.

Optimize Quoting Parameters via Gradient Descent

Description

Learns optimal market-making quoting parameters by minimising the mean squared error between a linear spread model and a target spread vector. The model is: spread = a + b \cdot vol + c \cdot |inventory| + d \cdot imbalance.

Usage

optimize_quotes_gd(data, target_spread, learning_rate = 0.01, epochs = 1000)

Arguments

Value

A named numeric vector of four optimised parameters: a (intercept), b (volatility), c (inventory), d (imbalance).

Examples

set.seed(2)
book   <- extract_features(simulate_orderbook(300))
target <- book$spread + rnorm(300, 0, 0.001)
optimize_quotes_gd(book, target, learning_rate = 0.005, epochs = 500)

Option Greeks (Black-Scholes Analytical)

Description

Option Greeks (Black-Scholes Analytical)

Usage

option_greeks(S, K, time_to_expiry, r, sigma, type = "call", q = 0)

Arguments

Value

Named numeric vector: Delta, Gamma, Theta, Vega, Rho.

Examples

option_greeks(100, 100, 1, 0.05, 0.20, "call")

Option Price Simulation: CLT Demonstration (Large N)

Description

Simulates option prices over a large grid of (mean, sd) parameters and demonstrates the Central Limit Theorem convergence.

Usage

option_price_simulation(
  S = 100,
  K = 100,
  time_to_expiry = 1,
  r = 0.05,
  sigma_grid = c(0.1, 0.2, 0.3, 0.4),
  n_sim_vec = c(100, 500, 1000, 5000, 10000),
  type = "call",
  n_rep = 200,
  seed = 123
)

Arguments

Value

A list: results data.frame, clt_plot, convergence_plot.

Option Pricing Summary via Repeated Monte Carlo

Description

Runs price_option_mc() multiple times and summarises the distribution of price estimates across repetitions.

Usage

option_price_summary(n_reps = 30, ...)

Arguments

Value

A list with:

Examples

option_price_summary(n_reps = 20, S0 = 100, K = 100,
                     r = 0.05, sigma = 0.2, n_sims = 5000)

Performance summary using PerformanceAnalytics

Description

Performance summary using PerformanceAnalytics

Usage

performance_summary(returns)

Arguments

Value

PerformanceAnalytics table of annualized returns.

Plot Asset Clusters

Description

Plot Asset Clusters

Usage

plot_asset_clusters(cl_obj, type = "heatmap", title = "Asset Clustering")

Arguments

Value

A ggplot2 object or base R plot.

Plot Binomial Tree (Small Trees)

Description

Visualises the stock price nodes for a binomial tree. Only recommended for n <= 15.

Usage

plot_binomial_tree(bt_obj, show = "stock", title = "Binomial Tree")

Arguments

Value

A ggplot2 object.

Plot Correlation Heatmap

Description

Plot Correlation Heatmap

Usage

plot_correlation_heatmap(
  cor_obj,
  title = "Cross-Asset Correlation",
  show_values = TRUE,
  low_col = "#2166ac",
  high_col = "#d6604d"
)

Arguments

Value

A ggplot2 object.

Plot CVaR Frontier

Description

Plot CVaR Frontier

Usage

plot_cvar_frontier(cvar_obj, title = "CVaR-Efficient Frontier")

Arguments

Value

A ggplot2 object.

Plot the Efficient Frontier

Description

Visualises the efficient frontier with optional overlays for max-Sharpe and min-variance portfolios, and individual asset positions.

Usage

plot_efficient_frontier(
  ef_obj,
  highlight_portfolios = TRUE,
  risk_free = 0.02,
  show_assets = TRUE,
  title = "Efficient Frontier"
)

Arguments

Value

A ggplot2 object.

Plot 2D Embedding (t-SNE or UMAP)

Description

Plot 2D Embedding (t-SNE or UMAP)

Usage

plot_embedding(
  embed_obj,
  labels = NULL,
  title = "2D Embedding",
  method = "t-SNE"
)

Arguments

Value

A ggplot2 object.

Plot Gradient Descent Convergence

Description

Plot Gradient Descent Convergence

Usage

plot_gd_convergence(gd_obj, title = "Gradient Descent Convergence")

Arguments

Value

A ggplot2 object.

Plot Monte Carlo Paths

Description

Plots a random sample of simulated price or cumulative-return paths. Accepts output from either gbm_simulation() (App 2) or mc_price_simulation() (App 2), making it usable across both apps.

Usage

plot_mc_paths(mc_obj, n_show = 200, title = "Monte Carlo Price Paths")

Arguments

Value

A ggplot2 object.

Plot Monte Carlo Option Paths

Description

Plot Monte Carlo Option Paths

Usage

plot_option_simulation(mc_obj, n_paths = 100, title = "Monte Carlo GBM Paths")

Arguments

Value

A ggplot2 object.

Plot PCA Biplot

Description

Plot PCA Biplot

Usage

plot_pca_biplot(
  pca_obj,
  pc_x = 1,
  pc_y = 2,
  colour_by = NULL,
  title = "PCA Biplot"
)

Arguments

Value

A ggplot2 object.

Plot Market Regimes

Description

Plots a time series of returns coloured by detected regime.

Usage

plot_regimes(regime_obj, dates = NULL, title = "Market Regime Detection")

Arguments

Value

A ggplot2 object.

Plot Risk Contributions

Description

Visualises portfolio weights alongside risk contributions using a bar chart (side-by-side) or a pie chart.

Usage

plot_risk_contribution(
  rp_obj,
  type = c("bar", "pie"),
  title = "Risk Contribution"
)

Arguments

Value

A ggplot2 object.

Portfolio Asset Clustering (Extended)

Description

Clusters portfolio assets using k-means, hierarchical, or EM methods on correlation-transformed distance in PCA-reduced space. Returns rich statistics including per-cluster summary, correlation matrix, and dendrogram. For the general-purpose version see asset_clustering.

Usage

portfolio_asset_clustering(
  returns,
  k = 3,
  method = "kmeans",
  n_pca = 5,
  seed = 42,
  freq = 252
)

Arguments

Value

A list: labels, cluster_stats, dendrogram, centers, cor_matrix.

Examples

set.seed(42)
R <- matrix(rnorm(300 * 8, 0.0002, 0.01), 300, 8)
colnames(R) <- paste0("Asset", 1:8)
cl <- portfolio_asset_clustering(R, k = 3)
cl$cluster_stats

Portfolio Clustering (full pipeline)

Description

Runs the complete asset clustering pipeline including PCA reduction, k-means clustering, and regime assignment.

Usage

portfolio_clustering(returns, k = 3, freq = 252, plot_all = TRUE, seed = 42)

Arguments

Value

A comprehensive list with clustering, plots, and statistics.

Portfolio CVaR (Expected Shortfall)

Description

Computes the Conditional Value-at-Risk (CVaR / Expected Shortfall) for a given weight vector using historical simulation.

Usage

portfolio_cvar(
  returns,
  weights,
  alpha = 0.95,
  method = c("historical", "parametric", "monte_carlo"),
  n_sim = 10000
)

Arguments

Value

A named numeric vector: VaR, CVaR (both as positive loss figures).

Examples

set.seed(42)
R <- matrix(rnorm(500 * 4, 0.0003, 0.012), 500, 4)
w <- c(0.25, 0.25, 0.25, 0.25)
portfolio_cvar(R, w, alpha = 0.95)

Portfolio PCA Analysis

Description

Performs Principal Component Analysis on asset returns. Identifies dominant factors, factor loadings, and variance explained.

Usage

portfolio_pca(returns, scale_ = TRUE, n_comp = NULL, freq = 252)

Arguments

Value

A list: pca_obj, loadings, scores, var_explained, cumulative_var.

Examples

set.seed(42)
R <- matrix(rnorm(300 * 8, 0.0002, 0.01), 300, 8)
colnames(R) <- paste0("Asset", 1:8)
pca <- portfolio_pca(R)
pca$var_explained

Portfolio Performance Summary

Description

Computes key performance metrics for a portfolio.

Usage

portfolio_performance(returns, weights = NULL, risk_free = 0.02, freq = 252)

Arguments

Value

A named list of performance metrics.

Examples

set.seed(1)
r <- rnorm(252, 0.0004, 0.012)
portfolio_performance(r, risk_free = 0.02)

Portfolio t-SNE Embedding

Description

Reduces high-dimensional return data to 2D using t-SNE. Useful for visualising clusters in asset return space.

Usage

portfolio_tsne(
  returns,
  perplexity = 30,
  n_iter = 1000,
  dims = 2,
  scale_ = TRUE,
  seed = 42,
  use_pca_first = TRUE,
  pca_dims = 20
)

Arguments

Value

A list: embedding (T x dims), perplexity, note.

Examples

set.seed(42)
R <- matrix(rnorm(300 * 10, 0.0002, 0.01), 300, 10)
ts <- portfolio_tsne(R, perplexity = 30)
head(ts$embedding)

Portfolio UMAP Embedding

Description

Reduces returns matrix to 2D using UMAP.

Usage

portfolio_umap(
  returns,
  n_neighbors = 15,
  min_dist = 0.1,
  dims = 2,
  scale_ = TRUE,
  seed = 42
)

Arguments

Value

A list: embedding, config.

Predict Regime using kNN

Description

Classifies a new order book snapshot into one of the regimes learned by cluster_book_kmeans() using k-nearest-neighbour classification.

Usage

predict_regime_knn(train_data, new_snapshot, k = 5)

Arguments

Value

A factor of length 1 with the predicted regime label.

Examples

set.seed(3)
book  <- extract_features(simulate_orderbook(500))
res   <- cluster_book_kmeans(book, centers = 3)
pred  <- predict_regime_knn(res$data, res$data[1, ], k = 5)

Binomial Tree Option Pricing (European / American)

Description

Prices European or American options using the Cox-Ross-Rubinstein (CRR) binomial tree model.

Usage

price_option_binomial(
  S0,
  K,
  r,
  sigma,
  time_to_maturity = 1,
  n_steps = 100,
  type = c("call", "put"),
  american = FALSE
)

Arguments

Value

Scalar option price.

Examples

price_option_binomial(S0 = 100, K = 100, r = 0.05, sigma = 0.2)
price_option_binomial(S0 = 100, K = 100, r = 0.05, sigma = 0.2,
                      american = TRUE, type = "put")

Monte Carlo European Option Pricing

Description

Prices a European call or put option using Monte Carlo simulation under risk-neutral GBM dynamics.

Usage

price_option_mc(
  S0,
  K,
  r,
  sigma,
  time_to_maturity = 1,
  n_sims = 10000,
  type = c("call", "put"),
  seed = NULL
)

Arguments

Value

A list with elements:

Examples

price_option_mc(S0 = 100, K = 100, r = 0.05, sigma = 0.2, seed = 1)

Regime Statistics

Description

Computes per-regime return, volatility, Sharpe, and duration statistics.

Usage

regime_statistics(regime_obj)

Arguments

Value

A data.frame with per-regime statistics.

Compute Risk Contributions

Description

Computes the marginal and percentage risk contribution of each asset to total portfolio volatility.

Usage

risk_contribution(weights, cov_matrix)

Arguments

Value

A data.frame with columns: Asset, Weight, MargRC, RiskContrib, PercRC.

Examples

Sig <- matrix(c(0.04, 0.02, 0.02, 0.09), 2, 2)
risk_contribution(c(0.5, 0.5), Sig)

Risk Parity Portfolio (Convenience Wrapper)

Description

Alias for equal_risk_contribution() with named budget support. Use this when you want to specify a custom (possibly named) risk budget.

Usage

risk_parity_portfolio(returns, budget = NULL, freq = 252, ...)

Arguments

Value

Same list as equal_risk_contribution().

Examples

set.seed(1)
R <- matrix(rnorm(300 * 3, 0.0003, 0.01), 300, 3)
colnames(R) <- c("Equity", "Bond", "Gold")
rp <- risk_parity_portfolio(R, budget = c(0.5, 0.3, 0.2))
rp$weights

Risk Parity Weights — Fast Iterative Solver

Description

Computes equal-risk-contribution weights directly from a covariance matrix using a simple iterative proportional scaling algorithm. This is a lightweight alternative to equal_risk_contribution() when only a covariance matrix is available (no return series needed).

Usage

risk_parity_weights(covmat, max_iter = 1000, tol = 1e-08)

Arguments

Value

A list with elements:

Examples

Sig <- matrix(c(0.04, 0.02, 0.02, 0.09), 2, 2)
colnames(Sig) <- rownames(Sig) <- c("A", "B")
risk_parity_weights(Sig)

Rolling Correlation

Description

Computes rolling pairwise correlations between two assets over time.

Usage

rolling_correlation(r1, r2, window = 60, method = "pearson")

Arguments

Value

A numeric vector of rolling correlations.

Rolling cross-validation for return forecasts

Description

Rolling cross-validation for return forecasts

Usage

rolling_cv_forecast(
  returns,
  window = 252,
  horizon = 21,
  step = 21,
  estimator = c("mean", "median")
)

Arguments

Value

Data frame with fold metrics.

Launch the QuantPortR Interactive Dashboard

Description

Launch the QuantPortR Interactive Dashboard

Usage

run_quantportr_app(host = "127.0.0.1", port = 3838, launch.browser = TRUE)

Arguments

Value

No return value. Called for the side effect of launching a Shiny application. Internally this starts a Shiny app object and blocks the current R session until the app is stopped.

Sampling Distribution Demonstration

Description

Demonstrates properties of sampling distributions (mean, variance) through simulation, verifying theoretical results.

Usage

sampling_distribution(
  pop,
  stat = "mean",
  n_samples = c(10, 30, 50, 100, 200),
  n_reps = 2000,
  seed = 42
)

Arguments

Value

A list: results, plots, theoretical_vs_empirical.

Scree Plot

Description

Scree Plot

Usage

scree_plot(pca_obj, title = "Scree Plot (PCA Variance Explained)")

Arguments

Value

A ggplot2 object.

Simulate GBM Price Paths

Description

Simulates stock price paths under Geometric Brownian Motion using the exact log-normal increments. Returns a matrix with rows as time steps and columns as simulations (compatible with App 1 option pricing workflow).

Usage

simulate_gbm_paths(
  S0,
  mu,
  sigma,
  time_horizon = 1,
  n_steps = 252,
  n_sims = 1000,
  seed = NULL
)

Arguments

Value

Numeric matrix of simulated prices (n_steps+1 rows x n_sims cols).

Examples

paths <- simulate_gbm_paths(S0 = 100, mu = 0.08, sigma = 0.2, seed = 42)
dim(paths)   # 253 x 1000

Simulate a Basic Order Book

Description

Generates synthetic limit order book (LOB) snapshots over time by combining a random-walk mid-price with Poisson-distributed depth and a stochastic bid-ask spread.

Usage

simulate_orderbook(n_steps = 1000, p0 = 100)

Arguments

Value

A data.frame with columns time, mid_price, bid, ask, bid_depth, and ask_depth.

Examples

set.seed(42)
book <- simulate_orderbook(n_steps = 500, p0 = 100)
head(book)

Unbiasedness Check

Description

Tests whether a list of estimates is unbiased w.r.t. a true value.

Usage

unbiasedness_check(estimates, true_val, tol = 0.05)

Arguments

Value

A list: bias, rel_bias, is_unbiased.

VaR and CVaR analysis

Description

VaR and CVaR analysis

Usage

var_cvar(
  returns,
  alpha = 0.95,
  method = c("historical", "gaussian"),
  portfolio_weights = NULL
)

Arguments

Value

Data frame with VaR and CVaR.

Full VaR / CVaR Portfolio Analysis

Description

Computes VaR and CVaR using three methods and returns a comprehensive report.

Usage

var_cvar_analysis(
  returns,
  weights,
  alphas = c(0.9, 0.95, 0.99),
  n_sim = 50000,
  freq = 252
)

Arguments

Value

A list with tables and ggplot objects.