openseries (TypeScript)

Tools for analyzing financial timeseries of a single asset or a group of assets. Designed for daily or less frequent data. TypeScript port of the Python openseries package.

Quick Start

import { OpenTimeSeries } from "openseries-ts";

const dates = ["2020-01-02", "2020-01-03", "2020-01-06", "2020-01-07"];
const values = [100, 101, 102, 99];

const series = OpenTimeSeries.fromArrays("My Series", dates, values);

console.log(series.geoRet());    // CAGR
console.log(series.vol());      // Annualized volatility
console.log(series.maxDrawdown()); // Max drawdown

Features

• OpenTimeSeries: Single timeseries with risk metrics (CAGR, volatility, VaR, CVaR, Sortino ratio, max drawdown, etc.)
• OpenFrame: Multi-series comparison, correlation, portfolio construction, rebalancing
• ReturnSimulation: Monte Carlo with reproducible seeds (normal, lognormal, GBM, Merton jump-diffusion)
• Portfolio tools: Efficient frontier, simulated portfolios, weight strategies
• Date utilities: Business day calendars (via date-holidays), date offsets, period-end alignment
• Captor API: Fetch timeseries from Captor Open API (fetchCaptorSeries, fetchCaptorSeriesBatch)
• Report: reportHtml(frame, options) — programmatic HTML report; CLI via npm run report
• Plot: plotSeriesHtml(), plotSeries() — full-page series line chart (like Python plot_series)

API Overview

OpenTimeSeries

• fromArrays(), fromObject(), fromDateColumns() — create from dates/values or simulation output
• valueToRet(), toCumret() - Convert price ↔ returns
• geoRet(), arithmeticRet(), vol(), varDown(), cvarDown()
• sortinoRatio(), retVolRatio(), maxDrawdown(), maxDrawdownBottomDate(), downsideDeviation()
• ewmaVolFunc(), ewmaVarFunc() - EWMA risk measures

OpenFrame

• mergeSeries(), truncFrame() - Align multiple series
• toDrawdownSeries() - Convert aligned columns to drawdown (value/peak - 1)
• makePortfolio() - Weighted portfolio (eq_weights, inv_vol, max_div, min_vol_overweight)
• correlMatrix(), trackingError(), infoRatio(), beta(), jensenAlpha()
• maxDrawdown(), maxDrawdownBottomDate() - Per-column drawdown metrics
• captureRatio(ratio, baseColumn?, opts?) - CAGR-based capture vs benchmark (opts.freq optional; when omitted, uses frame data as-is)
• ordLeastSquaresFit(), filterToBusinessDays(), resampleToPeriodEnd()

ReturnSimulation

• fromNormal(), fromLognormal(), fromGbm(), fromMertonJumpGbm() — all accept optional seed for reproducibility
• toDateColumns(name, options?) — returns dates and columns (as returns or cumulative prices)
• randomGenerator(seed?) — seeded RNG for custom use

Captor API

• fetchCaptorSeries(id) — fetch a single series from Captor Open API
• fetchCaptorSeriesBatch(ids) — fetch multiple series

Report

• reportHtml(frame, options?) — generate HTML report (cumulative performance, annual returns, stats) from an OpenFrame. Options: title, logoUrl, addLogo. Countries for business-day metrics come from frame.countries.

Plot

• plotSeriesHtml(seriesOrFrame, options?) — generate full-page HTML with a line chart of cumulative returns (base 1). Works with OpenTimeSeries or OpenFrame (use mergeSeries("inner") first). Options: title, logoUrl, addLogo, asDrawdown (plot drawdown series).
• plotSeries(seriesOrFrame, options?) — async: writes HTML to file and optionally opens in browser. Options: title, logoUrl, addLogo, filename (default: ~/Documents/plot.html), autoOpen (default: true).

Documentation

API reference: https://captorab.github.io/openseries-ts/

To regenerate docs locally:

npm run docs

This writes static HTML to docs/. To serve them via GitHub Pages:

1. Run npm run docs and commit the docs/ folder
2. In the repo: Settings → Pages
3. Under Source, choose Deploy from a branch
4. Branch: main (or your default branch), folder: /docs

Docs will be available at https://<username>.github.io/<repo>/.

Scripts

Build & Development

Command	Description
npm run build	Build dist/ (ESM + CJS + declarations)
npm run test	Run Vitest test suite
npm run test:coverage	Run tests with Istanbul coverage report
npm run lint	Run ESLint on src/
npm run lint:fix	ESLint with auto-fix
npm run typecheck	TypeScript check (tsc --noEmit)
npm run check	Run lint + typecheck
npm run docs	Generate API docs to docs/ (TypeDoc)
npm publish	publish to npm

Report Script

Generates an HTML portfolio report from Captor API timeseries (cumulative performance, annual returns, statistics).

Command	Description
npm run report	Report with custom or default Captor series IDs
npm run report:iris	Preset: Captor Iris Bond + Benchmark Index
npm run report:captor	Same as report (default Captor IDs)

Default output (in ~/Documents): iris_report.html (Iris preset), captor_report.html (default Captor preset), or report.html (custom --ids).

Options (pass after --): --ids id1 id2 ..., --iris, --title "Title", --countries "SE,US", --from-date YYYY-MM-DD, --to-date YYYY-MM-DD, --filename path, --no-open, --no-logo.

Examples:

npm run report -- --ids 638f681e 5b72a10c 5c1115fb
npm run report:iris -- --from-date 2023-01-01 --to-date 2024-12-31 --no-open

Plot Script

Generates a full-page HTML line chart of cumulative returns (base 1) from Captor API timeseries. With the default Captor preset (no --ids), an equal-weight portfolio series is included.

Command	Description
npm run plot	Plot with custom or default Captor series IDs
npm run plot:iris	Preset: Captor Iris Bond + Benchmark Index
npm run plot:captor	Same as plot
npm run plot:drawdown	DEFAULT_SERIES as drawdown series

Default output (in ~/Documents): iris_plot.html (Iris preset), captor_plot.html (default Captor preset), drawdown_plot.html (drawdown preset), or plot.html (custom --ids).

Options (pass after --): same as Report (--ids, --iris, --drawdown, --title, --countries, --from-date, --to-date, --filename, --no-open, --no-logo).

Examples:

npm run plot:iris
npm run plot -- --ids id1 id2 --no-open --filename my-plot.html

Efficient Frontier Script

Simulates asset returns (lognormal), builds portfolio frame, computes efficient frontier and max-Sharpe portfolio, and plots simulated portfolios, frontier, and labeled points (assets, current, optimum). Mirrors the Python openseries Jupyter notebook workflow.

Command	Description
npm run efficient-frontier	Run efficient frontier demo

Options (pass after --): --simulations N (default: 5000), --points N (default: 30), --seed N (default: 71), --countries "SE", --title "Title", --filename path, --no-open, --no-logo.

Example:

npm run efficient-frontier -- --simulations 3000 --points 25 --no-open

Compare Metrics Script

Compares TypeScript openseries-ts metrics against Python openseries metrics. Loads timeseries data from iris.json, computes metrics with the TS implementation, and displays them side-by-side with Python metrics from data.json.

Prerequisites: Run the Python script first to create the reference data in ~/Documents/:

python scripts/load_py_openseries_data.py

This fetches the Captor Iris Bond timeseries from the API, saves it to ~/Documents/iris.json, and exports Python-calculated metrics to ~/Documents/data.json.

Command	Description
npm run compare-metrics	Compare TS vs Python metrics (default: 4 decimal places)

Options: --decimals=N (pass after --).

Examples:

npm run compare-metrics
npm run compare-metrics -- --decimals=6