{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "a83b4d22",
   "metadata": {},
   "source": [
    "# Running IDyOM Tutorial\n",
    "\n",
    "This tutorial will walk you through how to run the IDyOM model in py2lispIDyOM. For an overview of the py2lispIDyOM\n",
    "functionality, see the [README](../README.md).\n",
    "\n",
    "Generally speaking, to run the IDyOM model with py2lispIDyOM usually takes three steps:\n",
    "\n",
    "1. Set experiment configuration (paths to input music files and to output experiment log.\n",
    "\n",
    "2. Set model configuration (model parameters,\n",
    "   see  [IDyOM parameters documentation](https://github.com/mtpearce/idyom/wiki/IDyOM-Parameters) for more detail).\n",
    "   \n",
    "3. Run the experiment."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6b47d1c9",
   "metadata": {},
   "source": [
    "In this sample experiment, \n",
    "- we will have the model pretrain on a chinese corpus ('shanx_dataset/') and test the model on the european corpus ('bach_dataset/').\n",
    "\n",
    "- the viewpoints to predict (target viewpoint) and the viewpoints to use in prediction (source viewpoint) are both cpitch and onset.\n",
    "\n",
    "- we will use the ':both' model, and we don't want resampling (i.e., k=1)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a03d19c",
   "metadata": {},
   "source": [
    "## Step-by-Step"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "5ace7c11",
   "metadata": {},
   "outputs": [],
   "source": [
    "#  import relevant modules\n",
    "import py2lispIDyOM as py2lispIDyOM\n",
    "from py2lispIDyOM.run import IDyOMExperiment"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0dd6ec56",
   "metadata": {},
   "source": [
    "### 1. Set experiment configuration:\n",
    "\n",
    "First, we set the IDyOM experiment configurations by providing the relevant paths to the `IDyOMExperiment`.\n",
    "\n",
    "```python3\n",
    "class IDyOMExperiment(test_dataset_path,\n",
    "                      pretrain_dataset_path=None,\n",
    "                      experiment_history_folder_path=None)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "a4dbd422",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "** Putting Test dataset files in experiment history folder. **\n",
      "** Putting Pretraining dataset files in experiment history folder. **\n"
     ]
    }
   ],
   "source": [
    "my_experiment = IDyOMExperiment(test_dataset_path='dataset/bach_dataset/',\n",
    "                                pretrain_dataset_path='dataset/shanx_dataset/')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6cc8cff6",
   "metadata": {},
   "source": [
    "### 2. Set model parameters:\n",
    "\n",
    "Next, we set the model parameters using the `set_parameters` methods.\n",
    "\n",
    "```python3\n",
    "class IDyOMExperiment.set_parameters(target_viewpoints, source_viewpoints,\n",
    "                                     ...)\n",
    "\n",
    "```\n",
    "For a comprehensive list of valid model parameters, see below and also the documentation:\n",
    "\n",
    "Valid parameters are: ['ltmo_order_bound', 'ltmo_mixtures', 'ltmo_update_exclusion', 'ltmo_escape', 'stmo_order_bound', 'stmo_mixtures', 'stmo_update_exclusion', 'stmo_escape', 'detail', 'overwrite', 'separator', 'target_viewpoints', 'source_viewpoints', 'models', 'ltmo', 'ltmo_options', 'stmo', 'stmo_options', 'k', 'resampling_indices', 'basis', 'dp', 'max_links', 'min_links', 'viewpoint_selection_output', 'use_resampling_set_cache', 'use_ltms_cache'\n",
    "\n",
    "For detailed description of the model parameters, please refer to\n",
    "the [IDyOM parameters documentation](https://github.com/mtpearce/idyom/wiki/IDyOM-Parameters).\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "8aeec2cf",
   "metadata": {},
   "outputs": [],
   "source": [
    "my_experiment.set_parameters(target_viewpoints=['cpitch', 'onset'],\n",
    "                             source_viewpoints=['cpitch', 'onset'],\n",
    "                             models=':both',\n",
    "                             k=1,\n",
    "                             detail=3)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "37755817",
   "metadata": {},
   "source": [
    "###  3. Run IDyOM model:\n",
    "\n",
    "To run the IDyOM model, simply call the `IDyOMExperiment.run()` method.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "a21c2816",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "** running lisp script **\n",
      "To load \"clsql\":\n",
      "  Load 1 ASDF system:\n",
      "    clsql\n",
      "; Loading \"clsql\"\n",
      ".\n",
      "To load \"idyom\":\n",
      "  Load 1 ASDF system:\n",
      "    idyom\n",
      "; Loading \"idyom\"\n",
      "...........\n",
      "\n",
      "Inserting data into database: dataset 66052122170523.\n",
      "Inserting data into database: dataset 99052122170523.\n",
      "Written resampling set to /Users/guan/idyom/data/resampling/66052122170523-1.resample.\n",
      "Written PPM* model to /Users/guan/idyom/data/models/cpitch_99052122170523_66052122170523-1:1_melody.ppm.\n",
      "Written PPM* model to /Users/guan/idyom/data/models/onset_99052122170523_66052122170523-1:1_melody.ppm.\n",
      " \n",
      "** Finished! **\n"
     ]
    }
   ],
   "source": [
    "my_experiment.run()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "799a88ae",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "1a90394b",
   "metadata": {},
   "source": [
    "## What happens then?\n",
    "\n",
    "py2lispIDyOM will automatically create a folder\n",
    "(with the timestamp of experiment time as the folder name) logging all data of the current experiment. For details of\n",
    "the experiment log folder, see the Experiment Logger section in [README](README.md).\n",
    "\n",
    "After finish running the model, the model output (a `.dat` file will be saved in the current experiment log folder under\n",
    "'experiment_output_data_folder/').\n",
    "\n",
    "From here on, you can extract the relevant IDyOM outputs or export them in other formats for further analysis.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4d7c626f",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2cd1bb21",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6e004244",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c4075f8f",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fc6f4616",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}