# Text2BedNN Module

<a id="geniml.text2bednn"></a>

<a id="geniml.text2bednn.Vec2VecFNN"></a>

## `Vec2VecFNN`

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

Initialize Vec2VecFNN.

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

### Attributes

- <a id="geniml.text2bednn.Vec2VecFNN.model"></a>**`model`**
- <a id="geniml.text2bednn.Vec2VecFNN.trained"></a>**`trained`**
- <a id="geniml.text2bednn.Vec2VecFNN.optimizer"></a>**`optimizer`**
- <a id="geniml.text2bednn.Vec2VecFNN.loss_fn"></a>**`loss_fn`**
- <a id="geniml.text2bednn.Vec2VecFNN.config"></a>**`config`**
- <a id="geniml.text2bednn.Vec2VecFNN.most_recent_train"></a>**`most_recent_train`**

### Methods

<a id="geniml.text2bednn.Vec2VecFNN.load_from_disk"></a>

#### `load_from_disk`

```python
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).

<a id="geniml.text2bednn.Vec2VecFNN.export"></a>

#### `export`

```python
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.

<a id="geniml.text2bednn.Vec2VecFNN.embedding_to_embedding"></a>

#### `embedding_to_embedding`

```python
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.

<a id="geniml.text2bednn.Vec2VecFNN.compile"></a>

#### `compile`

```python
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.

<a id="geniml.text2bednn.Vec2VecFNN.train"></a>

#### `train`

```python
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, <dim>).
    training_Y (np.ndarray): Embedding vectors of region set with shape (n, <dim>).
    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().

<a id="geniml.text2bednn.Vec2VecFNN.train_one_epoch"></a>

#### `train_one_epoch`

```python
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.

<a id="geniml.text2bednn.Vec2VecFNN.calc_loss"></a>

#### `calc_loss`

```python
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.

<a id="geniml.text2bednn.Vec2VecFNN.plot_training_hist"></a>

#### `plot_training_hist`

```python
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.

<a id="geniml.text2bednn.arrays_to_torch_dataloader"></a>

## `arrays_to_torch_dataloader`

```python
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.

<a id="geniml.text2bednn.metadata_dict_from_csv"></a>

## `metadata_dict_from_csv`

```python
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>,
                ...
            },
            ...
        }