{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial on basic topics"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Importing the library\n",
    "At the beginning import the library (it is assumed you have already installed it - see https://neuroinflab.wordpress.com/research/pymice/ for details). The name _`pm`_ will be assigned to the library."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import pymice as pm"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Downloading example IntelliCage data.\n",
    "Before you can start the tutorial you have to have the training data stored in your working directory.\n",
    "\n",
    "The library might do it for you after you call _`getTutorialData()`_ function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "pm.getTutorialData(quiet=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exploring data from an IntelliCage archive.\n",
    "At the beginning load data from one of files to investigate it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "ml = pm.Loader('C57_AB/2012-08-28 15.33.58.zip')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Visits\n",
    "#### Obtaining visit objects\n",
    "The most important piece of data obtained from IntelliCage system are recordings of visits performed by mice to corners. You can obtain list of objects representing all recorded visits with _`.getVisits()`_ method.\n",
    "\n",
    "**WARNING: The visits might be in a random order!**\n",
    "\n",
    "For details on selecting a subset of available visits and on ordering the visits see _\"Tutorial on advanced topics\"_"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "visits = ml.getVisits()\n",
    "print(type(visits))\n",
    "print(len(visits))\n",
    "visit = visits[0]\n",
    "print(type(visit))\n",
    "print(repr(visit))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Visit objects\n",
    "Every _`Visit`_ object contains information about one visit to a corner.\n",
    "\n",
    "The _`.Start`_ and _`.End`_ attributes of the visit object are respectively start and end times of the visit and they are instances of _`datatime.datatime`_ class. The _`.Duration`_ attribute is their derivative (and therefore a _`datatime.timedelta`_ object).\n",
    "\n",
    "The _`.Cage`_ and _`.Corner`_ attributes indicates whhich corner of which cage was visited; they are guaranted to be convertable to _`int`_.\n",
    "\n",
    "Another important attribute is _`.Animal`_ which is an _`Animal`_ object representing the mouse performing the visit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "print(\"visit of %s in cage #%d to corner #%d\" % (visit.Animal, visit.Cage, visit.Corner))\n",
    "print(\"visit duration: %.2fs\" % visit.Duration.total_seconds())\n",
    "print(\"(from %s to %s)\" % (visit.Start, visit.End))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Animals\n",
    "#### Animal objects\n",
    "An _`Animal`_ object represents a mouse housed in the system, which contains basic information about the animal.\n",
    "\n",
    "Names of its _`.Name`_ and _`Sex`_ attributes are self-explanatory (both are instances of _`unicode`_ class). The _`Tag`_ attribute is a set of animal's transponder identificators (containing more than one identificator if mouse's transponder has been changed during the experiment)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "animal = visit.Animal\n",
    "print(type(animal))\n",
    "print(repr(animal))\n",
    "print(animal.Name)\n",
    "print(animal.Sex)\n",
    "print(animal.Tag)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Registered animals\n",
    "You can directly access an _`Animal`_ object associated with any mouse registered in the system with the _`.getAnimal()`_ method. You can also use the method to obtain names of all animals registered in the system."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "animal = ml.getAnimal('C57 A 1')\n",
    "print(repr(animal))\n",
    "print(animal.Name)\n",
    "print(animal.Sex)\n",
    "print()\n",
    "\n",
    "print('All registered mice:')\n",
    "for name in ml.getAnimal():\n",
    "    print(name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Text representation of Animal objects\n",
    "It is also possible to use \"shortcuts\" to access the information."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "print(str(animal))\n",
    "print(str(animal) == animal.Name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Cages\n",
    "#### Animals and cages\n",
    "Animals are housed in cages and with _`.getCage()`_ method you can check in which cage(s) the animal was detected.\n",
    "The cage object is either guaranted to be convertable to an integer or to be a collection of such objects.  \n",
    "You can also check (with _`.getInmates()`_ method) which mice were housed in the cage."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "cage = ml.getCage('C57 A 1')\n",
    "print(int(cage))\n",
    "print()\n",
    "print(\"Mice housed in cage #%d:\" % cage)\n",
    "mice = ml.getInmates(cage)\n",
    "for mouse in mice:\n",
    "    print(mouse)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Available cages\n",
    "The method (_`.getInmates()`_) can be also used to list available cages."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "print(ml.getInmates())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Animal groups\n",
    "Animals might be also assigned to certain groups. To list them (as well to obtaing object containing information about a particular group), use the _`.getGroup()`_ method.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "print(ml.getGroup())\n",
    "group = ml.getGroup('C57 A')\n",
    "print(\"Animals of group %s:\" % group.Name)\n",
    "for mouse in group.Animals:\n",
    "    print(repr(mouse))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exploring nosepoke data\n",
    "If the noseopke data are loaded (see _\"Tutorial on advanced topics\"_ for details), a _`Visit`_ object has a _`.Nosepoke`_ attribute containing tuple of objects representing nosepoke events.\n",
    "\n",
    "**WARNING: The nosepokes might be in a random order.**\n",
    "\n",
    "The _`order`_ parameter of _`.getVisits()`_ method is there **solely for technical purposes of the tutorial** - it enforces the order of visits so the fifth one (of index 4) is always the same."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "visits = ml.getVisits(order=('Start', 'End'))\n",
    "visit = visits[4]\n",
    "print(type(visit.Nosepokes))\n",
    "print(len(visit.Nosepokes))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "_`.Start`_, _`.End`_ and _`.Duration`_ attributes of a _`Nosepoke`_ object are analogous to those of the visit object. _`.Side`_ attribute is guaranted to be convertable to _`int`_. The _`.Visit`_ attribute is the same visit object the nosepoke is assigned to.\n",
    "\n",
    "_`.Door`_ attribute is an auxilary attribute indicating which (left or right) side of the corner was nosepoked.\n",
    "The _`Visit`_ object also provides several auxilary aggregate attributes providing summary of corresponding attributes of its _`Nosepoke`_ objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "visit = visits[4]\n",
    "nosepoke = visit.Nosepokes[1]\n",
    "print(type(nosepoke))\n",
    "print(repr(nosepoke))\n",
    "\n",
    "from datetime import timedelta\n",
    "print(\"nosepoke to side #%d (%s) of the cage #%d\" % (nosepoke.Side, nosepoke.Door, nosepoke.Visit.Cage))\n",
    "print(\"nosepoke duration: %s (from %s to %s)\" % (nosepoke.Duration, nosepoke.Start, nosepoke.End))\n",
    "print(\"licks taken %d, licking time: %s\" % (nosepoke.LickNumber, nosepoke.LickDuration))\n",
    "print(sum(n.LickNumber for n in visit.Nosepokes) == visit.LickNumber)\n",
    "print(sum((n.LickDuration for n in visit.Nosepokes), timedelta(0)) == visit.LickDuration)\n",
    "print(sum((n.LickContactTime for n in visit.Nosepokes), timedelta(0)) == visit.LickContactTime)\n",
    "print(sum((n.Duration for n in visit.Nosepokes), timedelta(0)) == visit.NosepokeDuration)\n",
    "print(nosepoke.Visit is visit)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Combining data from multiple sources\n",
    "There is often many data files recorded from one experiment. To merge them into one object you have to load them first into a _`Loader`_ and then create an object of _`Merger`_ class.\n",
    "\n",
    "To obtain list of files matching 'C57\\_AB/*.zip' pattern you might use the [_`glob`_ module of The Python Standard Library](https://docs.python.org/2/library/glob.html)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import glob\n",
    "dataFiles = glob.glob('C57_AB/*.zip')\n",
    "\n",
    "loaders = [pm.Loader(filename) for filename in dataFiles]\n",
    "mm = pm.Merger(*loaders)\n",
    "n = len(mm.getVisits())\n",
    "print(\"Total number of visits in data: %d\" % n)\n",
    "print(n == sum(len(ml.getVisits()) for ml in loaders))"
   ]
  }
 ],
 "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.5.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}