### End-to-End WaveTrend 3D Workflow

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

A comprehensive example showing the full pipeline: fetching market data via CCXT, processing it with Polars, computing WaveTrend 3D indicators, and analyzing trading signals.

```python
import ccxt
import polars as pl
from src.wavetrend_3d.wavetrend_3d import WaveTrend3D

exchange = ccxt.binance()
ohlcv = exchange.fetch_ohlcv('BTC/USDT', '1h', limit=500)

df = pl.DataFrame(ohlcv, schema=['timestamp', 'open', 'high', 'low', 'close', 'volume'], orient='row').with_columns(pl.from_epoch('timestamp', time_unit='ms').alias('datetime'))

wt3d = WaveTrend3D(df['close'])
wt3d.compute_series(oscillator_lookback=20, quadratic_mean_length=50, f_length=0.75, n_length=1.00, s_length=1.75)
wt3d.compute_signals(lookback_bound=40, proportional_decrease_bound=0.4)

import numpy as np
print(f"Total bars: {len(df)}")
print(f"Bullish fast-norm crosses: {np.sum(wt3d.fast_norm_cross_bullish)}")
print(f"Bearish fast-norm crosses: {np.sum(wt3d.fast_norm_cross_bearish)}")
```

--------------------------------

### Initialize and Compute WaveTrend3D Oscillator and Signals (Python)

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

Demonstrates initializing the WaveTrend3D class with price data (NumPy array or Polars Series) and computing the three oscillator series (fast, normal, slow) along with trading signals like crossovers and divergences. It shows how to access the computed series and signals, and provides parameters for customization.

```python
import numpy as np
import polars as pl
from src.wavetrend_3d.wavetrend_3d import WaveTrend3D

# Load sample price data (close prices)
df = pl.read_parquet('tests/data/sample_btc_data.parquet')
close_prices = df['close']

# Initialize WaveTrend3D with price data (accepts np.ndarray or pl.Series)
wt3d = WaveTrend3D(close_prices)

# Compute the three oscillator series with default parameters
wt3d.compute_series(
    oscillator_lookback=20,      # Bars for signal smoothing
    quadratic_mean_length=50,    # Window for RMS normalization
    f_length=0.75,               # Fast oscillator scale factor
    n_length=1.00,               # Normal oscillator scale factor
    s_length=1.75,               # Slow oscillator scale factor
    f_smoothing=0.45,            # Fast frequency smoothing
    n_smoothing=1.00,            # Normal frequency smoothing
    s_smoothing=2.50             # Slow frequency smoothing
)

# Compute trading signals (crossovers and divergences)
wt3d.compute_signals(
    lookback_bound=40,                  # Max bars between divergence crosses
    proportional_decrease_bound=0.4     # Proportional size threshold for divergence
)

# Access computed oscillator series (np.ndarray, values between -1.75 and 1.75)
print(f"Fast series shape: {wt3d.series_fast.shape}")
print(f"Normal series shape: {wt3d.series_norm.shape}")
print(f"Slow series shape: {wt3d.series_slow.shape}")

# Access trading signals (boolean np.ndarray)
print(f"Bullish crossovers: {np.sum(wt3d.fast_norm_cross_bullish)}")
print(f"Bearish crossovers: {np.sum(wt3d.fast_norm_cross_bearish)}")

# Access divergence indices (np.ndarray of index positions)
print(f"Bullish divergences at indices: {wt3d.divergence_bullish}")
print(f"Bearish divergences at indices: {wt3d.divergence_bearish}")

# Alternative: get series as tuple
fast, norm, slow = wt3d.get_series()
```

--------------------------------

### Signal Splitting with Custom Thresholds

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

Demonstrates how to split a signal series into positive and negative components based on a custom threshold value instead of the default zero line.

```python
pos_custom, neg_custom = split_signal(signal, fill=None, threshold=0.5)
print(f"Positive (>0.5): {pos_custom}")
print(f"Negative (<=0.5): {neg_custom}")
```

--------------------------------

### Crossover Detection Utilities

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

Provides functions for identifying bullish and bearish crossover events between two series or a series and a static threshold. These utilities are essential for generating trading signals from oscillator data.

```python
import numpy as np
from common.signal_tools import cross_over, cross_down, cross

fast_signal = np.array([0.0, -0.2, -0.1, 0.1, 0.3, 0.2, 0.0, -0.1, -0.3, -0.2])
slow_signal = np.array([0.0, -0.1, -0.1, 0.0, 0.1, 0.15, 0.1, 0.0, -0.1, -0.15])

bullish_crosses = cross_over(fast_signal, slow_signal)
print(f"Bullish crossovers at indices: {np.where(bullish_crosses)[0]}")

bearish_crosses = cross_down(fast_signal, slow_signal)
print(f"Bearish crossovers at indices: {np.where(bearish_crosses)[0]}")

zero_crosses_up = cross_over(fast_signal, 0)
zero_crosses_down = cross_down(fast_signal, 0)
print(f"Zero line cross up: {np.where(zero_crosses_up)[0]}")
print(f"Zero line cross down: {np.where(zero_crosses_down)[0]}")

any_cross = cross(fast_signal, slow_signal)
print(f"Any crossing events: {np.where(any_cross)[0]}")
```

--------------------------------

### Generate Bounded Oscillator Signal (Python)

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

This function, `get_oscillator`, generates a bounded oscillator signal from raw price data. It utilizes normalization and dual-pole filtering, transforming price data into WaveTrend oscillator values that are approximately bounded between -1 and 1 due to a tanh activation function.

```python
import numpy as np
from src.wavetrend_3d.signal_processing import get_oscillator

# Sample price data (e.g., close prices)
prices = np.array([100, 102, 101, 103, 105, 104, 106, 108, 107, 109,
                   111, 110, 108, 106, 104, 102, 100, 98, 96, 94,
                   92, 90, 91, 93, 95, 97, 99, 101, 103, 105])

# Generate oscillator signal
oscillator = get_oscillator(
    src=prices,
    smoothing_frequency=9.0,      # Controls smoothing level (higher = smoother)
    quadratic_mean_length=50     # Window for RMS normalization
)

# Output is bounded approximately between -1 and 1 due to tanh transformation
print(f"Oscillator shape: {oscillator.shape}")
print(f"Oscillator values (last 10): {oscillator[-10:]}")
print(f"Min value: {np.nanmin(oscillator):.4f}")
print(f"Max value: {np.nanmax(oscillator):.4f}")
```

--------------------------------

### Create and Display Interactive 3D WaveTrend Plot

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

Generates an interactive 3D plot of market data with the WaveTrend 3D indicator. This involves initializing the plot, adding candlestick data for a specified market and interval, and overlaying the WaveTrend 3D indicator with options for main and mirror views. The plot is then displayed.

```python
plot = PlotWaveTrend3D([0.7, 0.2, 0.1], height=900)
plot.add_candles(df, market='BTC-USDT', interval='1h')
plot.add_wavetrend(wt3d, main=True, mirror=True)
plot.show()
```

--------------------------------

### WaveTrend 3D Computation

Source: https://github.com/artnaz/wavetrend-3d/blob/master/README.md

Demonstrates how to initialize and compute the WaveTrend 3D indicator using a Polars DataFrame.

```APIDOC
## WaveTrend 3D Computation

### Description
This section shows how to compute the WaveTrend 3D indicator. It requires a Polars DataFrame with typical OHLC data and accepts only a Polars Series or NumPy array for the 'close' price.

### Method
```python
from wavetrend_3d.wavetrend_3d import WaveTrend3D

df = ... # Polars DataFrame with typical Open, High, Low, Close data

wt3d = WaveTrend3D(df['close'])
wt3d.compute_series()
wt3d.compute_signals()
```

### Parameters
- `df` (Polars DataFrame): Input DataFrame containing OHLC data.
- `df['close']` (Polars Series or NumPy array): The closing prices used for computation.

### Notes
Refer to the docstrings of the `compute_series()` method for details on customizable settings.
```

--------------------------------

### WaveTrend-3D Computation API

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

End-to-end workflow for computing WaveTrend-3D oscillators and generating trading signals from market data.

```APIDOC
## POST /compute_wavetrend

### Description
Computes WaveTrend-3D oscillator series and identifies bullish/bearish signals based on market data.

### Request Body
- **data** (array) - Required - List of closing prices.
- **oscillator_lookback** (int) - Required - Lookback period for oscillator.
- **f_length** (float) - Required - Fast timeframe multiplier.
- **n_length** (float) - Required - Normal timeframe multiplier.
- **s_length** (float) - Required - Slow timeframe multiplier.

### Response
#### Success Response (200)
- **fast_norm_cross_bullish** (array) - Boolean array of bullish events.
- **fast_norm_cross_bearish** (array) - Boolean array of bearish events.
- **divergence_bullish** (list) - List of detected bullish divergences.
- **divergence_bearish** (list) - List of detected bearish divergences.
```

--------------------------------

### Compute WaveTrend 3D Signals

Source: https://github.com/artnaz/wavetrend-3d/blob/master/README.md

Initializes the WaveTrend3D class with a price series and computes the indicator series and signals. It expects a Polars Series or NumPy array as input.

```python
from wavetrend_3d.wavetrend_3d import WaveTrend3D

df = ... # Polars DataFrame with typical Open, High, Low, Close data

wt3d = WaveTrend3D(df['close'])
wt3d.compute_series()
wt3d.compute_signals()
```

--------------------------------

### Signal Detection Utilities

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

Functions for identifying crossover events between series or against a threshold, useful for generating trading signals.

```APIDOC
## SIGNAL DETECTION UTILITIES

### Description
Provides functions to detect when a signal crosses above or below another signal or a fixed threshold.

### Methods
- `cross_over(series1, series2)`: Returns boolean array where series1 crosses above series2.
- `cross_down(series1, series2)`: Returns boolean array where series1 crosses below series2.
- `cross(series1, series2)`: Returns boolean array where any crossing occurs.

### Parameters
#### Arguments
- **series1** (array) - Required - The primary signal series.
- **series2** (array/float) - Required - The comparison series or threshold value.

### Response
- **result** (boolean array) - An array of the same length as the input series indicating event occurrences.
```

--------------------------------

### Visualize WaveTrend 3D with Plotly

Source: https://github.com/artnaz/wavetrend-3d/blob/master/README.md

Configures and renders a candlestick chart combined with the WaveTrend 3D indicator using Plotly. Supports optional mirrored oscillator views and custom height proportions.

```python
from wavetrend_3d.plotting import PlotWaveTrend3D

plot_mirror = True

if plot_mirror:
  plot = PlotWaveTrend3D([.7, .2, .1], height=800)
else:
  plot = PlotWaveTrend3D([.8, .2], height=800)

plot.add_candles(df, 'BTC-USDT', '1h')
plot.add_wavetrend(wt3d, main=True, mirror=plot_mirror)
plot.show()
```

--------------------------------

### Color Conversion Utility

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

Converts hexadecimal color codes to RGBA format with support for opacity and RGB value offsets.

```APIDOC
## hex_to_rgba

### Description
Converts a hex color string into an RGBA representation, allowing for transparency and color adjustment.

### Parameters
- **hex_code** (string) - Required - The hex color (e.g., '#009988').
- **opacity** (float) - Optional - Alpha channel value (0.0 to 1.0).
- **offset** (int) - Optional - Integer to add/subtract from RGB channels.
- **return_type** (string) - Optional - 'string' (default) or 'tuple'.

### Response
- **rgba** (string/tuple) - The formatted RGBA color.
```

--------------------------------

### WaveTrend 3D Plotting

Source: https://github.com/artnaz/wavetrend-3d/blob/master/README.md

Illustrates how to plot the WaveTrend 3D indicator and candlestick chart using Plotly.

```APIDOC
## Plotting WaveTrend 3D

### Description
This section details how to plot the WaveTrend 3D indicator along with a candlestick chart using the Plotly library. It allows for customization of plot layout, including mirrored oscillators.

### Method
```python
from wavetrend_3d.plotting import PlotWaveTrend3D

plot_mirror = True  # Set to True to add a mirrored version of the oscillator

if plot_mirror:
  # Set height proportions for price, regular oscillator, and mirrored oscillator
  plot = PlotWaveTrend3D([.7, .2, .1], height=800)
else:
  # Set proportions for price and regular oscillator
  plot = PlotWaveTrend3D([.8, .2], height=800)

plot.add_candles(df, 'BTC-USDT', '1h')
plot.add_wavetrend(wt3d, main=True, mirror=plot_mirror)
plot.show()
```

### Parameters
- `df` (Polars DataFrame): DataFrame containing OHLC data.
- `symbol` (str): The trading symbol (e.g., 'BTC-USDT').
- `interval` (str): The chart interval (e.g., '1h').
- `plot_mirror` (bool): If True, adds a mirrored oscillator plot.
- `height` (int): The height of the Plotly figure.
- `proportions` (list): A list of floats defining the height proportions for the price and oscillator plots.

### Notes
The generated plot uses the default white theme. The `add_wavetrend` method can include a mirrored version if `plot_mirror` is set to True.
```

--------------------------------

### PlotWaveTrend3D Class for Financial Chart Visualization

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

Visualizes candlestick charts with the WaveTrend 3D oscillator using Plotly. This class supports both a main oscillator view and a mirrored three-dimensional visualization. It requires OHLCV data and computes the WaveTrend 3D series and signals before plotting.

```python
import polars as pl
from src.wavetrend_3d.wavetrend_3d import WaveTrend3D
from src.wavetrend_3d.plotting import PlotWaveTrend3D

# Load OHLCV data with required columns: datetime, open, high, low, close
df = pl.read_parquet('tests/data/sample_btc_data.parquet')

# Compute WaveTrend3D oscillator
wt3d = WaveTrend3D(df['close'])
wt3d.compute_series()
wt3d.compute_signals()

# Option 1: Plot with main oscillator only
plot = PlotWaveTrend3D(
    subplot_proportions=[0.8, 0.2],  # 80% price chart, 20% oscillator
    height=800
)
plot.add_candles(df, market='BTC-USDT', interval='1h')
plot.add_wavetrend(wt3d, main=True, mirror=False)
plot.show()

# Option 2: Plot with main oscillator and mirrored 3D view
plot_mirror = PlotWaveTrend3D(
    subplot_proportions=[0.7, 0.2, 0.1],  # Price, oscillator, mirror
    height=800
)
plot_mirror.add_candles(df, market='BTC-USDT', interval='1h')
plot_mirror.add_wavetrend(wt3d, main=True, mirror=True)
plot_mirror.show()
```

--------------------------------

### Split Oscillator Signal for Plotly Visualization

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

Splits an oscillator signal into positive and negative components, facilitating visualization with Plotly's fill effects. It supports different fill modes: 'None' (NaN fill), 'bfill' (backward fill for continuous lines), and 'zero' (zero fill for clean area charts). This is crucial for rendering oscillators correctly.

```python
import numpy as np
from src.wavetrend_3d.plotting import split_signal

# Sample oscillator signal crossing zero multiple times
signal = np.array([-1, 1, 2, 1, -1, -2, 1, 0.5, -0.5, 0])

# Mode 1: Simple split with NaN for opposite values
pos_nan, neg_nan = split_signal(signal, fill=None)
print(f"Positive (NaN fill): {pos_nan}")  # [nan  1.  2.  1. nan nan  1. 0.5 nan nan]
print(f"Negative (NaN fill): {neg_nan}")  # [-1. nan nan nan -1. -2. nan nan -0.5  0.]

# Mode 2: Backward fill for continuous lines at crossings
pos_bfill, neg_bfill = split_signal(signal, fill='bfill')
print(f"Positive (bfill): {pos_bfill}")   # Fills transition points
print(f"Negative (bfill): {neg_bfill}")

# Mode 3: Zero fill for clean area charts
pos_zero, neg_zero = split_signal(signal, fill='zero')
print(f"Positive (zero): {pos_zero}")     # Surrounds with zeros
print(f"Negative (zero): {neg_zero}")
```

--------------------------------

### PlotWaveTrend3D Class

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

A comprehensive plotting class for visualizing candlestick charts alongside the WaveTrend 3D oscillator using Plotly. Supports both the main oscillator view and the mirrored three-dimensional visualization.

```APIDOC
## PlotWaveTrend3D Class

### Description
A comprehensive plotting class for visualizing candlestick charts alongside the WaveTrend 3D oscillator using Plotly. Supports both the main oscillator view and the mirrored three-dimensional visualization.

### Methods
- **__init__(self, subplot_proportions=[0.7, 0.3], height=600, **kwargs)**: Initializes the PlotWaveTrend3D class with specified subplot proportions and figure height.
- **add_candles(self, df, market, interval, **kwargs)**: Adds candlestick data to the plot.
- **add_wavetrend(self, wt3d, main=True, mirror=False, **kwargs)**: Adds the WaveTrend 3D oscillator to the plot, with options for main view and mirrored 3D view.
- **show(self)**: Displays the generated Plotly figure.

### Parameters
#### `__init__` Parameters
- **subplot_proportions** (list[float]) - Optional - Proportions of the subplots (e.g., `[0.8, 0.2]` for price and oscillator).
- **height** (int) - Optional - The height of the Plotly figure in pixels.

#### `add_candles` Parameters
- **df** (polars.DataFrame) - Required - DataFrame containing OHLCV data with columns: `datetime`, `open`, `high`, `low`, `close`.
- **market** (str) - Required - Market identifier (e.g., 'BTC-USDT').
- **interval** (str) - Required - Candlestick interval (e.g., '1h').

#### `add_wavetrend` Parameters
- **wt3d** (WaveTrend3D) - Required - An instance of the WaveTrend3D class containing computed oscillator data.
- **main** (bool) - Optional - Whether to display the main oscillator view (default: True).
- **mirror** (bool) - Optional - Whether to display the mirrored 3D visualization (default: False).

### Request Example
```python
import polars as pl
from src.wavetrend_3d.wavetrend_3d import WaveTrend3D
from src.wavetrend_3d.plotting import PlotWaveTrend3D

# Load OHLCV data with required columns: datetime, open, high, low, close
df = pl.read_parquet('tests/data/sample_btc_data.parquet')

# Compute WaveTrend3D oscillator
wt3d = WaveTrend3D(df['close'])
wt3d.compute_series()
wt3d.compute_signals()

# Option 1: Plot with main oscillator only
plot = PlotWaveTrend3D(
    subplot_proportions=[0.8, 0.2],  # 80% price chart, 20% oscillator
    height=800
)
plot.add_candles(df, market='BTC-USDT', interval='1h')
plot.add_wavetrend(wt3d, main=True, mirror=False)
plot.show()

# Option 2: Plot with main oscillator and mirrored 3D view
plot_mirror = PlotWaveTrend3D(
    subplot_proportions=[0.7, 0.2, 0.1],  # Price, oscillator, mirror
    height=800
)
plot_mirror.add_candles(df, market='BTC-USDT', interval='1h')
plot_mirror.add_wavetrend(wt3d, main=True, mirror=True)
plot_mirror.show()
```

### Response
#### Success Response (200)
- **Plotly Figure** - The generated Plotly figure object is displayed.

#### Response Example
(Displays interactive Plotly charts based on the provided data and configuration.)
```

--------------------------------

### Normalize Data Series Derivative (Python)

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

The `normalize_derivative` function preprocesses data by normalizing its discrete second derivative using the quadratic mean (RMS). This standardization is a crucial step before applying the tanh activation function in the WaveTrend oscillator calculation.

```python
import numpy as np
from src.wavetrend_3d.signal_processing import normalize_derivative

# Sample price data
prices = np.array([100, 102, 104, 103, 105, 108, 107, 110, 112, 115,
                   118, 120, 119, 117, 115, 113, 110, 108, 105, 103])

# Compute normalized derivative
normalized = normalize_derivative(
    data=prices,
    quadratic_mean_length=10  # Window for RMS calculation
)

```

--------------------------------

### split_signal Function

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

Utility function that splits an oscillator signal into positive and negative arrays for proper visualization with Plotly fills. Supports multiple fill modes for continuous line rendering.

```APIDOC
## split_signal Function

### Description
Utility function that splits an oscillator signal into positive and negative arrays for proper visualization with Plotly fills. Supports multiple fill modes for continuous line rendering.

### Method
`split_signal`

### Parameters
#### Arguments
- **signal** (numpy.ndarray) - Required - The input oscillator signal.
- **fill** (str | None) - Optional - The fill mode. Can be 'bfill' (backward fill), 'zero' (fill with zeros), or None (fill with NaN). Defaults to None.

### Request Example
```python
import numpy as np
from src.wavetrend_3d.plotting import split_signal

# Sample oscillator signal crossing zero multiple times
signal = np.array([-1, 1, 2, 1, -1, -2, 1, 0.5, -0.5, 0])

# Mode 1: Simple split with NaN for opposite values
pos_nan, neg_nan = split_signal(signal, fill=None)
print(f"Positive (NaN fill): {pos_nan}")  # [nan  1.  2.  1. nan nan  1. 0.5 nan nan]
print(f"Negative (NaN fill): {neg_nan}")  # [-1. nan nan nan -1. -2. nan nan -0.5  0.]

# Mode 2: Backward fill for continuous lines at crossings
pos_bfill, neg_bfill = split_signal(signal, fill='bfill')
print(f"Positive (bfill): {pos_bfill}")   # Fills transition points
print(f"Negative (bfill): {neg_bfill}")

# Mode 3: Zero fill for clean area charts
pos_zero, neg_zero = split_signal(signal, fill='zero')
print(f"Positive (zero): {pos_zero}")     # Surrounds with zeros
print(f"Negative (zero): {neg_zero}")
```

### Response
#### Success Response (200)
- **positive_signal** (numpy.ndarray) - Array containing only the positive values of the signal, with fill applied.
- **negative_signal** (numpy.ndarray) - Array containing only the negative values of the signal, with fill applied.

#### Response Example
```
Positive (NaN fill): [       nan 1.         2.         1.                nan        nan
 1.         0.5             nan        nan]
Negative (NaN fill): [-1.             nan        nan        nan -1.        -2.
        nan        nan -0.5         0.     ]
Positive (bfill): [ 1.  1.  2.  1.  1. -1.  1.  0.5  0.5  0. ]
Negative (bfill): [-1. -1. -1. -1. -1. -2. -2. -0.5 -0.5  0. ]
Positive (zero): [0. 1. 2. 1. 0. 0. 1. 0.5 0. 0.]
Negative (zero): [-1. 0. 0. 0. -1. -2. 0. 0. -0.5 0.]
```
```

--------------------------------

### Apply Dual-Pole Filter for Signal Smoothing

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

Applies a dual-pole low-pass Butterworth filter to smooth a given signal. This IIR filter is effective in reducing high-frequency noise while preserving underlying trends with minimal lag. It takes the data array and a lookback parameter to control the smoothing intensity.

```python
import numpy as np
from src.wavetrend_3d.signal_processing import apply_dual_pole_filter

# Sample signal (e.g., tanh-normalized derivative)
signal = np.array([0.0, 0.1, 0.3, 0.5, 0.4, 0.2, -0.1, -0.3, -0.5, -0.4,
                   -0.2, 0.0, 0.2, 0.4, 0.6, 0.5, 0.3, 0.1, -0.1, -0.3])

# Apply dual-pole filter for smoothing
filtered = apply_dual_pole_filter(
    data=signal,
    lookback=9.0  # Higher values = more smoothing
)

# Compare original vs filtered
print(f"Original signal: {signal[:10]}")
print(f"Filtered signal: {filtered[:10]}")
print(f"Smoothing reduces noise while preserving trend direction")
```

--------------------------------

### Hex to RGBA Color Conversion

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

Utility function to convert hexadecimal color codes into RGBA strings or tuples. Supports opacity adjustment and RGB value offsets for creating transparent or lightened/darkened plot colors.

```python
from common.utilities import hex_to_rgba

green = hex_to_rgba('#009988', opacity=1.0)
print(f"Green RGBA: {green}")

green_transparent = hex_to_rgba('#009988', opacity=0.3)
print(f"Transparent green: {green_transparent}")

green_light = hex_to_rgba('#009988', opacity=1.0, offset=50)
print(f"Lightened green: {green_light}")

green_dark = hex_to_rgba('#009988', opacity=1.0, offset=-50)
print(f"Darkened green: {green_dark}")

rgba_tuple = hex_to_rgba('#CC3311', opacity=0.8, return_type='tuple')
print(f"RGBA tuple: {rgba_tuple}")
```

--------------------------------

### apply_dual_pole_filter Function

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

Applies a dual-pole low-pass Butterworth filter to reduce high-frequency noise while highlighting underlying trends. This IIR filter provides smooth signals with minimal lag compared to traditional moving averages.

```APIDOC
## apply_dual_pole_filter Function

### Description
Applies a dual-pole low-pass Butterworth filter to reduce high-frequency noise while highlighting underlying trends. This IIR filter provides smooth signals with minimal lag compared to traditional moving averages.

### Method
`apply_dual_pole_filter`

### Parameters
#### Arguments
- **data** (numpy.ndarray) - Required - The input signal data to be filtered.
- **lookback** (float) - Required - The lookback period for the filter, influencing the degree of smoothing. Higher values result in more smoothing.

### Request Example
```python
import numpy as np
from src.wavetrend_3d.signal_processing import apply_dual_pole_filter

# Sample signal (e.g., tanh-normalized derivative)
signal = np.array([0.0, 0.1, 0.3, 0.5, 0.4, 0.2, -0.1, -0.3, -0.5, -0.4,
                   -0.2, 0.0, 0.2, 0.4, 0.6, 0.5, 0.3, 0.1, -0.1, -0.3])

# Apply dual-pole filter for smoothing
filtered = apply_dual_pole_filter(
    data=signal,
    lookback=9.0  # Higher values = more smoothing
)

# Compare original vs filtered
print(f"Original signal: {signal[:10]}")
print(f"Filtered signal: {filtered[:10]}")
print(f"Smoothing reduces noise while preserving trend direction")
```

### Response
#### Success Response (200)
- **filtered_signal** (numpy.ndarray) - The smoothed signal after applying the dual-pole filter.

#### Response Example
```
Original signal: [ 0.   0.1  0.3  0.5  0.4  0.2 -0.1 -0.3 -0.5 -0.4]
Filtered signal: [ 0.00161978  0.0134689   0.04182715  0.09017937  0.15343766  0.2258701
  0.30053368  0.3711161   0.4317998   0.4801463 ]
Smoothing reduces noise while preserving trend direction
```
```

--------------------------------

### add_oscillator Function

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

Adds an oscillator subplot to a Plotly figure with positive/negative value coloring and fill effects. Used internally by PlotWaveTrend3D but can be used directly for custom visualizations.

```APIDOC
## add_oscillator Function

### Description
Adds an oscillator subplot to a Plotly figure with positive/negative value coloring and fill effects. Used internally by PlotWaveTrend3D but can be used directly for custom visualizations.

### Method
`add_oscillator`

### Parameters
#### Arguments
- **fig** (plotly.graph_objects.Figure) - Required - The Plotly figure to which the oscillator will be added.
- **datetime** (numpy.ndarray) - Required - Array of datetime objects for the x-axis.
- **signal** (numpy.ndarray) - Required - The oscillator signal data.
- **name** (str) - Required - The name of the oscillator trace.
- **row** (int) - Required - The row number where the oscillator subplot will be placed.
- **col** (int) - Required - The column number where the oscillator subplot will be placed.
- **line_opacity** (float) - Optional - Opacity of the oscillator line (default: 1.0).
- **fill_opacity** (float) - Optional - Opacity of the fill area below the line (default: 0.2).
- **line_width** (int) - Optional - Thickness of the oscillator line (default: 1).
- **colour_pos** (str) - Optional - Color for positive signal values (default: '#009988').
- **colour_neg** (str) - Optional - Color for negative signal values (default: '#CC3311').
- **mirror** (bool) - Optional - If True, the oscillator is mirrored (default: False).
- **show_legend** (bool) - Optional - Whether to show the legend for this trace (default: True).

### Request Example
```python
import numpy as np
import polars as pl
import plotly.graph_objects as go
from plotly.subplots import make_subplots
from src.wavetrend_3d.plotting import add_oscillator

# Create sample oscillator data
datetime = pl.date_range(pl.date(2024, 1, 1), pl.date(2024, 1, 30), eager=True)
signal = np.sin(np.linspace(0, 4 * np.pi, len(datetime)))  # Sample oscillator

# Create subplot figure
fig = make_subplots(rows=2, cols=1, row_heights=[0.7, 0.3], shared_xaxes=True)

# Add dummy price chart to row 1
fig.add_scatter(x=datetime, y=100 + 10 * signal, name='Price', row=1, col=1)

# Add oscillator to row 2 with custom styling
fig = add_oscillator(
    fig=fig,
    datetime=datetime.to_numpy(),
    signal=signal,
    name='Custom Oscillator',
    row=2,
    line_opacity=0.8,           # Line transparency
    fill_opacity=0.2,           # Fill transparency
    line_width=1.5,             # Line thickness
    colour_pos='#009988',       # Color for positive values (green)
    colour_neg='#CC3311',       # Color for negative values (red)
    mirror=False,               # Set True for mirrored display
    show_legend=True
)

fig.update_layout(height=600, title='Custom Oscillator Plot')
fig.show()
```

### Response
#### Success Response (200)
- **fig** (plotly.graph_objects.Figure) - The updated Plotly figure object with the added oscillator subplot.

#### Response Example
(Displays an interactive Plotly figure with a price chart and a custom-styled oscillator subplot.)
```

--------------------------------

### Add Oscillator Subplot to Plotly Figure

Source: https://context7.com/artnaz/wavetrend-3d/llms.txt

Adds an oscillator subplot to an existing Plotly figure, enabling custom styling with positive/negative value coloring and fill effects. This function is useful for creating custom visualizations of oscillator data, supporting various styling options like line opacity, fill opacity, and colors.

```python
import numpy as np
import polars as pl
import plotly.graph_objects as go
from plotly.subplots import make_subplots
from src.wavetrend_3d.plotting import add_oscillator

# Create sample oscillator data
datetime = pl.date_range(pl.date(2024, 1, 1), pl.date(2024, 1, 30), eager=True)
signal = np.sin(np.linspace(0, 4 * np.pi, len(datetime)))  # Sample oscillator

# Create subplot figure
fig = make_subplots(rows=2, cols=1, row_heights=[0.7, 0.3], shared_xaxes=True)

# Add dummy price chart to row 1
fig.add_scatter(x=datetime, y=100 + 10 * signal, name='Price', row=1, col=1)

# Add oscillator to row 2 with custom styling
fig = add_oscillator(
    fig=fig,
    datetime=datetime.to_numpy(),
    signal=signal,
    name='Custom Oscillator',
    row=2,
    line_opacity=0.8,           # Line transparency
    fill_opacity=0.2,           # Fill transparency
    line_width=1.5,             # Line thickness
    colour_pos='#009988',       # Color for positive values (green)
    colour_neg='#CC3311',       # Color for negative values (red)
    mirror=False,               # Set True for mirrored display
    show_legend=True
)

fig.update_layout(height=600, title='Custom Oscillator Plot')
fig.show()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.