examples/data_domain_api_intro.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import datetime\n",
    "\n",
    "from btgym import BTgymEnv, BTgymDataset\n",
    "from btgym.datafeed import BTgymRandomDataDomain, BTgymSequentialDataDomain\n",
    "\n",
    "from logbook import WARNING, INFO, DEBUG"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- BTGym data is basically discrete timeflow of equitype records. For the sake of\n",
    "defining episodic MDP over such data and setting formal problem objective it should\n",
    "be somehow structured. \n",
    "\n",
    "- This notebook is brief introduction to API realisation of formal definitions introduced in Section 1 (Data) from   this draft: https://github.com/Kismuz/btgym/blob/master/docs/papers/btgym_formalism_draft.pdf\n",
    "- objects described here can be thought as nested data containers with bult-in properties like sampling and         splitting data to train and test subsets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Make data domain - top-level data structure:\n",
    "domain = BTgymRandomDataDomain(\n",
    "    filename='../examples/data/DAT_ASCII_EURUSD_M1_2016.csv',\n",
    "    target_period={'days': 29, 'hours': 0, 'minutes': 0},\n",
    "    trial_params=dict(\n",
    "        start_weekdays={0, 1, 2, 3, 4, 5, 6},\n",
    "        sample_duration={'days': 10, 'hours': 0, 'minutes': 0},\n",
    "        start_00=True,\n",
    "        time_gap={'days': 5, 'hours': 0},\n",
    "        test_period={'days': 2, 'hours': 0, 'minutes': 0},\n",
    "    ),\n",
    "    episode_params=dict(\n",
    "        start_weekdays={0, 1, 2, 3, 4, 5, 6},\n",
    "        sample_duration={'days': 0, 'hours': 23, 'minutes': 55},\n",
    "        start_00=False,\n",
    "        time_gap={'days': 0, 'hours': 10},\n",
    "    ),\n",
    "    log_level=INFO, # Set to DEBUG to see more output\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here Domain instanse is defined such as:\n",
    "- Holds one yera of 1min bars data;\n",
    "- Splits data to source and target domains, target domain data gets last 29 days of year period;\n",
    "- Defines each Trial to consist of 8 days of train and following 2 days of test data;\n",
    "- Each Episode lasts maximum 23:55."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Manually perfom sampling cycle:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Prepare domain, it's essential for stateful classes such as BTgymSequentialDataDomain:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "domain.reset()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Sample trial from source domain:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "trial= domain.sample(sample_type=0)\n",
    "trial.reset()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Trials can be sampled from `Source` or `Target` domains by passing kwarg `sample_type` to `reset()`         method. 0 is for `source` and 1 is for `target` and later are conventional names for train ans test data.\n",
    "- If target period duration is set to 0:0:0, trying to get target sample will rise an exeption.\n",
    "- Note that during real BTgym operation domain instance is held by `btgym_data_server`;\n",
    "\n",
    "- Different Trial samples are sent to every environment instance, so corresponding `btgym_server` can sample           multiple episodes until agent decides to request another trial via Gym API by calling env.reset() \n",
    "  with kwarg `new_trial`=True.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Sample episode from trial test interval:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "episode = trial.sample(sample_type=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Episodes can be sampled from Trial `train` or `test` subsets, just like Trials from Source/Target domains e.g:       \n",
    "    - env.reset(new_trial=False, sample_type=1) will ask for test episode from same trial;\n",
    "    \n",
    "    - env.reset(new_trial=True, sample_type=0) asks for train episode from new trial (... means requset is passed from API shell to `btgym_server` wich itself request new episode from `data_server` and than samples episode from freshly obtained trial).\n",
    "    \n",
    "        \n",
    "- To be implemented soon: pass kwargs `b_alpha` and `b_beta` to get skewed train data sampling."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Now print whole path:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "print('Got instance of: {}\\nholding data: {}\\nmetadata: {}'.\n",
    "      format(type(domain), domain.filename, domain.metadata))\n",
    "\n",
    "print('  |\\nsample()\\n  |')\n",
    "\n",
    "print('got instance of: {}\\nholding data: {}\\nmetadata: {}'.\n",
    "      format(type(trial), trial.filename, trial.metadata))\n",
    "\n",
    "print('  |\\nsample()\\n  |')\n",
    "\n",
    "print('got instance of: {}\\nholding data: {}\\nmetadata: {}'.\n",
    "      format(type(episode), episode.filename, episode.metadata))\n",
    "\n",
    "print('  |\\nto_btfeed()\\n  |')\n",
    "\n",
    "print('got instance of: {},\\n...wich ready to be fed to bt.Cerebro'.format(type(episode.to_btfeed())))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Note:\n",
    "- BTgymDataSet class used in most examples is simply special case where we set Trial=Episode by definition.\n",
    "- This nested data structure is intended mostly for upcoming implementation of meta-learning and guided-policy-search algorithms.\n",
    "- using kwargs in .reset() method is Gym API extension. Nevermind."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "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.6.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}