{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Train \n",
    "The network can be trained using three interfaces:\n",
    "\n",
    "- python, via `das.train.train`\n",
    "- the command-line interface `das train`.\n",
    "- the GUI - see the [GUI tutorial](/tutorials_gui/train)\n",
    "\n",
    "Training will:\n",
    "\n",
    "- load train/val/test data form a dataset\n",
    "- initialize the network\n",
    "- save all parameters for reproducibility\n",
    "- train the network and save the best network to disk\n",
    "- run inference and evaluate the network using the test data.\n",
    "\n",
    "The names of files created during training start with an optional prefix and the time stamp of the start time of training, as in `my-awesome-prefix_20192310_091032`. Typically, three files are created:\n",
    "- `*_params.yaml` - training parameters etc.\n",
    "- `*_model.h5` -  model architecture and weights\n",
    "- `*_results.h5` - predictions and evaluation results for the test set (only created if the training dataset contains a test set)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Training using python\n",
    "Training is done using the `train` function in the `das.train` module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import das.train\n",
    "help(das.train.train)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Calling the `train` function produce fairly verbose logging messages, to help with troubleshooting:\n",
    "\n",
    "- run time parameters\n",
    "- information on the size of the training and validation data\n",
    "- network architecture\n",
    "- training progress (training and validation loss)\n",
    "- after training, a classification report for the test data (if test data exist in the dataset)\n",
    "\n",
    "When done, `train` returns the trained keras model and a parameter dictionary with all arguments required to reproduce the model.\n",
    "\n",
    "To demonstrate the outputs of `train`, the following trains a small network on a small dataset to annotate pulse and sine song from _Drosophila melanogater_. Expected performance (f1-score) is about 75%."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "model, params = das.train.train(model_name='tcn',  # see `das.models` for valid model_names\n",
    "                                data_dir='tutorial_dataset.npy', \n",
    "                                save_dir='res',\n",
    "                                nb_hist=256,\n",
    "                                kernel_size=16,\n",
    "                                nb_filters=16,\n",
    "                                ignore_boundaries=True,\n",
    "                                verbose=1,\n",
    "                                nb_epoch=4,\n",
    "                                log_messages=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Training using command-line scripts\n",
    "The training function `das.train.train` and all its arguments are also accessible from the command line via `das train` for use on the terminal. See [here](/technical/cli#train) for a description of all command-line arguments. The command-line interface is generated with [defopt](https://defopt.readthedocs.io/en/stable/index.html).\n",
    "\n",
    "For instance, training command above can be invoked from the command line:\n",
    "```shell\n",
    "das train --data-dir dat/dmel_single_raw.npy --save-dir res --model-name tcn --kernel-size 16 --nb-filters 16 --nb-hist 512 --nb-epoch 20 -i\n",
    "```\n",
    "\n",
    "Shell scripts are particularly useful if you want to fit the network with with different configurations to optimize [structural parameters](/tutorials/structparams). For instance, this script will fit networks with different numbers of TCN blocks (`nb_conv`) and filters (`nb_filters`):\n",
    "```shell\n",
    "#!/bin/bash\n",
    "conda activate das\n",
    "\n",
    "YSUFFIX=\"pulse\"\n",
    "MODELNAME='tcn'\n",
    "DATADIR='../dat/dmel_single.npy'\n",
    "SAVEDIR=\"res\"\n",
    "\n",
    "NB_HIST=2048\n",
    "KERNEL_SIZE=32\n",
    "NB_FILTERS=32\n",
    "NB_CONV=3\n",
    "\n",
    "for NB_CONV in 2 3 4\n",
    "do\n",
    "    for NB_FILTERS in 16 32 64\n",
    "    do\n",
    "        das train -i --nb-filters $NB_FILTERS --kernel-size $KERNEL_SIZE --nb-conv $NB_CONV --nb-hist $NB_HIST --save-dir $SAVEDIR --y-suffix $YSUFFIX --data-dir $DATADIR --model-name $MODELNAME\n",
    "    done\n",
    "done\n",
    "```\n",
    "\n",
    "A description of all command line arguments can be obtained by typing `das train --help` in a terminal:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!das train --help"
   ]
  }
 ],
 "metadata": {
  "file_extension": ".py",
  "interpreter": {
   "hash": "97e399eb41f39eece155bd3046c19e1bcac896c178036c5a0e917146c5ea4385"
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.11"
  },
  "mimetype": "text/x-python",
  "name": "python",
  "npconvert_exporter": "python",
  "pygments_lexer": "ipython3",
  "version": 3
 },
 "nbformat": 4,
 "nbformat_minor": 4
}