Models

This module contains functions for model definitions, prediction, saving, training, and tuning.

Model Definitions

roberta_model: Creates a classification model using the Roberta architecture.
rnn_model: Creates a classification model using the RNN architecture.
load_model: Loads a pre-trained model from the specified path.

from emotion_detective.models.model_definitions import create_model, roberta_model, rnn_model

# Example usage
roberta = roberta_model(num_labels=7)
rnn = rnn_model(num_labels=7, embedding_dim=128, hidden_dim=256)
loaded_model = load_model(model_path='path/to/model.pth')

class emotion_detective.models.model_definitions.RNNModel(vocab_size: int, embedding_dim: int, hidden_dim: int, output_dim: int)

Bases: Module

forward(x: Tensor) → Tensor

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

emotion_detective.models.model_definitions.load_model(model_path: str) → Module

Load a pre-trained model from the specified path.

Parameters:: model_path (str) – Path to the model file.
Returns:: The loaded model.
Return type:: torch.nn.Module

Author: Rebecca Borski, Martin Vladimirov

emotion_detective.models.model_definitions.rnn_model(num_labels: int, embedding_dim: int = 128, hidden_dim: int = 256) → Any

Creates a classification model using an RNN architecture.

Parameters:

num_labels (int) – Number of output labels/classes.
embedding_dim (int, optional) – Dimension of word embeddings. Defaults to 128.
hidden_dim (int, optional) – Dimension of hidden states in the RNN.
256. (Defaults to)

Returns:

An RNN model initialized with the specified parameters.

Return type:

RNNModel

Author: Martin Vladimirov

emotion_detective.models.model_definitions.roberta_model(num_labels: int) → RobertaForSequenceClassification

Creates a classification model using the RoBERTa architecture.

Parameters:: num_labels (int) – The number of labels/classes for the classification task.
Returns:: A RoBERTa model initialized with the specified number of labels.
Return type:: RobertaForSequenceClassification

Author: Rebecca Borski

Troubleshooting

roberta_model: - Ensure that the “roberta-base” model is available and correctly specified. - Check for sufficient memory resources. - Verify internet connectivity if downloading the model. - If an error occurs, inspect the log for detailed error messages. - Example code snippet for troubleshooting:
try:
    model = roberta_model(num_labels=6)
except Exception as e:
    print("Error:", e)
rnn_model:

Ensure that the tokenizer (bert-base-uncased) is available and correctly specified.

Check for sufficient memory resources, especially if using large embedding or hidden dimensions.

Verify internet connectivity if downloading tokenizer or embeddings.

If an error occurs, inspect the log for detailed error messages.

Example code snippet for troubleshooting:
try:
   model = rnn_model(num_labels=6, embedding_dim=128, hidden_dim=256)
except Exception as e:
   print("Error:", e)
load_model: - Confirm the model path is correct and accessible. - Ensure the file format matches the expected format ‘.pth’. - If an error occurs, inspect the log for detailed error messages. - Example code snippet for troubleshooting:
try:
    loaded_model = load_model(model_path='path/to/model.pth')
except Exception as e:
    print("Error:", e)

Model Prediction

get_predictions: Obtain predictions from a model based on the input DataFrame.

from emotion_detective.models.model_predict import get_predictions

# Example usage
predictions_df = get_predictions(model_path, df, emotion_mapping_path='path/to/mapping.json', model_type='roberta')

emotion_detective.models.model_predict.get_predictions(model_path, df, emotion_mapping_path=None, model_type='roberta')

Perform predictions using a specified model on a DataFrame containing text data. This function loads a model, tokenizes input data based on the specified model_type, performs predictions, and optionally maps numeric emotions back to string labels.

Parameters: - model_path (str): Path to the trained model. - df (pd.DataFrame): DataFrame containing ‘text’ column with input text data. - emotion_mapping_path (str, optional): Path to JSON file mapping numeric emotions to string labels. - model_type (str, optional): Type of model to use (‘roberta’ or ‘rnn’). Default is ‘roberta’.

Returns: pd.DataFrame: DataFrame with added ‘emotion’ column containing predicted emotions.

Raises: ValueError: If an unsupported model_type is provided. Exception: If there’s an error during tokenization, prediction, or emotion mapping.

Author: Rebecca Borski

Troubleshooting

get_predictions: - Verify that the input DataFrame is correctly formatted. - Ensure the model is in evaluation mode. - Make sure the data loader is working correctly. - If an error occurs, inspect the log for detailed error messages. - Example code snippet for troubleshooting:
try:
    predictions_df = get_predictions(model, df, emotion_mapping_path='path/to/mapping.json', model_type='roberta')
except Exception as e:
    print("Error:", e)

Model Saving

save_model: Saves the state of a PyTorch model to a binary file.

from emotion_detective.models.model_saving import save_model

# Example usage
save_model(model, model_dir='models', model_name='my_model')

emotion_detective.models.model_saving.save_model(model: Module, model_dir: str, model_name: str)

Saves the state of a PyTorch model to a binary file.

Parameters: model (torch.nn.Module): The model to save. model_dir (str): Directory path where the model will be saved. model_name (str): Name of the file to save the model as.

Returns: None

Author: Andrea Tosheva

Troubleshooting

save_model: - Confirm the directory path exists or can be created. - Check file permissions for writing. - Ensure the model is properly instantiated and not None. - If an error occurs, inspect the log for detailed error messages. - Example code snippet for troubleshooting:
try:
    save_model(model, model_dir='models', model_name='my_model')
except Exception as e:
    print("Error:", e)

Model Training

train_and_evaluate_roberta: Trains and evaluates a neural network model for emotion detection based on the roberta model architecture.
train_and_evaluate_rnn: Trains and evaluates a neural network model for emotion detection based on the RNN model architecture.

from emotion_detective.models.model_training import train_and_evaluate_roberta, train_and_evaluate_rnn
import pandas as pd

# Train and evaluate RoBERTa Example usage
trained_model, evaluation_results = train_and_evaluate_roberta(
   roberta_model=roberta_model,
   train_data=train_data,
   test_data=test_data,
   output_dir='./roberta_output/',
   logging_dir='./logs/',
   num_train_epochs=3,
   train_batch_size=4,
   eval_batch_size=8,
   gradient_accumulation_steps=16,
   learning_rate=2e-5,
   warmup_steps=500,
   weight_decay=0.01,
   logging_steps=8,
   disable_tqdm=False,
   dataloader_num_workers=8,
   seed=42,
   early_stopping_patience=3,
   cloud_logging=True
)

# Print evaluation results
print("Evaluation results:", evaluation_results)

# Train and evaluate RNN Example usage
trained_rnn_model = train_and_evaluate_rnn(
   model=rnn_model,
   train_data=train_data,
   test_data=test_data,
   num_epochs=5,
   early_stopping_patience=3,
   learning_rate=0.001,
   train_batch_size=4,
   eval_batch_size=8,
   cloud_logging=True
)

emotion_detective.models.model_training.train_and_evaluate_rnn(model: Module, train_data: DataFrame, test_data: DataFrame, num_epochs: int = 3, early_stopping_patience: int = 3, learning_rate: float = 0.001, train_batch_size: int = 4, eval_batch_size: int = 8, cloud_logging: bool = False) → Module

Train and evaluate an RNN model using the given training and test data.

Parameters:

model – RNN model to train.
train_data – Training data in a pandas DataFrame.
test_data – Test data in a pandas DataFrame.
num_epochs – Number of training epochs.
early_stopping_patience – Patience for early stopping.
learning_rate – Learning rate for training.
train_batch_size – Batch size for training.
eval_batch_size – Batch size for evaluation.
cloud_logging – Enable cloud logging with MLflow if True.

Returns:

The trained RNN model.

Author: Rebecca Borski

emotion_detective.models.model_training.train_and_evaluate_roberta(roberta_model: Module, train_data: DataFrame, test_data: DataFrame, output_dir: str = './', logging_dir: str = './', num_train_epochs: int = 1, train_batch_size: int = 4, eval_batch_size: int = 8, gradient_accumulation_steps: int = 16, learning_rate: float = 2e-05, warmup_steps: int = 500, weight_decay: float = 0.01, logging_steps: int = 8, disable_tqdm: bool = False, dataloader_num_workers: int = 8, seed: int = 42, early_stopping_patience: int = 3, cloud_logging: bool = False) → Tuple[Module, Dict[str, Any]]

Train and evaluate a RoBERTa model using the given training and test data.

Parameters:

roberta_model – Pre-trained RoBERTa model to fine-tune.
train_data – Training data in a pandas DataFrame.
test_data – Test data in a pandas DataFrame.
output_dir – Directory to save the model and outputs.
logging_dir – Directory to save the logs.
num_train_epochs – Number of training epochs.
train_batch_size – Batch size for training.
eval_batch_size – Batch size for evaluation.
gradient_accumulation_steps – Number of gradient accumulation steps.
learning_rate – Learning rate for training.
warmup_steps – Number of warmup steps.
weight_decay – Weight decay for the optimizer.
logging_steps – Frequency of logging.
disable_tqdm – Disable tqdm progress bar if “True”.
dataloader_num_workers – Number of worker threads for data loading.
seed – Random seed for reproducibility.
early_stopping_patience – Patience for early stopping.
cloud_logging – Enable cloud logging with MLflow if True.

Returns:

A tuple containing the trained model and evaluation results.

Author: Rebecca Borski

Troubleshooting

train_and_evaluate_roberta:

Model Training Issues: If the model fails to train, check the batch sizes (train_batch_size, eval_batch_size), and gradient_accumulation_steps settings. Adjusting these parameters can help resolve memory issues or improve training stability.

Logging Errors: If logging fails (e.g., with MLflow), ensure the logging directories (output_dir, logging_dir) are accessible and have write permissions. Also, verify that MLflow is correctly configured and running.

Performance Metrics: If the evaluation metrics are unexpected, ensure that compute_metrics function correctly computes metrics relevant to your task. Check if the labels and predictions are aligned properly in compute_metrics.

train_and_evaluate_rnn:

Tokenization Errors: If tokenization fails, ensure BertTokenizer (or equivalent) is correctly initialized and that text lengths are within tokenizer limits (max_length). Adjust tokenize function parameters accordingly.

Training Convergence: If the model does not converge or loss does not decrease, check learning_rate and consider adjusting it. Also, monitor training and validation losses (train_loss, eval_loss) to ensure they are reasonable and decreasing over epochs.

Early Stopping: If early stopping triggers unexpectedly or too early, review early_stopping_patience and eval_loss monitoring. Adjust these parameters based on model convergence patterns observed during training.