example3.texw

In this example, we analyze results of a place preference experiment
described in detail in~\cite{Puscian:2014cu}. Similarly as in Example 2,
the experiment comprised several adaptation and learning phases, in
which the mice could access either all or just selected drinking bottles.
In the nosepoke adaptation phase (\emph{NPA}), all the mice had access to tap water in all corners. In order to obtain water, the mice were required to open the door by performing a nosepoke.
Next, in the place preference learning phase (\emph{Place Pref}), the access
to the drinking bottles was (as in the previous example) restricted to just one corner for each mouse.
Tap water was replaced with 10\% sucrose solution to increase the motivation of the mice
to seek access to the drinking bottles.  We are interested in how the percentage of visits to the
rewarded corner changed over time.

The data used here are a subset of data presented in~\cite{Puscian:2014cu},
and in the final figure obtained in this example (\fig{figurePlotReplication})
we show two learning curves
from Fig.~3A in~\cite{Puscian:2014cu} (cohorts A and B).
Each curve represents an average performance (defined as a fraction
of visits to the rewarded corner) of a cohort of mice in eight subsequent,
12-h-long phases of the experiment.

As the code here is quite similar to the code of the previous
example, we will focus on the major differences between the examples.
We start by loading the \code{data}, \code{timeline}
and \code{PHASES} objects from the relevant  dataset (different than in Example 2;
code omitted here, the full code is available
at \url{https://github.com/Neuroinflab/PyMICE_SM/blob/examples/example3.py}).

<<echo=False, results='hidden'>>=
import warnings
warnings.simplefilter("ignore")

import numpy as np
import matplotlib.pyplot as plt
import matplotlib.ticker as mtick
import matplotlib.dates as mpd
import pytz

import pymice as pm

data = pm.Loader('C57_AB/2012-08-31 11.58.22.zip')
timeline = pm.Timeline('C57_AB/timeline.ini')

PHASES = ['NPA 2 dark', 'NPA 2 light',
          'Place Pref 1 dark', 'Place Pref 1 light',
          'Place Pref 2 dark', 'Place Pref 2 light',
          'Place Pref 3 dark', 'Place Pref 3 light']
@

As in the previous example, we define a function returning a performance
matrix (defined here as the fraction of visits to the rewarded corner):
\code{getGroupPerformanceMatrix()}.

\begin{samepage}
<<echo=True, results='hidden'>>=
def getGroupPerformanceMatrix(groupName):
    group = data.getGroup(groupName)
    return [getPerformanceCurve(mouse) for mouse in group.Animals]
@
\end{samepage}

Unlike in the previous example, the matrix here is limited to only one group of
mice. The group is defined in the IntelliCage experiment design.
Information about its members is contained in a \code{Group} object, which
we request in the first line of the function.

The \code{getPerformance()} and \code{calculatePerformance()}
functions are simpler than in the previous example, as neither filtering of visits
 nor extracting
of nosepokes is necessary.

<<echo=False, results='hidden'>>=
def getPerformanceCurve(mouse):
    return [getPerformance(mouse, phase) for phase in PHASES]
@

\begin{samepage}
<<echo=True, results='hidden'>>=
def getPerformance(mouse, phase):
    start, end = timeline.getTimeBounds(phase)
    visits = data.getVisits(mice=[mouse], start=start, end=end)
    return  calculatePerformance(visits)

def calculatePerformance(visits):
    successes = [isToCorrectCorner(v) for v in visits]
    return successRatio(successes)
@
\end{samepage}

To calculate the performance of a mouse during a phase, we check
-- for each visit -- whether the visit was to the rewarded corner.
In the IntelliCage experiment design, the rewarded corner was marked as
`correct'. Visits to the `correct' corner have positive value of the
\code{.CornerCondition} attribute of the \code{Visit} object.

<<echo=False, results='hidden'>>=
def isToCorrectCorner(visit):
    return visit.CornerCondition > 0

def successRatio(successes):
    return np.mean(successes)
@

With all the functions defined, we obtain a
performance matrix and plot it averaged across mice (\fig{figurePlotReplication})
for each cohort (groups C57A and C57B) separately. Note that analyzing
several cohorts reduces to a loop over the cohorts included in the
analysis.


<<echo=False,results='hidden'>>=
def getTimeBounds(phases):
    return mpd.date2num(timeline.getTimeBounds(phases))

class DecoratedAxes(object):
    yticks = range(0, 80, 10)

    def __enter__(self):
        self.init()
        return self.__ax

    def init(self):
        fig, ax = plt.subplots(figsize=(13, 8))

        ax.set_title('C57BL/6 - PLACE PREFERENCE LEARNING')

        self.__ax = ax
        self.__fig = fig
        self.__setUpAxisY()
        self.__setUpAxisX()
        self.__plotDarkPhasesInBackground()
        self.__plotPercentReferenceLines()

        ax.plotGroupAverages = plotGroupAverages.__get__(ax, ax.__class__)

    def __setUpAxisY(self):
        self.__ax.set_ylabel('% of visits to sugar corner')
        self.__ax.set_ylim(min(self.yticks), max(self.yticks))
        self.__ax.yaxis.set_ticks_position('none')
        self.__ax.yaxis.set_major_formatter(mtick.FormatStrFormatter("%.0f%%"))
        self.__ax.set_yticks(self.yticks)

    def __setUpAxisX(self):
        tzone = pytz.timezone('CET')
        hours=[7, 19]

        self.__ax.set_xlabel('experiment phase')
        self.__ax.set_xlim(getTimeBounds(PHASES))
        self.__ax.xaxis.set_major_locator(mpd.HourLocator(np.array(hours),tz=tzone))
        self.__ax.xaxis.set_ticks_position('none')
        self.__ax.xaxis.set_major_formatter(timeline)

    def __plotPercentReferenceLines(self):
        for y in self.yticks:
            self.__ax.axhline(y, color='#A0A0A0', lw=1)

    def __plotDarkPhasesInBackground(self):
        for phase in PHASES:
            if phase.endswith('dark'):
                start, end = getTimeBounds(phase)
                self.__ax.axvspan(start, end, color='#E0E0E0')

    def __exit__(self, type, value, traceback):
        self.finish()

    def finish(self):
        self.__ax.legend(loc='lower right')
        self.__ax.autoscale_view()
        self.__fig.autofmt_xdate()
        plt.show()

def getPhaseMidtime(phase):
    return getTimeBounds(phase).mean()

def getSem(X):
    return X.std(axis=0) / np.sqrt(np.logical_not(X.mask).sum(axis=0))

GRUOP_COLORS = {'C57 A': '#00c0ff',
                'C57 B': '#00aa00'}

# Although it is a good practice to plot error bars as confidence
# intervals instead of SEM\cite{Cumming2014newStat} we decided to
# reproduce the original plot as close as possible.
def plotGroupAverages(ax, series, group):
    masked = np.ma.masked_invalid(series)
    mean = masked.mean(axis=0)
    sem = getSem(masked)
    midpoints = [getPhaseMidtime(phase) for phase in PHASES]
    color = GRUOP_COLORS[group]
    ax.errorbar(midpoints, mean * 100, yerr=sem * 100,
                linewidth=3, elinewidth=2,
                marker='o', markeredgecolor=color,
                markersize=10,
                ecolor="black",
                color=color, linestyle='--',
                dash_capstyle='round',
                label=group,
                alpha=0.69)
@
<<echo=True,term=True,fig=True,include=False,name='Figure'>>=
with DecoratedAxes() as ax:
    for group in ['C57 A', 'C57 B']:
        performance = getGroupPerformanceMatrix(group)
        ax.plotGroupAverages(performance, group)
@

\begin{figure*}
  \includegraphics[width=0.75\textwidth]{figures/example3_Figure_1.pdf}
  \caption{
    {\bf  Place preference learning of two cohorts of C57BL\/6 mice in
    an IntelliCage experiment.}
    The plot presents the cohort-averaged percentage of visits
    to a rewarded corner during consecutive phases, each lasting 12 h.
    During the place preference phases (Place Pref),
    each mouse is provided access to sweetened water
    in one selected corner of the IntelliCage. The fraction of visits to that
    corner is close to the chance level (25\%) during
    the NPA (nosepoke adaptation) phases when
    mice are provided access to plain water in all corners, and
    increases over time after the reward (sweetened water) is introduced.
    Error bars are standard error of the mean.
  }
  \label{figurePlotReplication}
\end{figure*}