# Relative Volatility Index

`D07-F06-A04` · Technical Indicators → Range and Volatility Indicators · archetype `series-transform` · difficulty 2/5 · verification **verified**

Full page: https://docs.thefintechbuilder.com/technical-indicators/range-and-volatility-indicators/relative-volatility-index/
Agent skill: `npx skills add IslamBaraka90/Fintech-Algorithms-Library` — https://docs.thefintechbuilder.com/guides/agent-skill/

## Install and import

```bash
npm install fintech-algorithms
```

```ts
import { relativeVolatilityIndex } from "fintech-algorithms/technical-indicators/range-and-volatility-indicators/relative-volatility-index";
```

## Signature

```ts
relativeVolatilityIndex(input)
```

Relative Volatility Index: an RSI-shaped 0-100 oscillator that grades the rolling standard deviation of close recorded on up bars against the same measure recorded on down bars.

## Parameters

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `input` | `TopicInput` | yes | `bars` is the required OHLCV array -- each bar carries `timestamp`, `open`, `high`, `low`, `close`, `volume` and an optional `basis`, strictly ordered by timestamp. From `parameters` this topic reads only `period` (default 14, integer >= 2). It serves as both the standard-deviation window and the length of the two Wilder RMA smoothings applied to the up and down streams. |

## Returns

`TopicResult`

`series` holds a single key, `value`, bounded to 0-100; `latest.value` is its last reading. The warm-up is `2 * period - 2` leading nulls, so `ready_at` is 26 at the default period.

## Warm-up

The first ``2 * period - 2` bars (26 at the default period)` positions are `null`. The standard deviation seeds at index `period - 1`, and each RMA then needs `period` consecutive non-null inputs before it emits, pushing the first reading to `2 * period - 2`. `value` is also null on any bar where the up and down averages sum to zero.

## Errors

- When `parameters.period` is not an integer >= 2 — throws Error
- When a bar is missing open, high, low, close, or volume, or one of them is not a finite number — throws Error
- When bars are not strictly ordered by timestamp, or a bar's high is below its open, low, or close — throws Error

## Complexity

Time `O(n * period)`, space `O(n)`.

## Worked example

Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

### Input

`input`:

```json
{
  "bars": [
    {
      "timestamp": "2024-01-02",
      "basis": "synthetic-unadjusted",
      "open": 100,
      "high": 101.45,
      "low": 98.695,
      "close": 100,
      "volume": 750000,
      "benchmark": 200
    },
    {
      "timestamp": "2024-01-03",
      "basis": "synthetic-unadjusted",
      "open": 101.49111452,
      "high": 103.38381693,
      "low": 100.05480022,
      "close": 101.78791214,
      "volume": 795117,
      "benchmark": 200.56326135
    },
    {
      "timestamp": "2024-01-04",
      "basis": "synthetic-unadjusted",
      "open": 102.45519048,
      "high": 104.6701838,
      "low": 100.91147007,
      "close": 102.9549389,
      "volume": 840234,
      "benchmark": 201.11020913
    }
  ],
  "parameters": {}
}
```

### Call

```ts
relativeVolatilityIndex(input)
```

### Returns

object with 9 fields: topic_id, title, state, ready, ready_at, series, latest, parameters, …

```json
{
  "topic_id": "D07-F06-A04",
  "title": "Relative Volatility Index",
  "state": "calculated",
  "ready": true,
  "ready_at": 26,
  "series": {
    "value": [null, null, null, null, null, null]
  },
  "latest": {
    "value": 32.31900401565408
  },
  "parameters": {},
  "diagnostics": {
    "causal": true,
    "input_count": 96
  }
}
```

## Verification and provenance

Tier: **verified** (via E).

The worked example below is the figure published in this algorithm's article, replayed and asserted by the test suite on every build. The arithmetic cannot drift without the build failing.

Both tiers guarantee the signature. Full explanation: https://docs.thefintechbuilder.com/guides/verification/

Generated from the docs.json payload shipped inside fintech-algorithms@0.13.0.
The signature and parameter list are checked against the compiled implementation at build time,
so a description that contradicts the code fails the build rather than reaching this file.

## Links

- Article (how it works, step by step): https://thefintechbuilder.com/technical-indicators/range-and-volatility-indicators/relative-volatility-index/
- Implementation source: https://github.com/IslamBaraka90/Fintech-Algorithms-Library/blob/main/src/technical-indicators/range-and-volatility-indicators/relative-volatility-index/impl.ts
- Package on npm: https://www.npmjs.com/package/fintech-algorithms
- Domain index for agents: https://docs.thefintechbuilder.com/technical-indicators/llms.txt