pandastock 0.0.4

Pandas extension for financial data processing and visualization

Pandastock

A simple pandas extension for financial data processing and visualization. Pandastock makes it easy to plot candlestick charts from pandas DataFrames and overlay technical indicators.

Features

• 📊 Candlestick Charting: Beautiful candlestick charts with volume bars
• 📈 Technical Indicators: Built-in support for popular indicators
• 🎨 Flexible Plotting: Indicators can be plotted over or under the main chart
• 🔄 Streaming Support: Real-time indicator calculation with next_value()
• 📁 Easy Data Loading: Convenient functions to load candle data from CSV files
• 🐼 Pandas Integration: Seamless pandas DataFrame accessor

Installation

pip install pandastock

Or install from source:

git clone https://github.com/alexeyshesh/pandastock.git
cd pandastock
pip install -e .

Requirements

• Python >= 3.11
• pandas
• matplotlib

Quick Start

Basic Usage

import pandas as pd
from pandastock.candles import read_candles_from_csv
from pandastock.indicators import RSI, SMA, MACD

# Load candlestick data from CSV
# CSV must have columns: timestamp, open, high, low, close, volume
df = read_candles_from_csv('data.csv')

# Add indicators
df.candles.add_indicators(
    rsi_14=RSI(period=14),
    sma_20=SMA(window=20),
    macd=MACD()
)

# Plot the chart
df.candles.plot('2025-01-13 20:10:00', window=30)

Data Loading

Pandastock provides several convenient functions to load candlestick data:

Load from Single CSV File

from pandastock.candles import read_candles_from_csv

# Load data from a single CSV file
df = read_candles_from_csv('data.csv')

# Optional: Aggregate data to different timeframes
df_hourly = read_candles_from_csv('data.csv', agg='1H')
df_daily = read_candles_from_csv('data.csv', agg='1D')

# Optional: Remove weekend data
df = read_candles_from_csv('data.csv', remove_weekend=True)

Load from Multiple CSV Files

from pandastock.candles import read_candles_from_csv_list

# Load and combine multiple CSV files
df = read_candles_from_csv_list([
    'data_2025-01-01.csv',
    'data_2025-01-02.csv',
    'data_2025-01-03.csv'
])

Load from Directory Range

from pandastock.candles import read_candles_csv_range

# Load all CSV files in a directory within a date range
df = read_candles_csv_range(
    dir='data/YDEX',
    from_='2025-01-01',
    to_='2025-01-31',
    agg='1H'
)

Available Indicators

RSI (Relative Strength Index)

Measures the speed and change of price movements.

from pandastock.indicators import RSI

# Create RSI indicator with default period (14)
rsi = RSI()

# Custom period
rsi_20 = RSI(period=20)

# Add to dataframe
df.candles.add_indicators(rsi=rsi)

Parameters:

• period (int): RSI period, default 14
• col (str): Column to calculate RSI on, default 'close'

SMA (Simple Moving Average)

Calculates the average price over a specified period.

from pandastock.indicators import SMA

# Create SMA with default window (15)
sma = SMA()

# Custom window
sma_50 = SMA(window=50)

# Add to dataframe
df.candles.add_indicators(sma_20=SMA(window=20), sma_50=SMA(window=50))

Parameters:

• window (int): Moving average window size, default 15
• col (str): Column to calculate SMA on, default 'close'

LSMA (Least Squares Moving Average)

Linear regression-based moving average that fits a line to the data.

from pandastock.indicators import LSMA

# Create LSMA with default window (15)
lsma = LSMA()

# Custom window
lsma_30 = LSMA(window=30)

# Add to dataframe
df.candles.add_indicators(lsma=lsma)

Parameters:

• window (int): Moving average window size, default 15
• col (str): Column to calculate LSMA on, default 'close'

MACD (Moving Average Convergence Divergence)

Trend-following momentum indicator that shows the relationship between two moving averages.

from pandastock.indicators import MACD

# Create MACD with default parameters (12, 26, 9)
macd = MACD()

# Custom parameters
macd_custom = MACD(fast=10, slow=20, signal=8)

# Add to dataframe
df.candles.add_indicators(macd=macd)

Parameters:

• fast (int): Fast EMA period, default 12
• slow (int): Slow EMA period, default 26
• signal (int): Signal line period, default 9
• col (str): Column to calculate MACD on, default 'close'

Stochastic RSI

Combines Stochastic Oscillator and RSI to generate more reliable signals.

from pandastock.indicators import StochasticRSI

# Create Stochastic RSI with default parameters (14, 3, 3)
stoch_rsi = StochasticRSI()

# Custom parameters
stoch_rsi_custom = StochasticRSI(period=14, k=3, d=3)

# Add to dataframe
df.candles.add_indicators(stoch_rsi=stoch_rsi)

Parameters:

• period (int): RSI period, default 14
• k (int): %K smoothing period, default 3
• d (int): %D smoothing period, default 3
• col (str): Column to calculate Stochastic RSI on, default 'close'

Plotting

Basic Plot

# Plot centered on a specific timestamp
df.candles.plot('2025-01-13 20:10:00')

Custom Window Size

# Plot with custom window size (number of candles on each side)
df.candles.plot('2025-01-13 20:10:00', window=50)

Date Range

# Plot specific date range
df.candles.plot(
    center_time='2025-01-13 20:10:00',
    from_='2025-01-01',
    to_='2025-01-31'
)

Custom Figure Size

# Plot with custom figure size
df.candles.plot('2025-01-13 20:10:00', figsize=(16, 12))

Complete Example

Here's a complete example showing how to use pandastock:

import pandas as pd
from pandastock.candles import read_candles_csv_range
from pandastock.indicators import RSI, SMA, MACD, StochasticRSI, LSMA

# Load data from multiple CSV files in a directory
df = read_candles_csv_range(
    dir='data/YDEX',
    from_='2025-01-01',
    to_='2025-01-31',
    agg='1H'
)

# Add multiple indicators
df.candles.add_indicators(
    # Overlaid indicators (plotted on the same chart as candles)
    sma_20=SMA(window=20),
    sma_50=SMA(window=50),
    lsma_30=LSMA(window=30),

    # Under indicators (plotted in separate subplots)
    rsi_14=RSI(period=14),
    macd=MACD(fast=12, slow=26, signal=9),
    stoch_rsi=StochasticRSI(period=14, k=3, d=3)
)

# Plot the chart
df.candles.plot(
    center_time='2025-01-15 10:00:00',
    window=40,
    figsize=(14, 10)
)

# Access indicator values
print(df[['close', 'sma_20__sma', 'sma_50__sma', 'rsi_14__rsi']].tail())

Indicator Plot Positions

Indicators can be plotted in two positions:

• Over (PlotPosition.over): Plotted on the same chart as candlesticks (e.g., SMA, LSMA)
• Under (PlotPosition.under): Plotted in separate subplots below the main chart (e.g., RSI, MACD, StochasticRSI)

Streaming Support

All indicators support streaming data processing with the next_value() method:

from pandastock.indicators import RSI

# Create indicator
rsi = RSI(period=14)

# Process candles one by one (streaming)
for _, candle in df.iterrows():
    result = rsi.next_value(candle)
    print(f"RSI: {result['rsi']}")

Data Format

Your CSV files should have the following columns:

• timestamp: Date and time of the candle
• open: Opening price
• high: Highest price
• low: Lowest price
• close: Closing price
• volume: Trading volume

Example CSV format:

timestamp,open,high,low,close,volume
2025-01-01 00:00:00,100.0,105.0,99.0,104.0,1000
2025-01-01 01:00:00,104.0,108.0,103.0,107.0,1200
2025-01-01 02:00:00,107.0,110.0,106.0,109.0,900

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Alexey Sheshukov - [e-mail]

Links

• GitHub Repository
• Homepage