Quick Start

This guide will help you get started with Rhoa in just a few minutes.

Overview

Rhoa provides pandas DataFrame extension accessors for:

• Technical indicators via .indicators accessor on pandas DataFrame and Series

• ML target generation via the generate_target_combinations() function

• Visualization via .plots accessor on pandas DataFrame

Installation

If you haven’t installed Rhoa yet:

pip install rhoa

Your First Indicators

Let’s calculate some basic technical indicators on stock price data.

Basic Example

import pandas as pd
import rhoa

# Load your price data (assuming you have a CSV with Close prices)
df = pd.read_csv('stock_prices.csv')

# Calculate Simple Moving Average
df['SMA_20'] = df.rhoa.indicators.sma(window_size=20)

# Calculate RSI (Relative Strength Index)
df['RSI_14'] = df.rhoa.indicators.rsi(window_size=14)

# Calculate Exponential Moving Average
df['EMA_12'] = df.rhoa.indicators.ewma(span=12)

print(df[['Close', 'SMA_20', 'RSI_14', 'EMA_12']].tail())

Working with OHLC Data

For indicators that require High, Low, and Close prices:

# Calculate Average True Range
df['ATR_14'] = df.rhoa.indicators.atr(window_size=14)

# Calculate Stochastic Oscillator
stoch = df.rhoa.indicators.stochastic(k_window=14, d_window=3)
df['Stoch_K'] = stoch['%K']
df['Stoch_D'] = stoch['%D']

Multiple Indicators at Once

# Calculate multiple indicators

# Build comprehensive technical analysis DataFrame
df['SMA_50'] = df.rhoa.indicators.sma(50)
df['SMA_200'] = df.rhoa.indicators.sma(200)
df['RSI'] = df.rhoa.indicators.rsi(14)
df['ATR'] = df.rhoa.indicators.atr(window_size=14)

macd = df.rhoa.indicators.macd()
df['MACD'] = macd['macd']
df['MACD_Signal'] = macd['signal']
df['MACD_Hist'] = macd['histogram']

bb = df.rhoa.indicators.bollinger_bands(window_size=20)
df['BB_Upper'] = bb['upper_band']
df['BB_Middle'] = bb['middle_band']
df['BB_Lower'] = bb['lower_band']

Generating ML Targets

Rhoa can automatically generate optimized binary targets for machine learning.

Auto Mode (Recommended)

Let Rhoa find the optimal lookback period and threshold:

from rhoa.targets import generate_target_combinations

# Generate targets with Pareto optimization
targets, metadata = generate_target_combinations(
    df,
    mode='auto',
    target_class_balance=0.5  # Aim for 50% positive class
)

# Inspect what was found optimal for each target
for method, params in metadata.items():
    print(f"{method}: period={params['period']}, "
          f"threshold={params['threshold']}%, "
          f"instances={params['instances']}")

This generates 8 different target types in the returned DataFrame:

• Target_1: Close[N]/Close[0]

• Target_2: Close[N]/High[0]

• Target_3: High[N]/Close[0]

• Target_4: High[N]/High[0]

• Target_5: MaxClose/Close[0]

• Target_6: MaxClose/High[0]

• Target_7: MaxHigh/Close[0]

• Target_8: MaxHigh/High[0]

Manual Mode

Specify a fixed lookback period and let Rhoa optimize thresholds:

# Generate targets with fixed 5-day lookback
targets, metadata = generate_target_combinations(
    df,
    mode='manual',
    lookback_periods=5
)

# All targets use 5-day period with optimized thresholds
print(targets.head())

Building an ML Pipeline

Here’s a complete example combining features and targets:

from rhoa.targets import generate_target_combinations
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import train_test_split
from sklearn.metrics import classification_report

# Step 1: Load data
df = pd.read_csv('stock_prices.csv')

# Step 2: Generate technical indicator features
df['SMA_20'] = df.rhoa.indicators.sma(20)
df['SMA_50'] = df.rhoa.indicators.sma(50)
df['RSI_14'] = df.rhoa.indicators.rsi(14)
df['ATR_14'] = df.rhoa.indicators.atr(window_size=14)
df['Returns'] = df['Close'].pct_change()

# Step 3: Generate optimized targets
targets, meta = generate_target_combinations(
    df,
    mode='auto',
    target_class_balance=0.3  # 30% positive instances
)

# Step 4: Prepare ML dataset
# Combine features and targets
ml_df = pd.concat([df, targets], axis=1).dropna()

# Select features and target
feature_cols = ['SMA_20', 'SMA_50', 'RSI_14', 'ATR_14', 'Returns']
X = ml_df[feature_cols]
y = ml_df['Target_7']  # Using MaxHigh/Close[0]

# Step 5: Train-test split
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42
)

# Step 6: Train model
model = RandomForestClassifier(n_estimators=100, random_state=42)
model.fit(X_train, y_train)

# Step 7: Evaluate
y_pred = model.predict(X_test)
print(classification_report(y_test, y_pred))
print(f"Accuracy: {model.score(X_test, y_test):.2%}")

Visualizing Predictions

Visualize your model’s predictions on a price chart:

# After training your model
predictions = model.predict(X_test)

# Create visualization with confusion matrix
fig = df.loc[X_test.index].rhoa.plots.signal(
    y_pred=predictions,
    y_true=y_test,
    date_col='Date',
    price_col='Close',
    title='Stock Predictions'
)

# Save to file
fig.savefig('predictions.png', dpi=300, bbox_inches='tight')

The visualization shows:

• Stock price line over time

• Light green dots: True opportunities (y_true=1)

• Bright green dots: Model predictions (y_pred=1)

• Red X markers: False positives

• Orange circles: False negatives (missed opportunities)

• Confusion matrix: Performance summary

Common Patterns

Find Overbought/Oversold Conditions

# Calculate RSI
rsi = df.rhoa.indicators.rsi(14)

# Find overbought (RSI > 70)
overbought = df[rsi > 70]
print(f"Overbought periods: {len(overbought)}")

# Find oversold (RSI < 30)
oversold = df[rsi < 30]
print(f"Oversold periods: {len(oversold)}")

Detect Moving Average Crossovers

# Calculate moving averages
sma_50 = df.rhoa.indicators.sma(50)
sma_200 = df.rhoa.indicators.sma(200)

# Detect golden cross (50 crosses above 200)
golden_cross = (sma_50 > sma_200) & (sma_50.shift(1) <= sma_200.shift(1))

# Detect death cross (50 crosses below 200)
death_cross = (sma_50 < sma_200) & (sma_50.shift(1) >= sma_200.shift(1))

print(f"Golden crosses: {golden_cross.sum()}")
print(f"Death crosses: {death_cross.sum()}")

Identify MACD Signals

# Calculate MACD
macd_data = df.rhoa.indicators.macd()
macd = macd_data['macd']
signal = macd_data['signal']

# Bullish crossover
bullish = (macd > signal) & (macd.shift(1) <= signal.shift(1))

# Bearish crossover
bearish = (macd < signal) & (macd.shift(1) >= signal.shift(1))

print(f"Bullish signals: {bullish.sum()}")
print(f"Bearish signals: {bearish.sum()}")

Check Bollinger Band Breakouts

# Calculate Bollinger Bands
bb = df.rhoa.indicators.bollinger_bands(window_size=20, num_std=2.0)

# Price touching upper band (potential reversal)
upper_touch = df['Close'] >= bb['upper_band']

# Price touching lower band (potential bounce)
lower_touch = df['Close'] <= bb['lower_band']

print(f"Upper band touches: {upper_touch.sum()}")
print(f"Lower band touches: {lower_touch.sum()}")

Next Steps

Now that you understand the basics, explore:

• User Guide - In-depth conceptual guides

• Examples - More practical examples

• API Reference - Complete API reference

• Frequently Asked Questions - Common questions and solutions

Tips for Success

1. Always import rhoa before using accessors

2. Handle NaN values - Indicators create NaN for initial periods

3. Choose appropriate window sizes - Longer = smoother but more lag

4. Test multiple targets - Different targets work for different strategies

5. Validate on out-of-sample data - Avoid overfitting

6. Document your metadata - Save target generation parameters for reproducibility

Need Help?

• Check the Frequently Asked Questions for common issues

• Read the User Guide for detailed explanations

• Browse Examples for more use cases

• Open an issue on GitHub