### Example Usage

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/PyTorchModelTrainer.md

Provides an example of how to instantiate and use the PyTorchLSTMTrainer.

```APIDOC
### Example

```python
from torch.PyTorchModelTrainer import PyTorchLSTMTrainer

lstm_trainer = PyTorchLSTMTrainer(
    model=lstm_model,
    optimizer=optimizer,
    criterion=criterion,
    device=device,
    data_convertor=convertor,
    window_size=10,
    n_epochs=50,
    batch_size=32
)

lstm_trainer.fit(data_dict, splits=["train", "test"])
```
```

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

### Configuration Example (JSON)

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/MANIFEST.txt

Example of a JSON configuration file for FreqAI. This snippet shows typical settings for core FreqAI parameters, feature engineering, data splitting, model training, and model architecture.

```json
{
  "freqai": {
    "live_trade_mode": false,
    "model_training_interval_minutes": 1440,
    "model_save_interval_minutes": 1440,
    "model_training_batch_size": 1024,
    "model_save_path": "user_data/models/freqai/"
  },
  "feature_parameters": {
    "include_time_feature": true,
    "time_feature_period_seconds": 3600
  },
  "data_split_parameters": {
    "test_size": 0.2,
    "shuffle": true,
    "stratify": "target"
  },
  "model_training_parameters": {
    "optimizer": "adam",
    "loss": "mse",
    "learning_rate": 0.001,
    "epochs": 50,
    "batch_size": 128,
    "patience": 10
  },
  "model_kwargs": {
    "hidden_size": 64,
    "num_layers": 2,
    "dropout": 0.1
  },
  "trainer_kwargs": {
    "scheduler_class": "ReduceLROnPlateau",
    "scheduler_kwargs": {
      "factor": 0.5,
      "patience": 5
    }
  }
}
```

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

### Clone FreqAI LSTM Repository and Install

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/README.md

Clone the FreqAI LSTM repository and install it using pip. This is the initial setup step for development.

```bash
# Clone repo and install
git clone https://github.com/netanelshoshan/freqai-lstm
cd freqai-lstm
pip install -e .
```

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

### Data Split Parameters Example

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/configuration.md

Example configuration for 'data_split_parameters', used to control the train/test split for model evaluation. It includes test size, random state, and shuffle settings.

```json
"data_split_parameters": {
  "test_size": 0.2,
  "random_state": 42,
  "shuffle": false
}
```

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

### Example Model Training Parameters Configuration

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/configuration.md

This JSON snippet shows a complete example of how to configure model training parameters. It includes settings for learning rate, trainer behavior (batch size, epochs), and LSTM model architecture (layers, hidden dimensions, dropout, window size).

```json
"model_training_parameters": {
  "learning_rate": 3e-3,
  "trainer_kwargs": {
    "n_steps": null,
    "batch_size": 32,
    "n_epochs": 10
  },
  "model_kwargs": {
    "num_lstm_layers": 3,
    "hidden_dim": 128,
    "dropout_percent": 0.4,
    "window_size": 5
  }
}
```

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

### Copy Model Files to Freqtrade Directory

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/README.md

Copy the necessary model and strategy files from the cloned repository to your Freqtrade installation directory. Ensure the paths are correct for your setup.

```shell
cp torch/BasePyTorchModel.py <freqtrade dir>/freqtrade/freqai/base_models/
cp torch/PyTorchLSTMModel.py <freqtrade dir >/freqtrade/freqai/torch/
cp torch/PyTorchModelTrainer.py <freqtrade dir>/freqtrade/freqai/torch/
cp torch/PyTorchLSTMRegressor.py <freqtrade dir>/user_data/freqaimodels/
cp config-example.json <freqtrade dir>/user_data/config.json
cp ExampleLSTMStrategy.py <freqtrade dir>/user_data/strategies/
```

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

### TensorBoard Callback Setup

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/LSTMRegressor.md

Initializes the TensorBoard callback to log training metrics and visualize them, specifying the log directory and histogram frequency.

```python
tensorboard_callback = TensorBoard(
    log_dir=dk.data_path,
    histogram_freq=1
)
```

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

### Example PyTorchLSTMRegressor Configuration

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/PyTorchLSTMRegressor.md

Illustrates a sample FreqTrade configuration dictionary for setting up the PyTorchLSTMRegressor. This includes enabling FreqAI and specifying parameters for the model and trainer.

```json
{
  "freqai": {
    "enabled": true,
    "model_training_parameters": {
      "learning_rate": 3e-3,
      "trainer_kwargs": {
        "n_steps": null,
        "batch_size": 32,
        "n_epochs": 10
      },
      "model_kwargs": {
        "num_lstm_layers": 3,
        "hidden_dim": 128,
        "dropout_percent": 0.4,
        "window_size": 5
      }
    }
  }
}
```

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

### Run Live Trade with Freqtrade

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/QUICK_REFERENCE.md

Starts a live trading session using the specified configuration and strategy. Ensure your configuration is set up for live trading.

```bash
freqtrade trade \
  -c config.json \
  -s ExampleLSTMStrategy
```

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

### Live Trading with ExampleLSTMStrategy

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/ExampleLSTMStrategy.md

Starts live trading using the ExampleLSTMStrategy with a given configuration. The model will train on historical data and periodically retrain based on the 'live_retrain_hours' setting in the configuration.

```bash
freqtrade trade \
  -c config-example.json \
  -s ExampleLSTMStrategy
```

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

### Feature Engineering Parameters Example

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/configuration.md

Example configuration for the 'feature_parameters' section, which controls the feature engineering pipeline. This includes settings for correlated pairs, timeframes, and indicator periods.

```json
"feature_parameters": {
  "include_corr_pairlist": ["BTC/USDT:USDT", "ETH/USDT:USDT"],
  "include_timeframes": ["2h", "4h"],
  "label_period_candles": 12,
  "include_shifted_candidates": 12,
  "DI_threshold": 10,
  "weight_factor": 0.5,
  "indicator_periods_candles": [10, 20],
  "noise_standard_deviation": 0.01,
  "buffer_train_data_candles": 20
}
```

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

### Instantiate PyTorchModelTrainer

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/PyTorchModelTrainer.md

Example of initializing the PyTorchModelTrainer with a PyTorch model, optimizer, loss function, device, and data convertor. Demonstrates setting training parameters like epochs and batch size.

```python
import torch
from torch import nn, optim
from torch.PyTorchModelTrainer import PyTorchModelTrainer
from freqtrade.freqai.torch.PyTorchDataConvertor import DefaultPyTorchDataConvertor

model = nn.Linear(20, 1)
optimizer = optim.Adam(model.parameters(), lr=1e-3)
criterion = nn.MSELoss()
convertor = DefaultPyTorchDataConvertor(target_tensor_type=torch.float)

trainer = PyTorchModelTrainer(
    model=model,
    optimizer=optimizer,
    criterion=criterion,
    device="cuda" if torch.cuda.is_available() else "cpu",
    data_convertor=convertor,
    n_epochs=10,
    batch_size=32
)
```

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

### Instantiate and Configure LSTMRegressor

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/LSTMRegressor.md

Example of how to instantiate the LSTMRegressor with a configuration and access its parameters.

```python
from tensorflow.LSTMRegressor import LSTMRegressor

regressor = LSTMRegressor(config=freqtrade_config)
print(f"Timesteps: {regressor.timesteps}")
print(f"Learning rate: {regressor.learning_rate}")
```

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

### Example PyTorchLSTMRegressor Instantiation

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/PyTorchLSTMRegressor.md

Demonstrates how to instantiate the PyTorchLSTMRegressor class with a FreqTrade configuration object. It prints the initialized learning rate, model arguments, trainer arguments, and window size.

```python
from torch.PyTorchLSTMRegressor import PyTorchLSTMRegressor

regressor = PyTorchLSTMRegressor(config=freqtrade_config)
print(f"Learning rate: {regressor.learning_rate}")
print(f"Model kwargs: {regressor.model_kwargs}")
print(f"Trainer kwargs: {regressor.trainer_kwargs}")
print(f"Window size: {regressor.window_size}")
```

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

### Minimal Configuration Example

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/PROJECT_OVERVIEW.md

This JSON snippet shows a minimal configuration for the FreqAI-LSTM model within FreqTrade's configuration file. It enables the model and specifies key training and model parameters.

```json
{
  "freqaimodel": "PyTorchLSTMRegressor",
  "freqai": {
    "enabled": true,
    "model_training_parameters": {
      "learning_rate": 3e-3,
      "trainer_kwargs": {
        "n_epochs": 10,
        "batch_size": 32
      },
      "model_kwargs": {
        "num_lstm_layers": 3,
        "hidden_dim": 128,
        "dropout_percent": 0.4,
        "window_size": 5
      }
    }
  }
}
```

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

### PyTorchLSTMTrainer Constructor and Fit Example

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/PyTorchModelTrainer.md

Instantiates a PyTorchLSTMTrainer and demonstrates its fit method. This is useful for training LSTM models with windowed data and learning rate scheduling.

```python
from torch.PyTorchModelTrainer import PyTorchLSTMTrainer

lstm_trainer = PyTorchLSTMTrainer(
    model=lstm_model,
    optimizer=optimizer,
    criterion=criterion,
    device=device,
    data_convertor=convertor,
    window_size=10,
    n_epochs=50,
    batch_size=32
)

lstm_trainer.fit(data_dict, splits=["train", "test"])
```

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

### EarlyStopping Callback Setup

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/LSTMRegressor.md

Implements EarlyStopping to halt training when the validation loss ceases to improve for a specified number of epochs, restoring the best weights found.

```python
early_stopping = EarlyStopping(
    monitor='val_loss',
    patience=10,
    restore_best_weights=True
)
```

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

### Run FreqAI LSTM Live Trading with Docker

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/README.md

Start live trading with the FreqAI LSTM Docker container. Mounts user data and specifies the configuration file.

```bash
# Run live trading
docker run -v ./user_data:/freqtrade/user_data \
  freqai-lstm:latest \
  trade -c user_data/config.json
```

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

### Install Editable Package

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/README.md

Make your Freqtrade package editable after making configuration changes. This ensures that your modifications are recognized.

```shell
pip install -e .
```

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

### Configuring PyTorchLSTMRegressor in FreqTrade

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/PyTorchLSTMRegressor.md

Example JSON configuration for FreqTrade to enable and configure the PyTorchLSTMRegressor. This includes setting the strategy and model type, and enabling FreqAI.

```json
{
  "strategy": "MyLSTMStrategy",
  "freqaimodel": "PyTorchLSTMRegressor",
  "freqai": {
    "enabled": true,
    "model_training_parameters": { ... }
  }
}
```

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

### Set CUDA Visible Devices

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/QUICK_REFERENCE.md

Specify which GPUs to use for training or inference. This is crucial for multi-GPU setups.

```bash
export CUDA_VISIBLE_DEVICES=0,1          # Use specific GPUs
```

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

### BasePyTorchModel Constructor and Initialization

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/BasePyTorchModel.md

Illustrates how to inherit from BasePyTorchModel and access its initialized properties like device, splits, and window_size. This example shows a basic implementation of a custom PyTorch model.

```python
from torch.BasePyTorchModel import BasePyTorchModel
import torch

class MyPyTorchModel(BasePyTorchModel):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        print(f"Training on device: {self.device}")
        print(f"Splits: {self.splits}")
        print(f"Window size: {self.window_size}")
    
    @property
    def data_convertor(self):
        from freqtrade.freqai.torch.PyTorchDataConvertor import DefaultPyTorchDataConvertor
        return DefaultPyTorchDataConvertor(target_tensor_type=torch.float)
    
    def fit(self, data_dictionary, dk, **kwargs):
        # Implementation required
        pass
    
    def predict(self, unfiltered_df, dk, **kwargs):
        # Implementation required
        pass

# Instantiation (FreqTrade handles this)
# model = MyPyTorchModel(config=freqtrade_config)
```

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

### PyTorch LSTM Model Initialization and Usage Example

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/PyTorchLSTMModel.md

Demonstrates how to initialize the PyTorch LSTM model and use it with both 3D (sequential) and 2D (single timestep) input data. Also shows a basic training loop structure.

```python
import torch
from torch.PyTorchLSTMModel import PyTorchLSTMModel

model = PyTorchLSTMModel(input_dim=15, output_dim=1, num_lstm_layers=2, hidden_dim=64)

# Case 1: 3D input (sequence data)
x_3d = torch.randn(32, 10, 15)  # batch=32, sequence=10, features=15
output = model(x_3d)  # shape: (32, 1)

# Case 2: 2D input (single timestep)
x_2d = torch.randn(32, 15)  # batch=32, features=15
output = model(x_2d)  # shape: (32, 1), internally expanded to (32, 1, 15)

# In training loop
optimizer.zero_grad()
predictions = model(x_batch)
loss = criterion(predictions.squeeze(), y_batch)
loss.backward()
optimizer.step()
```

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

### ReduceLROnPlateau Callback Setup

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/LSTMRegressor.md

Configures ReduceLROnPlateau to decrease the learning rate when the validation loss plateaus, with a specified reduction factor and minimum learning rate.

```python
lr_scheduler = ReduceLROnPlateau(
    monitor='val_loss',
    factor=0.2,
    patience=5,
    min_lr=0.00001
)
```

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

### Example Output Columns After set_freqai_targets

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/ExampleLSTMStrategy.md

Lists the columns added to the dataframe after the set_freqai_targets function is executed, including intermediate scores and the final target label.

```python
# After calling set_freqai_targets:
# dataframe columns now include:
# - S: Aggregate score from weighted indicators
# - R: Market regime filter from Bollinger Bands
# - V: Volatility adjustment from Bollinger Band width
# - R2: Trend regime filter from 100-SMA
# - V2: Volatility adjustment from ATR
# - &-target: Final score = S * R * V * R2 * V2
```

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

### Minimal FreqAI Configuration

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/configuration.md

A basic JSON configuration for FreqAI, enabling the model and setting essential training and backtesting periods. This configuration is suitable for initial setup and testing.

```json
{
  "exchange": {
    "name": "binance",
    "pair_whitelist": ["BTC/USDT:USDT", "ETH/USDT:USDT"],
    "sandbox": true
  },
  "freqaimodel": "PyTorchLSTMRegressor",
  "freqai": {
    "enabled": true,
    "train_period_days": 60,
    "backtest_period_days": 14,
    "model_training_parameters": {
      "learning_rate": 3e-3,
      "trainer_kwargs": {
        "n_epochs": 5,
        "batch_size": 32
      },
      "model_kwargs": {
        "num_lstm_layers": 2,
        "hidden_dim": 64,
        "window_size": 5
      }
    }
  }
}
```

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

### Validate FreqTrade Configuration via CLI

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/configuration.md

Use the FreqTrade CLI to validate your configuration file before starting the bot. This command checks for syntax errors and common misconfigurations.

```bash
freqtrade validate-config -c config.json
```

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

### Implement ExampleLSTMStrategy Methods

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/QUICK_REFERENCE.md

Demonstrates how to use the ExampleLSTMStrategy to populate indicators, trends, and calculate FreqAI targets.

```python
from ExampleLSTMStrategy import ExampleLSTMStrategy

strategy = ExampleLSTMStrategy(config)

# Method implementations:
df = strategy.populate_indicators(df, metadata={"pair": "BTC/USDT"})
df = strategy.populate_entry_trend(df, metadata)
df = strategy.populate_exit_trend(df, metadata)

# Target calculation:
df = strategy.set_freqai_targets(df, metadata)
# Adds columns: S, R, V, R2, V2, &-target
```

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

### Backtesting ExampleLSTMStrategy

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/ExampleLSTMStrategy.md

Initiates a backtest for the ExampleLSTMStrategy using a specified configuration file and timerange. The breakdown option provides daily, weekly, and monthly performance summaries.

```bash
freqtrade backtesting \
  -c config-example.json \
  -s ExampleLSTMStrategy \
  --timerange 20240301-20240401 \
  --breakdown day week month
```

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

### Instantiate and Use PyTorchLSTMModel

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/PyTorchLSTMModel.md

Demonstrates how to create an instance of the PyTorchLSTMModel, move it to the appropriate device (CPU or GPU), and perform a forward pass with sample data. This is useful for setting up the model for training or inference.

```python
import torch
from torch.PyTorchLSTMModel import PyTorchLSTMModel

# Create model with 3 LSTM layers, 128 hidden units, 20 input features, 1 output
model = PyTorchLSTMModel(
    input_dim=20,
    output_dim=1,
    num_lstm_layers=3,
    hidden_dim=128,
    dropout_percent=0.4
)

# Move to GPU
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
model = model.to(device)

# Example forward pass
batch_size = 32
sequence_length = 10
x = torch.randn(batch_size, sequence_length, 20).to(device)
output = model(x)  # shape: (batch_size, 1)
print(output.shape)
```

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

### LSTMRegressor Constructor

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/LSTMRegressor.md

Initializes the LSTMRegressor, handling configuration and GPU setup.

```python
def __init__(self, **kwargs) -> None:

```

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

### LSTMRegressor Predict Example Usage

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/LSTMRegressor.md

Demonstrates how to call the predict method with a DataFrame and DataKitchen object to obtain predictions and outlier detection information.

```python
predictions, do_predict = regressor.predict(
    unfiltered_df=df,
    dk=data_kitchen
)
# predictions: DataFrame with 1 column (predicted target)
# do_predict: Boolean array indicating valid predictions
```

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

### Pair String Type Alias

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/types.md

Defines a type alias for specifying trading pairs, with examples like 'BTC/USDT:USDT' or 'ETH/USDT:USDT'.

```python
pair: str = "BTC/USDT:USDT" | "ETH/USDT:USDT"
```

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

### Hyperopt Strategy with Freqtrade

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/QUICK_REFERENCE.md

Optimizes strategy hyperparameters for buy and sell signals over a specified number of epochs. Requires a configuration file and strategy.

```bash
freqtrade hyperopt \
  -c config.json \
  -s ExampleLSTMStrategy \
  --epochs 100 \
  --spaces buy sell
```

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

### Run Backtest

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/README.md

Execute a backtest of the trading strategy using the Freqtrade CLI. Specify the configuration file, breakdown period, and timerange for the backtest.

```shell
freqtrade backtesting -c user_data/config-torch.json --breakdown day week month --timerange 20240301-20240401 
```

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

### Run Hyperparameter Optimization

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/configuration.md

Execute the hyperopt command to automatically optimize strategy parameters. Specify the configuration file, strategy, epochs, parameter spaces, and timerange for the optimization.

```bash
freqtrade hyperopt \
  -c config-example.json \
  -s ExampleLSTMStrategy \
  --epochs 100 \
  --spaces buy sell \
  --timerange 20240101-20240228
```

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

### Build Local Docker Images

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/README.md

Build the local Docker images for the FreqAI project. Ensure you are in the cloned repository's root directory.

```shell
cd freqAI-LSTM
docker build -f torch/Dockerfile  -t freqai .
```

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

### Integrating PyTorchLSTMRegressor in a FreqTrade Strategy

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/PyTorchLSTMRegressor.md

Example of how to integrate the PyTorchLSTMRegressor within a custom FreqTrade strategy class. FreqTrade manages the regressor's lifecycle automatically.

```python
from freqtrade.strategy import IStrategy

class MyLSTMStrategy(IStrategy):
    def __init__(self, config):
        super().__init__(config)
        # FreqTrade automatically instantiates the regressor
        # No need to create it manually

    def populate_indicators(self, dataframe, metadata):
        # FreqAI calls regressor.fit() and regressor.predict() internally
        if self.freqai:
            dataframe = self.freqai.start(dataframe, metadata, self)
        return dataframe
```

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

### Set up PyTorch DataLoader

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/types.md

Wrap datasets with DataLoader for efficient batching, shuffling, and parallel data loading during training. Configure batch size, shuffling, and worker count.

```python
from torch.utils.data import DataLoader, TensorDataset

dataset = TensorDataset(features_tensor, labels_tensor)
loader = DataLoader(
    dataset,
    batch_size=32,
    shuffle=True,
    drop_last=True
)
```

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

### Implement DefaultPyTorchDataConvertor

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/BasePyTorchModel.md

Subclasses must implement the data_convertor property to return a PyTorchDataConvertor. This example shows the default implementation for converting pandas DataFrames to float tensors.

```python
from freqtrade.freqai.torch.PyTorchDataConvertor import DefaultPyTorchDataConvertor
import torch

@property
def data_convertor(self):
    return DefaultPyTorchDataConvertor(target_tensor_type=torch.float)
```

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

### Initialize, Train, and Predict with PyTorchLSTMRegressor

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/QUICK_REFERENCE.md

Shows the primary workflow for using the PyTorchLSTMRegressor: initialization, training with a data dictionary, and making predictions.

```python
from torch.PyTorchLSTMRegressor import PyTorchLSTMRegressor

# Initialize
regressor = PyTorchLSTMRegressor(config=config)

# Train
trainer = regressor.fit(
    data_dictionary={
        "train_features": df,  # (n, m)
        "train_labels": df,    # (n, 1)
        "test_features": df,   # (m, m)
        "test_labels": df      # (m, 1)
    },
    dk=data_kitchen
)

# Predict
predictions, do_predict = regressor.predict(
    unfiltered_df=df,
    dk=data_kitchen
)
```

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

### Define RealParameter for Hyperopt

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/types.md

Example of defining RealParameter objects for hyperparameter optimization. These parameters specify the range, default value, and optimization space for tunable strategy variables.

```python
threshold_buy = RealParameter(-1, 1, default=0, space='buy')
weight = RealParameter(0, 1, default=0.5, space='buy')
```

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

### Buy Parameters Configuration

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/ExampleLSTMStrategy.md

Configuration dictionary for buy parameters, including entry threshold and weights for various technical indicators. These parameters are used to determine when to enter a trade.

```python
buy_params = {
    "threshold_buy": 0.59453,
    "w0": 0.54347,
    "w1": 0.82226,
    "w2": 0.56675,
    "w3": 0.77918,
    "w4": 0.98488,
    "w5": 0.31368,
    "w6": 0.75916,
    "w7": 0.09226,
    "w8": 0.85667,
}
```

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

### Populate Entry Trend - ExampleLSTMStrategy

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/ExampleLSTMStrategy.md

Generates long and short entry signals based on predicted target score and volume. Use when needing to define conditions for entering new trades.

```python
def populate_entry_trend(self, df: DataFrame, metadata: dict) -> DataFrame:
```

```python
# If &-target = 0.8 and threshold_buy = 0.59:
# 0.8 > 0.59 → generate long entry signal

# If &-target = -0.5 and threshold_sell = 0.80:
# -0.5 < 0.80 → generate short entry signal
```

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

### LSTM Model Training Parameters Configuration

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/README.md

Example JSON configuration for training parameters of the PyTorch LSTM model. This includes learning rate, trainer arguments, and model-specific arguments.

```json
"model_training_parameters": {
    "learning_rate": 3e-3,
    "trainer_kwargs": {
    "n_steps": null,
    "batch_size": 32,
    "n_epochs": 10,
    },
    "model_kwargs": {
    "num_lstm_layers": 3,
    "hidden_dim": 128,
    "dropout_percent": 0.4,
    "window_size": 5
    }
}
```

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

### Import and Instantiate WindowDataset

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/types.md

Imports and demonstrates the instantiation of WindowDataset for creating sequential data windows for LSTM training. The dataset transforms flat tensors into sequences.

```python
from torch.datasets import WindowDataset

dataset = WindowDataset(x_tensor, y_tensor, window_size=10)
```

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

### Run Backtest using Docker

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/README.md

Execute a Docker container to perform backtesting on the downloaded data. This command also mounts the local 'data' directory.

```shell
docker run -v ./data:/freqtrade/user_data/data  -it freqai  backtesting -c user_data/config-torch.json --breakdown day week month --timerange 20240301-20240401 
```

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

### ExampleLSTMStrategy Class Definition

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/ExampleLSTMStrategy.md

Defines the ExampleLSTMStrategy class, inheriting from freqtrade.strategy.IStrategy. This class implements a complete trading strategy.

```python
class ExampleLSTMStrategy(IStrategy):
```

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

### ExampleLSTMStrategy Class Signature

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/QUICK_REFERENCE.md

Defines the ExampleLSTMStrategy class, inheriting from IStrategy. It includes methods for feature engineering, setting targets, populating indicators, and defining entry/exit trends.

```python
class ExampleLSTMStrategy(IStrategy):
    
    def feature_engineering_expand_all(
        self,
        dataframe: DataFrame,
        period: int,
        metadata: Dict,
        **kwargs
    ) -> DataFrame
    
    def feature_engineering_expand_basic(
        self,
        dataframe: DataFrame,
        metadata: Dict,
        **kwargs
    ) -> DataFrame
    
    def feature_engineering_standard(
        self,
        dataframe: DataFrame,
        metadata: Dict,
        **kwargs
    ) -> DataFrame
    
    def set_freqai_targets(
        self,
        dataframe: DataFrame,
        metadata: Dict,
        **kwargs
    ) -> DataFrame
    
    def populate_indicators(
        self,
        dataframe: DataFrame,
        metadata: dict
    ) -> DataFrame
    
    def populate_entry_trend(
        self,
        df: DataFrame,
        metadata: dict
    ) -> DataFrame
    
    def populate_exit_trend(
        self,
        df: DataFrame,
        metadata: dict
    ) -> DataFrame
```

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

### Get PyTorchLSTMRegressor Data Converter

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/PyTorchLSTMRegressor.md

Accesses the data converter for transforming pandas DataFrames to PyTorch tensors. It's configured to use float32 tensors for regression targets and can be used to convert features for model input.

```python
convertor = regressor.data_convertor
# Used internally by trainer to convert data
tensor = convertor.convert_x(df_features, device="cuda")
```

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

### Fit PyTorchLSTMRegressor Model

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/PyTorchLSTMRegressor.md

Fits the PyTorch LSTM regressor model to the provided data. This method handles model creation, optimizer and loss function setup, and training using the PyTorchLSTMTrainer. It supports continual learning by loading initial states if available.

```python
from freqtrade.freqai.data_kitchen import FreqaiDataKitchen

# Within FreqTrade's training workflow:
regressor = PyTorchLSTMRegressor(config=config)

data_dict = {
    "train_features": df_train_features,  # (1000, 20)
    "train_labels": df_train_labels,      # (1000, 1)
    "test_features": df_test_features,    # (200, 20)
    "test_labels": df_test_labels         # (200, 1)
}

trainer = regressor.fit(data_dict, dk=data_kitchen)
# trainer is now a PyTorchLSTMTrainer with trained weights
print(f"Model: {trainer.model}")
print(f"Device: {trainer.device}")
```

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

### ExampleLSTMStrategy

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/README.md

A complete FreqTrade strategy that demonstrates the integration of an LSTM model. It includes methods for feature engineering, target calculation, and populating trading signals.

```APIDOC
## Class: ExampleLSTMStrategy

### Description
A FreqTrade strategy example that utilizes an LSTM model for trading decisions.

### Methods
- `feature_engineering_expand_all()`: Generates multi-period technical indicators.
- `feature_engineering_expand_basic()`: Creates basic features like percentage change, volume, and price.
- `feature_engineering_standard()`: Adds temporal features such as day of the week and hour of the day.
- `set_freqai_targets()`: Calculates target scores using normalized indicators, dynamic weights, regime, and volatility.
- `populate_indicators()`: Integrates FreqAI features into the strategy.
- `populate_entry_trend()`: Defines logic for generating long and short entry signals.
- `populate_exit_trend()`: Defines logic for generating exit signals.
```

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

### Set up ReduceLROnPlateau Scheduler

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/QUICK_REFERENCE.md

Configures a learning rate scheduler that reduces the learning rate when a metric has stopped improving. Use with validation loss.

```python
scheduler = ReduceLROnPlateau(
    optimizer,
    mode='min',
    factor=0.2,      # Multiply LR by 0.2
    patience=5,      # Epochs without improvement
    min_lr=1e-5      # Floor
)
scheduler.step(val_loss)
```

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

### Tune Hyperparameters with FreqTrade

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/README.md

Tunes strategy hyperparameters using FreqTrade's hyperopt command. Results are saved to user data directory.

```bash
# Via FreqTrade hyperopt:
freqtrade hyperopt -c config.json -s ExampleLSTMStrategy --epochs 100

# Optimizes:
# - threshold_buy, threshold_sell (strategy parameters)
# - w0-w8 (indicator weights)

# Results written to {USER_DATA_DIR}/hyperopt_results/
```

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

### Initialize PyTorch Optimizers

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/types.md

Instantiate optimizers like Adam or AdamW to manage model parameter updates during training. Specify the model parameters and learning rate.

```python
import torch.optim as optim

optimizer = optim.Adam(model.parameters(), lr=0.001)
optimizer = optim.AdamW(model.parameters(), lr=0.001)
```

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

### ExampleLSTMStrategy Class Overview

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/MANIFEST.txt

This class provides a complete FreqTrade trading strategy implementation using LSTM. It includes configuration for buy/sell parameters, ROI, stoploss, and tunable parameters. It also features various methods for feature engineering, target calculation, and signal generation for entry and exit trends.

```python
class ExampleLSTMStrategy(IStrategy):
    # ... (implementation details) ...

    # Class configuration
    buy_params = {
        "patience": 10,
        "epochs": 100,
        "batch_size": 128,
        "lr": 0.001,
    }
    sell_params = {
        "patience": 10,
        "epochs": 100,
        "batch_size": 128,
        "lr": 0.001,
    }
    minimal_roi = {
        "0": 0.05,
        "20": 0.02,
        "40": 0.01,
    }
    stoploss = -0.1

    # Tunable parameters
    real_param_buy_strength = RealParameter(0.1, 1.0, default=0.5, space='buy')
    real_param_sell_strength = RealParameter(0.1, 1.0, default=0.5, space='sell')

    # Feature engineering methods
    def feature_engineering_expand_all(self):
        # ... (12 technical indicators) ...
        pass

    def feature_engineering_expand_basic(self):
        # ... (3 basic features) ...
        pass

    def feature_engineering_standard(self):
        # ... (2 temporal features) ...
        pass

    # Target calculation
    def set_freqai_targets(self):
        # ... (5-step target score calculation) ...
        pass

    # FreqAI integration
    def populate_indicators(self):
        # ... (FreqAI integration) ...
        pass

    # Signal generation
    def populate_entry_trend(self):
        # ... (long/short entry signals) ...
        pass

    def populate_exit_trend(self):
        # ... (exit signal generation) ...
        pass
```

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

### Download Data using Docker

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/README.md

Run a Docker container to download historical data for backtesting. This command mounts a local 'data' directory to store the downloaded data.

```shell
docker run -v ./data:/freqtrade/user_data/data  -it freqai  download-data -c user_data/config-torch.json --timerange 20230101-20240529 --timeframe 15m 30m 1h 2h 4h 8h 1d --erase
```

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

### Backtest Strategy with FreqTrade

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/README.md

Performs a backtest of a strategy using FreqTrade with a specified timerange.

```bash
freqtrade backtesting -c config.json --timerange 20240101-20240331
```

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

### Configuration Dictionary Structure

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/types.md

Outlines the nested structure of the configuration dictionary, detailing parameters for FreqAI, model training, data splitting, and feature engineering.

```python
config = {
    "freqai": {
        "enabled": bool,
        "model_training_parameters": {
            "learning_rate": float,
            "trainer_kwargs": {
                "n_epochs": int,
                "batch_size": int,
                "n_steps": Optional[int],
            },
            "model_kwargs": {
                "num_lstm_layers": int,
                "hidden_dim": int,
                "dropout_percent": float,
                "window_size": int,
            },
        },
        "data_split_parameters": {
            "test_size": float,
            "random_state": int,
            "shuffle": bool,
        },
        "feature_parameters": Dict[str, Any],
    },
}
```

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

### Tunable Parameters for Optimization

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/ExampleLSTMStrategy.md

Defines buy and sell thresholds, along with weights for different components, allowing for optimization via hyperopt or manual adjustment. These parameters influence the strategy's decision-making process.

```python
threshold_buy = RealParameter(-1, 1, default=0, space='buy')
threshold_sell = RealParameter(-1, 1, default=0, space='sell')
w0 = RealParameter(0, 1, default=0.10, space='buy')
w1 = RealParameter(0, 1, default=0.15, space='buy')
w2 = RealParameter(0, 1, default=0.10, space='buy')
w3 = RealParameter(0, 1, default=0.15, space='buy')
w4 = RealParameter(0, 1, default=0.10, space='buy')
w5 = RealParameter(0, 1, default=0.10, space='buy')
w6 = RealParameter(0, 1, default=0.10, space='buy')
w7 = RealParameter(0, 1, default=0.05, space='buy')
w8 = RealParameter(0, 1, default=0.15, space='buy')
```

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

### Run FreqAI LSTM Backtest with Docker

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/README.md

Execute a backtest using the FreqAI LSTM Docker container. Mounts user data and specifies the configuration file.

```bash
# Run backtest
docker run -v ./user_data:/freqtrade/user_data \
  freqai-lstm:latest \
  backtesting -c user_data/config.json
```

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

### Configure AdamW Optimizer

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/QUICK_REFERENCE.md

Sets up the AdamW optimizer for model training. Typical learning rate is 3e-3. Weight decay implements L2 regularization.

```python
optimizer = torch.optim.AdamW(
    model.parameters(),
    lr=learning_rate,  # 3e-3 typical
    betas=(0.9, 0.999),  # Default
    eps=1e-8,            # Default
    weight_decay=0.01    # L2 regularization
)
```

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

### Full PyTorchLSTMRegressor Configuration

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/PyTorchLSTMRegressor.md

This snippet demonstrates a comprehensive configuration for the PyTorchLSTMRegressor, including advanced features like data splitting, feature inclusion, and extended training parameters. Refer to config-example.json for a complete reference.

```json
{
  "freqaimodel": "PyTorchLSTMRegressor",
  "freqai": {
    "enabled": true,
    "identifier": "torch-lstm",
    "train_period_days": 120,
    "fit_live_predictions_candles": 24,
    "backtest_period_days": 30,
    "expiration_hours": 4,
    "live_retrain_hours": 4,
    "feature_parameters": {
      "include_corr_pairlist": ["BTC/USDT:USDT"],
      "include_timeframes": ["2h", "4h"],
      "label_period_candles": 12,
      "DI_threshold": 10
    },
    "data_split_parameters": {
      "test_size": 0.2,
      "random_state": 42,
      "shuffle": false
    },
    "model_training_parameters": {
      "learning_rate": 3e-3,
      "trainer_kwargs": {
        "n_steps": null,
        "batch_size": 32,
        "n_epochs": 10
      },
      "model_kwargs": {
        "num_lstm_layers": 3,
        "hidden_dim": 128,
        "dropout_percent": 0.4,
        "window_size": 5
      }
    }
  }
}
```

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

### device

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/BasePyTorchModel.md

Returns the device string for PyTorch tensor placement. This can be 'cuda' for NVIDIA GPUs, 'mps' for Apple Silicon, or 'cpu' as a fallback.

```APIDOC
## device

### Description
Returns the device string for PyTorch tensor placement. Value is one of:
- `"cuda"` — NVIDIA GPU via CUDA
- `"mps"` — Apple Silicon via Metal Performance Shaders
- `"cpu"` — CPU fallback

### Type
`str`

### Example
```python
model = BasePyTorchModel(config=config)
tensor = torch.randn(10, 5).to(model.device)  # Move tensor to selected device
```
```

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

### Output Directory Structure

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/DOCUMENTATION_INDEX.md

Lists the generated markdown files and their locations within the output directory. This helps users navigate to specific documentation sections.

```bash
output/
├── README.md                          # Main entry point
├── QUICK_REFERENCE.md                 # Cheat sheet
├── PROJECT_OVERVIEW.md                # Architecture guide
├── DOCUMENTATION_INDEX.md             # This file
├── configuration.md                   # Config reference
├── types.md                           # Type definitions
└── api-reference/
    ├── BasePyTorchModel.md
    ├── ExampleLSTMStrategy.md
    ├── LSTMRegressor.md
    ├── PyTorchLSTMModel.md
    ├── PyTorchLSTMRegressor.md
    └── PyTorchModelTrainer.md
```

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

### load

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/PyTorchModelTrainer.md

Loads the training state of a PyTorch model trainer from a specified checkpoint file.

```APIDOC
## load

### Description
Loads the training state of a PyTorch model trainer from a specified checkpoint file.

### Method
```python
def load(self, path: Path)
```

### Parameters
#### Path Parameters
- **path** (Path) - Required - File path to checkpoint (previously saved via `save()`).

### Returns
self (trainer instance with loaded state)

### Behavior
1. Loads checkpoint dict from path via `torch.load(path)`
2. Calls `load_from_checkpoint(checkpoint)`
3. Returns self for method chaining

### Example
```python
trainer = PyTorchModelTrainer(...)
trainer = trainer.load(Path("models/model_v1.pkl"))
```
```

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

### Sell Parameters Configuration

Source: https://github.com/netanelshoshan/freqai-lstm/blob/main/_autodocs/api-reference/ExampleLSTMStrategy.md

Configuration dictionary for sell parameters, specifically the exit threshold. This parameter determines when to exit a trade based on the strategy's calculated target.

```python
sell_params = {
    "threshold_sell": 0.80573,
}
```