% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/train.R
\name{train_model}
\alias{train_model}
\title{Train neural network on genomic data}
\usage{
train_model(
  model = NULL,
  dataset = NULL,
  dataset_val = NULL,
  train_val_ratio = 0.2,
  run_name = "run_1",
  initial_epoch = 0,
  class_weight = NULL,
  print_scores = TRUE,
  epochs = 10,
  max_queue_size = 100,
  steps_per_epoch = 1000,
  path_checkpoint = NULL,
  path_tensorboard = NULL,
  path_log = NULL,
  save_best_only = NULL,
  save_weights_only = FALSE,
  tb_images = FALSE,
  path_file_log = NULL,
  reset_states = FALSE,
  early_stopping_time = NULL,
  validation_only_after_training = FALSE,
  train_val_split_csv = NULL,
  reduce_lr_on_plateau = TRUE,
  lr_plateau_factor = 0.9,
  patience = 20,
  cooldown = 1,
  model_card = NULL,
  callback_list = NULL,
  train_type = "label_folder",
  path = NULL,
  path_val = NULL,
  batch_size = 64,
  step = NULL,
  shuffle_file_order = TRUE,
  vocabulary = c("a", "c", "g", "t"),
  format = "fasta",
  ambiguous_nuc = "zero",
  seed = c(1234, 4321),
  file_limit = NULL,
  use_coverage = NULL,
  set_learning = NULL,
  proportion_entries = NULL,
  sample_by_file_size = FALSE,
  n_gram = NULL,
  n_gram_stride = 1,
  masked_lm = NULL,
  random_sampling = FALSE,
  add_noise = NULL,
  return_int = FALSE,
  maxlen = NULL,
  reverse_complement = FALSE,
  reverse_complement_encoding = FALSE,
  output_format = "target_right",
  proportion_per_seq = NULL,
  read_data = FALSE,
  use_quality_score = FALSE,
  padding = FALSE,
  concat_seq = NULL,
  target_len = 1,
  skip_amb_nuc = NULL,
  max_samples = NULL,
  added_label_path = NULL,
  add_input_as_seq = NULL,
  target_from_csv = NULL,
  target_split = NULL,
  shuffle_input = TRUE,
  vocabulary_label = NULL,
  delete_used_files = FALSE,
  reshape_xy = NULL,
  return_gen = FALSE
)
}
\arguments{
\item{model}{A keras model.}

\item{dataset}{List of training data holding training samples in RAM instead of using generator. Should be list with two entries called \code{"X"} and \code{"Y"}.}

\item{dataset_val}{List of validation data. Should have two entries called \code{"X"} and \code{"Y"}.}

\item{train_val_ratio}{For generator defines the fraction of batches that will be used for validation (compared to size of training data), i.e. one validation iteration
processes \code{batch_size} \eqn{*} \code{steps_per_epoch} \eqn{*} \code{train_val_ratio} samples. If you use dataset instead of generator and \code{dataset_val} is \code{NULL}, splits \code{dataset}
into train/validation data.}

\item{run_name}{Name of the run. Name will be used to identify output from callbacks. If \code{NULL}, will use date as run name.
If name already present, will add \code{"_2"} to name or \code{"_{x+1}"} if name ends with \verb{_x}, where \code{x} is some integer.}

\item{initial_epoch}{Epoch at which to start training. Note that network
will run for (\code{epochs} - \code{initial_epochs}) rounds and not \code{epochs} rounds.}

\item{class_weight}{List of weights for output. Order should correspond to \code{vocabulary_label}.
You can use \code{\link{get_class_weight}} function to estimate class weights:

\code{class_weights <- get_class_weights(path = path, train_type = train_type)}

If \code{train_type = "label_csv"} you need to add path to csv file:

\code{class_weights <- get_class_weights(path = path, train_type = train_type, csv_path = target_from_csv)}}

\item{print_scores}{Whether to print train/validation scores during training.}

\item{epochs}{Number of iterations.}

\item{max_queue_size}{Maximum size for the generator queue.}

\item{steps_per_epoch}{Number of training batches per epoch.}

\item{path_checkpoint}{Path to checkpoints folder or \code{NULL}. If \code{NULL}, checkpoints don't get stored.}

\item{path_tensorboard}{Path to tensorboard directory or \code{NULL}. If \code{NULL}, training not tracked on tensorboard.}

\item{path_log}{Path to directory to write training scores. File name is \code{run_name} + \code{".csv"}. No output if \code{NULL}.}

\item{save_best_only}{Only save model that improved on some score. Not applied if argument is \code{NULL}. Otherwise must be
list with argument \code{monitor} or \code{save_freq} (can only use one option). \code{moniter} specifies what metric to use.
\code{save_freq}, integer specifying how often to store a checkpoint (in epochs).}

\item{save_weights_only}{Whether to save weights only.}

\item{tb_images}{Whether to show custom images (confusion matrix) in tensorboard "IMAGES" tab.}

\item{path_file_log}{Write name of files used for training to csv file if path is specified.}

\item{reset_states}{Whether to reset hidden states of RNN layer at every new input file and before/after validation.}

\item{early_stopping_time}{Time in seconds after which to stop training.}

\item{validation_only_after_training}{Whether to skip validation during training and only do one validation iteration after training.}

\item{train_val_split_csv}{A csv file specifying train/validation split. csv file should contain one column named \code{"file"} and one column named
\code{"type"}. The \code{"file"} column contains names of fasta/fastq files and \code{"type"} column specifies if file is used for training or validation.
Entries in \code{"type"} must be named \code{"train"} or \code{"val"}, otherwise file will not be used for either. \code{path} and \code{path_val} arguments should be the same.
Not implemented for \code{train_type = "label_folder"}.}

\item{reduce_lr_on_plateau}{Whether to use learning rate scheduler.}

\item{lr_plateau_factor}{Factor of decreasing learning rate when plateau is reached.}

\item{patience}{Number of epochs waiting for decrease in validation loss before reducing learning rate.}

\item{cooldown}{Number of epochs without changing learning rate.}

\item{model_card}{List of arguments for training parameters of training run. Must contain at least an entry \code{path_model_card}, i.e. the
directory where parameters are stored. List can contain additional (optional) arguments, for example
\code{model_card = list(path_model_card = "/path/to/logs", description = "transfer learning with BERT model on virus data", ...)}}

\item{callback_list}{Add additional callbacks to \code{keras::fit} call.}

\item{train_type}{Either \code{"lm"}, \code{"lm_rds"}, \code{"masked_lm"} for language model; \code{"label_header"}, \code{"label_folder"}, \code{"label_csv"}, \code{"label_rds"} for classification or \code{"dummy_gen"}.
\itemize{
\item Language model is trained to predict character(s) in a sequence. \cr
\item \code{"label_header"}/\code{"label_folder"}/\code{"label_csv"} are trained to predict a corresponding class given a sequence as input.
\item If \code{"label_header"}, class will be read from fasta headers.
\item If \code{"label_folder"}, class will be read from folder, i.e. all files in one folder must belong to the same class.
\item If \code{"label_csv"}, targets are read from a csv file. This file should have one column named "file". The targets then correspond to entries in that row (except "file"
column). Example: if we are currently working with a file called "a.fasta" and corresponding label is "label_1", there should be a row in our csv file\tabular{lll}{
   file \tab label_1 \tab label_2 \cr
   "a.fasta" \tab 1 \tab 0 \cr
}


\item If \code{"label_rds"}, generator will iterate over set of .rds files containing each a list of input and target tensors. Not implemented for model
with multiple inputs.
\item If \code{"lm_rds"}, generator will iterate over set of .rds files and will split tensor according to \code{target_len} argument
(targets are last \code{target_len} nucleotides of each sequence).
\item  If \code{"dummy_gen"}, generator creates random data once and repeatedly feeds these to model.
\item  If \code{"masked_lm"}, generator maskes some parts of the input. See \code{masked_lm} argument for details.
}}

\item{path}{Path to training data. If \code{train_type} is \code{label_folder}, should be a vector or list
where each entry corresponds to a class (list elements can be directories and/or individual files). If \code{train_type} is not \code{label_folder},
can be a single directory or file or a list of directories and/or files.}

\item{path_val}{Path to validation data. See \code{path} argument for details.}

\item{batch_size}{Number of samples used for one network update.}

\item{step}{Frequency of sampling steps.}

\item{shuffle_file_order}{Boolean, whether to go through files sequentially or shuffle beforehand.}

\item{vocabulary}{Vector of allowed characters. Characters outside vocabulary get encoded as specified in \code{ambiguous_nuc}.}

\item{format}{File format, \code{"fasta"}, \code{"fastq"}, \code{"rds"} or \code{"fasta.tar.gz"}, \code{"fastq.tar.gz"} for \code{tar.gz} files.}

\item{ambiguous_nuc}{How to handle nucleotides outside vocabulary, either \code{"zero"}, \code{"discard"}, \code{"empirical"} or \code{"equal"}.
\itemize{
\item If \code{"zero"}, input gets encoded as zero vector.
\item If \code{"equal"}, input is repetition of \code{1/length(vocabulary)}.
\item If \code{"discard"}, samples containing nucleotides outside vocabulary get discarded.
\item If \code{"empirical"}, use nucleotide distribution of current file.
}}

\item{seed}{Sets seed for reproducible results.}

\item{file_limit}{Integer or \code{NULL}. If integer, use only specified number of randomly sampled files for training. Ignored if greater than number of files in \code{path}.}

\item{use_coverage}{Integer or \code{NULL}. If not \code{NULL}, use coverage as encoding rather than one-hot encoding and normalize.
Coverage information must be contained in fasta header: there must be a string \code{"cov_n"} in the header, where \code{n} is some integer.}

\item{set_learning}{When you want to assign one label to set of samples. Only implemented for \code{train_type = "label_folder"}.
Input is a list with the following parameters
\itemize{
\item \code{samples_per_target}: how many samples to use for one target.
\item \code{maxlen}: length of one sample.
\item \code{reshape_mode}: \verb{"time_dist", "multi_input"} or \code{"concat"}.
\itemize{
\item
If \code{reshape_mode} is \code{"multi_input"}, generator will produce \code{samples_per_target} separate inputs, each of length \code{maxlen} (model should have
\code{samples_per_target} input layers).
\item If reshape_mode is \code{"time_dist"}, generator will produce a 4D input array. The dimensions correspond to
\verb{(batch_size, samples_per_target, maxlen, length(vocabulary))}.
\item If \code{reshape_mode} is \code{"concat"}, generator will concatenate \code{samples_per_target} sequences
of length \code{maxlen} to one long sequence.
}
\item If \code{reshape_mode} is \code{"concat"}, there is an additional \code{buffer_len}
argument. If \code{buffer_len} is an integer, the subsequences are interspaced with \code{buffer_len} rows. The input length is
(\code{maxlen} \eqn{*} \code{samples_per_target}) + \code{buffer_len} \eqn{*} (\code{samples_per_target} - 1).
}}

\item{proportion_entries}{Proportion of fasta entries to keep. For example, if fasta file has 50 entries and \code{proportion_entries = 0.1},
will randomly select 5 entries.}

\item{sample_by_file_size}{Sample new file weighted by file size (bigger files more likely).}

\item{n_gram}{Integer, encode target not nucleotide wise but combine n nucleotides at once. For example for \verb{n=2, "AA" ->  (1, 0,..., 0),}
\verb{"AC" ->  (0, 1, 0,..., 0), "TT" -> (0,..., 0, 1)}, where the one-hot vectors have length \code{length(vocabulary)^n}.}

\item{n_gram_stride}{Step size for n-gram encoding. For AACCGGTT with \code{n_gram = 4} and \code{n_gram_stride = 2}, generator encodes
\verb{(AACC), (CCGG), (GGTT)}; for \code{n_gram_stride = 4} generator encodes \verb{(AACC), (GGTT)}.}

\item{masked_lm}{If not \code{NULL}, input and target are equal except some parts of the input are masked or random.
Must be list with the following arguments:
\itemize{
\item \code{mask_rate}: Rate of input to mask (rate of input to replace with mask token).
\item \code{random_rate}: Rate of input to set to random token.
\item \code{identity_rate}: Rate of input where sample weights are applied but input and output are identical.
\item \code{include_sw}: Whether to include sample weights.
\item \code{block_len} (optional): Masked/random/identity regions appear in blocks of size \code{block_len}.
}}

\item{random_sampling}{Whether samples should be taken from random positions when using \code{max_samples} argument. If \code{FALSE} random
samples are taken from a consecutive subsequence.}

\item{add_noise}{\code{NULL} or list of arguments. If not \code{NULL}, list must contain the following arguments: \code{noise_type} can be \code{"normal"} or \code{"uniform"};
optional arguments \code{sd} or \code{mean} if noise_type is \code{"normal"} (default is \code{sd=1} and \code{mean=0}) or \verb{min, max} if \code{noise_type} is \code{"uniform"}
(default is \verb{min=0, max=1}).}

\item{return_int}{Whether to return integer encoding or one-hot encoding.}

\item{maxlen}{Length of predictor sequence.}

\item{reverse_complement}{Boolean, for every new file decide randomly to use original data or its reverse complement.}

\item{reverse_complement_encoding}{Whether to use both original sequence and reverse complement as two input sequences.}

\item{output_format}{Determines shape of output tensor for language model.
Either \code{"target_right"}, \code{"target_middle_lstm"}, \code{"target_middle_cnn"} or \code{"wavenet"}.
Assume a sequence \code{"AACCGTA"}. Output correspond as follows
\itemize{
\item \verb{"target_right": X = "AACCGT", Y = "A"}
\item \verb{"target_middle_lstm": X = (X_1 = "AAC", X_2 = "ATG"), Y = "C"} (note reversed order of X_2)
\item \verb{"target_middle_cnn": X = "AACGTA", Y = "C"}
\item \verb{"wavenet": X = "AACCGT", Y = "ACCGTA"}
}}

\item{proportion_per_seq}{Numerical value between 0 and 1. Proportion of sequence to take samples from (use random subsequence).}

\item{read_data}{If \code{TRUE} the first element of output is a list of length 2, each containing one part of paired read. Maxlen should be 2*length of one read.}

\item{use_quality_score}{Whether to use fastq quality scores. If \code{TRUE} input is not one-hot-encoding but corresponds to probabilities.
For example (0.97, 0.01, 0.01, 0.01) instead of (1, 0, 0, 0).}

\item{padding}{Whether to pad sequences too short for one sample with zeros.}

\item{concat_seq}{Character string or \code{NULL}. If not \code{NULL} all entries from file get concatenated to one sequence with \code{concat_seq} string between them.
Example: If 1.entry AACC, 2. entry TTTG and \code{concat_seq = "ZZZ"} this becomes AACCZZZTTTG.}

\item{target_len}{Number of nucleotides to predict at once for language model.}

\item{skip_amb_nuc}{Threshold of ambiguous nucleotides to accept in fasta entry. Complete entry will get discarded otherwise.}

\item{max_samples}{Maximum number of samples to use from one file. If not \code{NULL} and file has more than \code{max_samples} samples, will randomly choose a
subset of \code{max_samples} samples.}

\item{added_label_path}{Path to file with additional input labels. Should be a csv file with one column named "file". Other columns should correspond to labels.}

\item{add_input_as_seq}{Boolean vector specifying for each entry in \code{added_label_path} if rows from csv should be encoded as a sequence or used directly.
If a row in your csv file is a sequence this should be \code{TRUE}. For example you may want to add another sequence, say ACCGT. Then this would correspond to 1,2,2,3,4 in
csv file (if vocabulary = c("A", "C", "G", "T")).  If \code{add_input_as_seq} is \code{TRUE}, 12234 gets one-hot encoded, so added input is a 3D tensor.  If \code{add_input_as_seq} is
\code{FALSE} this will feed network just raw data (a 2D tensor).}

\item{target_from_csv}{Path to csv file with target mapping. One column should be called "file" and other entries in row are the targets.}

\item{target_split}{If target gets read from csv file, list of names to divide target tensor into list of tensors.
Example: if csv file has header names \verb{"file", "label_1", "label_2", "label_3"} and \code{target_split = list(c("label_1", "label_2"), "label_3")},
this will divide target matrix to list of length 2, where the first element contains columns named \code{"label_1"} and \code{"label_2"} and the
second entry contains the column named \code{"label_3"}.}

\item{shuffle_input}{Whether to shuffle entries in file.}

\item{vocabulary_label}{Character vector of possible targets. Targets outside \code{vocabulary_label} will get discarded if
\code{train_type = "label_header"}.}

\item{delete_used_files}{Whether to delete file once used. Only applies for rds files.}

\item{reshape_xy}{Can be a list of functions to apply to input and/or target. List elements (containing the reshape functions)
must be called x for input or y for target and each have arguments called x and y. For example:
\code{reshape_xy = list(x = function(x, y) {return(x+1)}, y = function(x, y) {return(x+y)})} .
For rds generator needs to have an additional argument called sw.}

\item{return_gen}{Whether to return the train and validation generators (instead of training).}
}
\value{
A list of training metrics.
}
\description{
Train a neural network on genomic data. Data can be fasta/fastq files, rds files or a prepared data set.
If the data is given as collection of fasta, fastq or rds files, function will create a data generator that extracts training and validation batches
from files. Function includes several options to determine the sampling strategy of the generator and preprocessing of the data.
Training progress can be visualized in tensorboard. Model weights can be stored during training using checkpoints.
}
\examples{
\dontshow{if (reticulate::py_module_available("tensorflow")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
# create dummy data
path_train_1 <- tempfile()
path_train_2 <- tempfile()
path_val_1 <- tempfile()
path_val_2 <- tempfile()

for (current_path in c(path_train_1, path_train_2,
                       path_val_1, path_val_2)) {
  dir.create(current_path)
  create_dummy_data(file_path = current_path,
                    num_files = 3,
                    seq_length = 10,
                    num_seq = 5,
                    vocabulary = c("a", "c", "g", "t"))
}

# create model
model <- create_model_lstm_cnn(layer_lstm = 8, layer_dense = 2, maxlen = 5)

# train model
hist <- train_model(train_type = "label_folder",
                    model = model,
                    path = c(path_train_1, path_train_2),
                    path_val = c(path_val_1, path_val_2),
                    batch_size = 8,
                    epochs = 3,
                    steps_per_epoch = 6,
                    step = 5,
                    format = "fasta",
                    vocabulary_label = c("label_1", "label_2"))
 
\dontshow{\}) # examplesIf}
}