@captorab/openseries-ts - v1.0.0
    Preparing search index...

    @captorab/openseries-ts - v1.0.0

    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.

    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
    • 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)
    • 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
    • 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()
    • 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
    • fetchCaptorSeries(id) — fetch a single series from Captor Open API
    • fetchCaptorSeriesBatch(ids) — fetch multiple series
    • 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.
    • 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).

    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>/.

    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)

    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

    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

    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

    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

    Settings

    Member Visibility

    On This Page

    openseries (TypeScript)