ClawFoxyVision

ClawFoxyVision: Your Sharper View into Financial Fortunes.

Clawy and Foxy, our visionary duo, power this library to help you navigate the complexities of financial time series data. Clawy's razor-sharp analytical abilities dissect intricate market patterns, while Foxy's cunning intelligence detects subtle movements often missed by others.

ClawFoxyVision empowers traders and analysts with enhanced foresight into market trends. By transforming raw data into actionable insights, our advanced vision algorithms cut through market noise, revealing the true signals that can inform tomorrow's movements. Trust ClawFoxyVision to illuminate your path through the often murky waters of financial forecasting.

Built with Burn, a deep learning framework in Rust.

Features

• Advanced Recurrent Neural Networks: Implements LSTM and GRU models tailored for time series forecasting.
• Flexible Configuration:
  • Configurable sequence length and forecast horizon.
  • Bidirectional processing capabilities.
  • Integrated attention mechanisms.
  • Adjustable hyperparameters.
  • L2 regularization and dropout for robust training.
• Streamlined Data Handling:
  • Built-in data normalization and preprocessing.
  • Supports OHLC (Open, High, Low, Close) data from CSV files.
• Persistent Models: Save trained models and load them for later use.
• Comparative Analysis: Directly compare prediction performance between LSTM and GRU models for the same ticker.

Getting Started

Prerequisites

• Rust 1.65 or higher installed on your system.
• Your stock data should be in CSV files, with columns for Open, High, Low, and Close values. For example: AAPL-ticker_minute_bars.csv.

Installation

1. Clone the repository: bash git clone <repository-url> # Replace <repository-url> with the actual URL cd ClawFoxyVision
2. The project uses Cargo, Rust's package manager. Dependencies will be handled automatically.

Running the Models

You can train and run forecasting models using either the provided shell script or directly with Cargo.

Using the shell script:

```bash ./run_model.sh [ticker] [model_type]

Usage

Running the Models

You can run either the LSTM or GRU model using the provided shell script:

bash ./run_model.sh [ticker] [model_type]

Examples: ```bash

Run with LSTM model

./run_model.sh AAPL lstm

Run with GRU model

./run_model.sh AAPL gru ```

Alternatively, you can run directly with Cargo:

bash cargo run --release -- [ticker] [model_type]

Model Types

The application supports two types of recurrent neural networks:

1. LSTM (Long Short-Term Memory) - Default model with gates to control information flow and mitigate vanishing gradients
2. GRU (Gated Recurrent Unit) - More efficient model with fewer parameters

Both models support: - Bidirectional processing - Attention mechanisms - Configurable hyperparameters - L2 regularization and dropout

Input Data

The application expects stock data in CSV format with OHLC (Open, High, Low, Close) values. Example input file: AAPL_minute_ohlcv.csv

Implementation Details

Project Structure

• src/minute/lstm/ - LSTM implementation modules
• src/minute/gru/ - GRU implementation modules
• src/constants.rs - Common configuration constants
• src/main.rs - Entry point and execution logic

Module Organization

Each model implementation follows the same module pattern:

1. step_1_tensor_preparation.rs - Data preparation utilities
2. step_2_*_cell.rs - Core cell implementation
3. step_3_*_model_arch.rs - Complete architecture
4. step_4_train_model.rs - Training workflow
5. step_5_prediction.rs - Prediction utilities
6. step_6_model_serialization.rs - Model saving/loading

Comparing Models

When a GRU model is run with an existing LSTM model for the same ticker, the application will automatically compare predictions from both models. This helps in evaluating which model performs better for your specific dataset.

Requirements

• Rust 1.65 or higher
• CSV input data files in the expected format

License

MIT License

Project Structure

ClawFoxyVision/ src/ # Main source code util/ # Utility functions daily/ # Daily data processing minute/ # Minute data processing constants/ # Project constants test/ # Test files and utilities examples/ # Example code csv/ # Sample data files .cursor/ # Cursor IDE configuration baseline.json # Project baseline

Coding Standards

Rust Style Guide

• Formatting:

  • Max line length: 100 characters
  • Use spaces (4) for indentation
  • No tabs

• Naming Conventions:

  • Modules: snake_case
  • Functions: snake_case
  • Structs: PascalCase
  • Traits: PascalCase
  • Constants: SCREAMING_SNAKE_CASE

• Documentation:

  • All public items must be documented
  • Use rustdoc style
  • Include sections for Arguments, Returns, and Examples

Data Processing

File Handling

• Use read_financial_data as a single entry point for all financial data operations
• Automatically detects file type based on extension
• Supported file formats:
  • CSV
  • Parquet
• Required columns:
  • symbol
  • datetime
  • open
  • high
  • low
  • close
  • volume
• Optional columns:
  • adjusted_close

Example usage: ```rust use predictpricelstm::util::fileutils::readfinancial_data;

// Read financial data from either CSV or Parquet with the same function let (df, metadata) = readfinancialdata("path/to/data.csv")?; // OR let (df, metadata) = readfinancialdata("path/to/data.parquet")?; ```

Model Guidelines

LSTM Default Parameters

• sequence_length: 30
• hidden_size: 64
• num_layers: 2
• dropout_rate: 0.2

GRU Default Parameters

• sequence_length: 30
• hidden_size: 64
• num_layers: 2
• dropout_rate: 0.2

Dependencies

Required

• polars (>=0.47.1): Data manipulation
• burn (>=0.17.0): Deep learning framework
• chrono (>=0.4.41): Date and time handling
• anyhow (>=1.0.98): Error handling
• rustalib (>=1.0.0): Financial data processing

Optional

• rayon (>=1.10.0): Parallel processing
• serde (>=1.0.219): Serialization

Version Policy

• Never downgrade dependencies
• Use caret (^) versioning to allow compatible updates
• Pin versions only when necessary for stability
• Regularly update dependencies to latest compatible versions
• Test thoroughly after dependency updates

Getting Started

1. Clone the repository
2. Install dependencies: bash cargo build
3. Run examples: bash cargo run --example lstm_example cargo run --example gru_example cargo run --example parquet_lstm_gru_example # Example using Parquet files

Development Guidelines

1. Module Organization:

   • One file per module
   • Tests adjacent to source files
   • Examples in the examples directory

2. Error Handling:

   • Use anyhow::Result for error propagation
   • Provide meaningful error messages
   • Handle all potential error cases

3. Testing:

   • Write unit tests for all public functions
   • Include integration tests for complex features
   • Maintain test coverage above 80%

4. Documentation:

   • Keep documentation up to date
   • Include examples in doc comments
   • Document all public APIs

Contributing

We welcome contributions to ClawFoxyVision! Please follow our quality standards:

Quality Requirements

Every change must include:

1. Code Coverage: Comprehensive tests for new functionality
2. Examples: Working examples for external interfaces
3. Documentation: Updated documentation in the docs/ folder

Development Process

1. Read our guidelines: Check .cursorrules for detailed requirements
2. Run quality checks: Use ./scripts/quality_check.sh to verify your changes
3. Follow coding standards: Use cargo fmt and cargo clippy
4. Add tests: Maintain >80% code coverage
5. Update documentation: Keep docs in sync with code changes
6. Submit pull requests: With clear descriptions and examples

Quick Start for Contributors

```bash

Clone and setup

git clone https://github.com/rustic-ml/ClawFoxyVision cd ClawFoxyVision cargo build

Run quality checks

./scripts/quality_check.sh

Install development tools

rustup component add rustfmt clippy cargo install cargo-tarpaulin ```

For detailed contribution guidelines, see docs/developer-guide.md.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Examples

The repository includes several example implementations to demonstrate the usage of LSTM and GRU models:

Standalone Examples

• standalonelstmgru_daily.rs: A self-contained example that demonstrates both LSTM and GRU models for daily stock price prediction. It includes:

  • Forward pass timing comparisons
  • Loss calculation
  • Implementation with both regular tensors and autodiff tensors
  • Architecture comparison

• simplifiedlstmgru_comparison.rs: A comprehensive comparison between LSTM and GRU models focusing on:

  • Performance metrics (speed and accuracy)
  • Architecture differences
  • Forward pass implementation
  • Layer-by-layer configuration

• parquetlstmgru_example.rs: A complete example demonstrating how to use Parquet files with LSTM and GRU models:

  • Reading financial data from Parquet files using the unified readfinancialdata function
  • Adding technical indicators through feature engineering
  • Processing data with both LSTM and GRU models
  • Performance timing for both models
  • Suitable as a starting point for new projects using Parquet files

Other Examples

• dailylstmexample.rs: LSTM implementation for daily data
• dailygruexample.rs: GRU implementation for daily data
• dailymodelcomparison.rs: Comparison between daily LSTM and GRU models
• lstm_example.rs: Basic LSTM implementation
• gru_example.rs: Basic GRU implementation
• compare_models.rs: Utility for detailed model comparison

Burn 0.17.0 API Notes

Our examples use the Burn 0.17.0 neural network API. There are some important implementation details to be aware of:

LSTM Implementation

The LSTM forward method returns a tuple containing the output tensor and a state:

```rust // LSTM forward signature fn forward(&self, x: Tensor, state: Option>) -> (Tensor, LstmState)

// Usage example let (output, _) = lstm.forward(x, None); ```

GRU Implementation

The GRU forward method returns just the output tensor:

```rust // GRU forward signature fn forward(&self, x: Tensor, state: Option>) -> Tensor

// Usage example let output = gru.forward(x, None); ```

Tensor Operations

When working with tensors, be careful with moved values. It's often necessary to: - Store dimension values before using tensor operations - Clone tensors that will be used multiple times

```rust // Get dimensions before using tensor let sequencelength = output.dims()[1]; let hiddensize = output.dims()[2];

// Shape transformation let lastoutput = output.narrow(1, sequencelength - 1, 1) .reshape([batchsize, hiddensize]); ```

Generic Backend Type

When using autodiff backends, make sure to specify the type explicitly:

rust let auto_lstm_model: StockModel<AutoDevice> = StockModel::new(&lstm_config, &auto_device);