Text2BedNN Module

Vec2VecFNN

class Vec2VecFNN(model_path: Union[str, None] = None)

Initialize Vec2VecFNN.

Args: model_path (Union[str, None]): Path to the pretrained model on HuggingFace.

Attributes

• model
• trained
• optimizer
• loss_fn
• config
• most_recent_train

Methods

load_from_disk

def load_from_disk(model_path: str, config_path: str)

Load model from local files.

Args: model_path (str): Path of saved model file (usually in format of .pt). config_path (str): Path of saved config file (in format of yaml).

export

def export(path: str, checkpoint_file: str, config_file: str = CONFIG_FILE_NAME, must_trained: bool = DEFAULT_MUST_TRAINED)

Save model weights and config.

Args: path (str): Path to export the model to. checkpoint_file (str): Name of model checkpoint file. config_file (str): Name of model config file. must_trained (bool): Whether the model needs training to be exported.

embedding_to_embedding

def embedding_to_embedding(input_vecs: np.ndarray) -> np.ndarray

Predict the region set embedding from embedding of natural language strings.

Args: input_vecs (np.ndarray): Input embedding vectors.

Returns: np.ndarray: The output of the neural network model.

compile

def compile(optimizer: str, loss: str, learning_rate: float, margin: Union[float, None] = DEFAULT_MARGIN)

Configure the model for training.

This includes setting the optimizer and loss function.

Args: optimizer (str): The name of optimizer. loss (str): The name of loss function. learning_rate (float): The learning rate of model backpropagation. margin (Union[float, None]): Should be a number from -1 to 1, 0 to 0.5 is suggested, only for CosineEmbeddingLoss.

train

def train(training_X: np.ndarray, training_Y: np.ndarray, validating_data: Union[Tuple[np.ndarray, np.ndarray], None] = None, save_best: bool = False, folder_path: Union[str, None] = None, best_model_file_name: Union[str, None] = None, early_stop: bool = False, patience: float = DEFAULT_PATIENCE, opt_name: str = DEFAULT_OPTIMIZER_NAME, loss_func: str = DEFAULT_LOSS_NAME, num_epochs: int = DEFAULT_NUM_EPOCHS, batch_size: int = DEFAULT_BATCH_SIZE, learning_rate: float = DEFAULT_LEARNING_RATE, training_target: Union[np.ndarray, None] = None, validating_target: Union[np.ndarray, None] = None, **kwargs)

Fit the feedforward neural network.

Based on https://pytorch.org/tutorials/beginner/introyt/trainingyt.html

Args: training_X (np.ndarray): Embedding vectors of metadata with shape (n, ). training_Y (np.ndarray): Embedding vectors of region set with shape (n, ). validating_data (Union[Tuple[np.ndarray, np.ndarray], None]): Validating data containing validating X and validating Y. save_best (bool): Whether the best performance model is saved after each epoch based on validation loss. folder_path (Union[str, None]): The path to the folder to save the model and config. best_model_file_name (Union[str, None]): The name of the file of saved best model. early_stop (bool): Whether the training should be stopped early to prevent overfitting. patience (float): The percentage of epochs to stop training if no validation loss improvement. opt_name (str): Name of optimizer. loss_func (str): Name of loss function. num_epochs (int): Number of training epochs. batch_size (int): Size of batch for training. learning_rate (float): Learning rate of optimizer. training_target (Union[np.ndarray, None]): Target values for training data. validating_target (Union[np.ndarray, None]): Target values for validating data. **kwargs: See units and layers in reinit_model().

train_one_epoch

def train_one_epoch(training_data) -> torch.Tensor

One epoch's training loop.

Based on https://pytorch.org/tutorials/beginner/introyt/trainingyt.html

Returns: torch.Tensor: The average training loss of one epoch.

calc_loss

def calc_loss(outputs: torch.Tensor, y: torch.Tensor, target: torch.Tensor) -> torch.Tensor

Calculate loss when different loss function is given.

Args: outputs (torch.Tensor): The output of model. y (torch.Tensor): The correct label. target (torch.Tensor): Target tensor.

Returns: torch.Tensor: The loss value.

plot_training_hist

def plot_training_hist(save_path: Union[str, None] = None, plot_file_name: Union[str, None] = DEFAULT_PLOT_FILE_NAME, title: Union[str, None] = DEFAULT_PLOT_TITLE) -> None

Plot the training and validating loss of the most recent training.

Args: save_path (Union[str, None]): The path of folder where image will be saved. plot_file_name (Union[str, None]): The file name of the png file. title (Union[str, None]): The title in the image.

arrays_to_torch_dataloader

def arrays_to_torch_dataloader(X: np.ndarray, Y: np.ndarray, target: np.ndarray, batch_size: int = DEFAULT_BATCH_SIZE, shuffle: bool = DEFAULT_DATALOADER_SHUFFLE) -> DataLoader

Store numpy arrays of X and Y into a torch.DataLoader.

Based on https://stackoverflow.com/questions/44429199/how-to-load-a-list-of-numpy-arrays-to-pytorch-dataset-loader

Args: X (np.ndarray): Embedding vectors of input data (natural language embeddings). Y (np.ndarray): Embedding vectors of output data (BED file embeddings). target (np.ndarray): Vector of 1 and -1, indicating if each vector pair of (X, Y) are target pairs or not. batch_size (int): Size of small batch. shuffle (bool): Shuffle dataset or not.

Returns: DataLoader: A Dataset for pytorch training in format of torch.DataLoader.

metadata_dict_from_csv

def metadata_dict_from_csv(csv_path: str, col_names: Set[str], file_key: str = DEFAULT_FILE_KEY, genomes: Union[Set[str], None] = None, genomes_key: Union[str, None] = DEFAULT_GENOME_KEY, series_key: Union[str, None] = DEFAULT_SERIES_KEY, chunk_size: Union[int, None] = None) -> Dict[str, Union[str, Dict[str, Union[str, List[str]]]]]

Read selected columns from a metadata CSV and return a metadata dictionary.

Can filter genomes with a given list of genomes and the column name of genome.

Args: csv_path (str): Path to the csv file that contain metadata. col_names (Set[str]): Set of csv columns that contain informative metadata. file_key (str): Name of column of file names. genomes (Union[Set[str], None]): Set of genomes. genomes_key (Union[str, None]): Name of column of sample genomes. series_key (Union[str, None]): Name of column of series. chunk_size (Union[int, None]): Size of chunk to read when the csv file is large.

Returns: Dict[str, Union[str, Dict[str, Union[str, List[str]]]]]: A metadata dictionary in one of two formats:

    If series information is in the csv:
    {
        <series>: [
            {
                "name": <file name>,
                "metadata": {
                    <csv column name>: <metadata string>,
                    ...
                }
            },
            ...
        ],
        ...
    }

    Otherwise:
    {
        <file name>: {
            <csv column name>: <metadata string>,
            ...
        },
        ...
    }