PyMICE: APython library for analysis of IntelliCage data
PyMICE: A Python library for analysis of IntelliCage data
Jakub M. Dzik 0 1 2
Alicja Pus´cian 0 1 2
Zofia Mijakowska 0 1 2
Kasia Radwanska 0 1 2
Szymon Łe˛ski 0 1 2
0 Department of Molecular and Cellular Neurobiology Laboratory of Molecular Basis of Behavior, Nencki Institute of Experimental Biology of Polish Academy of Sciences , Poland 3 Pasteur Str., Warsaw, 02-093 Poland
1 Department of Neurophysiology Laboratory of Emotions Neurobiology, Nencki Institute of Experimental Biology of Polish Academy of Sciences , Poland 3 Pasteur Str., Warsaw, 02-093 Poland
2 Department of Neurophysiology Laboratory of Neuroinformatics, Nencki Institute of Experimental Biology of Polish Academy of Sciences , Poland 3 Pasteur Str., Warsaw, 02-093 Poland
IntelliCage is an automated system for recording the behavior of a group of mice housed together. It produces rich, detailed behavioral data calling for new methods and software for their analysis. Here we present PyMICE, a free and open-source library for analysis of IntelliCage data in the Python programming language. We describe the design and demonstrate the use of the library through a series of examples. PyMICE provides easy and intuitive access to IntelliCage data, and thus facilitates the possibility of using numerous other Python scientific libraries to form a complete data analysis workflow.
Python; Library; Mice; Behavior; Analysis; IntelliCage
In recent years, a number of automated environments for
behavioral testing have been developed, based on RFID
(Dell’omo, Shore, & Lipp, 1998; Galsworthy et al., 2005;
Daan et al., 2011; Pus´cian et al., 2016)
or video tracking of
(de Chaumont et al., 2012; Weissbrod et al., 2013;
Shemesh et al., 2013; Pérez-Escudero, Vicente-Page, Hinz,
Arganda, & de Polavieja, 2014)
. Such automated systems
have many advantages compared to the traditional
behavioral tests, such as the reduction of the animal stress caused
by isolation and handling
(Heinrichs & Koob, 2006; Sorge
et al., 2014)
, the possibility of studying social interactions
in group-housed animals (Kiryk et al., 2011), the possibility
of long-term studies, and easier standardization of
protocols in turn leading to better reproducibility of results
(Crabbe, Wahlsten, & Dudek, 1999;
Chesler, Wilson, Lariviere, Rodriguez-Zas, & Mogil, 2002;
Krackow et al., 2010; Codita et al., 2012; Morrison, 2014;
Vannoni et al., 2014)
The system we are particularly interested in is the
(NewBehavior A G, 2011; Kiryk et al.,
2011; Radwan´ska & Kaczmarek, 2012; Pus´cian et al., 2014;
Mijakowska et al., 2017)
(see Fig. 1), which is increasingly
popular in behavioral research on rodents (TSE Systems
International Group, 2016).
The system outputs a large amount of data describing the
behavior of the mice in the conditioning corners of the cage.
A typical experiment yields 10,000–100,000 visits recorded
during several weeks or months. Such large data call for
development of data analysis methods and software. One
way to address the need of data analysis is to develop a
dedicated application, preferably with a graphical user interface
(GUI), which would allow researchers to inspect the data
and extract relevant quantities interactively. In fact, such an
application, called Analyzer, is provided with the IntelliCage
system. While an interactive GUI-based program for data
analysis may be useful, it does have certain limitations. In
the context of scientific research, perhaps the most severe
limitation is poor reproducibility of the analysis, unless
strict measures are taken to record every single action of the
user. Moreover, there is usually no automated way to
perform exactly the same analysis on a different dataset, and
repeating the analysis manually is very time-consuming and
highly error-prone. Another inconvenience of ready-made
programs is that they are typically limited to a predefined
set of analysis methods, and not easily extendable.
Custom data analysis programs (e.g., scripts) fall at
the opposite end of the spectrum than GUI programs.
First, the most obvious advantage of such programs is the
essentially unlimited possibility of implementing
specialized analysis methods and applying them much better (in
terms of calculation speed, precision and robustness) than
Second, a noninteractive program (written in any
programming language) running in batch mode is, by definition
(Hoare, 1969; Turing, 1937; Floyd, 1967; McCarthy, 1963)
an exhaustive specification of the analysis. In contrast, a
plain language description usually included in a Methods
section of a journal article may be ambiguous or not
upto-date. The voices calling for providing the data analysis
workflows together with journal publications date at least
two decades back (Buckheit & Donoho, 1995): ‘an
article about computational science in a scientific publication
is not the scholarship itself, it is merely advertising of the
scholarship. The actual scholarship is the complete software
development environment and the complete set of
instructions which generated the figures’.
Finally, one of the advantages of using an automated
behavioral setup is the possibility of high-throughput
screening by running the same protocol for a number of
mice cohorts (for example treatment and control groups
and/or different strains of mice
(Pus´cian et al., 2014)
Manual processing of each dataset separately is both tedious
and prone to errors. Batch-processing using a data
analysis script is an obvious remedy, as it allows for repetition of
exactly the same steps of analysis.
The only drawback is that the entry threshold for data
analysis using a programming language is much higher, as
significant effort is required to learn the programming
language and necessary technical details (e.g., the data format).
Our goal here is to lower this threshold by providing an easy
and intuitive way to access the IntelliCage data in the Python
(van Rossum, 1995)
This paper is organized as follows: first, we briefly
describe the IntelliCage system. Next, we introduce
PyMICE through a series of examples and provide pointers
to further documentation. We conclude with a short section
on technical details and a discussion.
IntelliCage (Fig. 1) is an automated, computer-controlled
RFID system for (possibly long-term) monitoring of groups
(Galsworthy et al., 2005; Krackow et al., 2010;
Pus´cian et al., 2014)
. The mice are housed in one or more
polycarbonate cages (of size 55 × 37.5 × 20.5 cm; Fig. 1A,
B). A cage can house a group of up to 16 mice. Each mouse
is tagged with an RFID transponder.
The key components of the system are learning
chambers (Fig. 1c, C, D) located in the corners of cages (for
brevity, we will refer to the chambers simply as ‘corners’).
Each corner can be accessed through a circular opening
(30 mm in diameter; Fig. 1a), with an embedded RFID
antenna. By design, only one mouse at a time can enter a
corner. Each corner contains two smaller (13 mm in
diameter; Fig. 1d) openings, through which a mouse can access
different drinking bottles (Fig. 1b). The access to the
drinking bottles is controlled using programmable doors in the
A broad range of different experiment protocols can be
implemented in the IntelliCage
(Knapska et al., 2006; Kiryk
et al., 2011; Endo et al., 2011; Radwan´ska & Kaczmarek,
2012; Knapska et al., 2013; Smutek et al., 2014; Pus´cian
et al., 2014; Vannoni et al., 2014)
. The system can be
programmed to open the doors on specific conditions, for
instance, if a specific mouse enters the corner or if a specific
nosepoke pattern is performed. Also, an air puff in the back
may be delivered to the mouse as a punishment.
The IntelliCage system records the visits of each mouse
to a particular corner and also tracks the nosepokes—which
lead to accessing the drinking bottles. When the mouse
drinks from a bottle, the number of licks taken is also
recorded. The events (visits and nosepokes) registered by
the system are stored on a computer as a series of records.
Each visit record contains, for example, the RFID
transponder number of a given mouse, the cage and corner, and the
time bounds of the visit. Further, nosepokes during the visit
are also stored, along with time boundaries and the number
of licks recorded, etc.
The system periodically logs the environmental
conditions (ambient illumination and temperature) in every cage
connected. It also logs other relevant events, such as: starts
or ends of recording, errors, warnings, and hardware events
(e.g., concerning state of the doors).
The IntelliCage system enables researchers to use
sophisticated experimental protocols and thus explore behavioral
phenomena inaccessible in classic, non-automated
behavioral tests. However, in many cases, the analysis of data from
such experiments poses a serious challenge. First, in some
instances, manual analysis performed in the manufacturer’s
software (Analyzer) would simply take too much time.
For instance, analyzing data from experiments in which
one is interested in a particular time frame with respect
to a stimulus presented in the corner would be extremely
time-consuming. If, for example, the availability of a reward
is signaled by LEDs in a corner, and the diodes are only
lit up in a specific time frame, then one would be
naturally interested in, say, number of nosepokes performed
before, during, and after the visual stimulus. Such
information cannot be extracted from Analyzer in an automated
way, and therefore the researcher would have to inspect each
of the hundreds or thousands of visits manually. Another
case in which it is hard to obtain the relevant data directly
from Analyzer are protocols assessing impulsiveness of
individual subjects by employing progressive ratio of
behaviors (e.g. nosepokes) needed to obtain a reward. On the
other hand, such protocols are useful for modeling
symptoms of e.g. addiction
(Radwan´ska & Kaczmarek, 2012;
Mijakowska et al., 2017)
A solution to this problem is to write custom software for
automated data analysis. PyMICE is a free and open-source
library that makes it easier to access and analyze IntelliCage
data in the Python programming language.
Moreover, PyMICE is more suitable than the Analyzer
software when it comes to the analysis of more
sophisticated experimental designs
(Endo et al., 2011; Knapska
et al., 2013)
. Namely, it allows for the comprehensive
analysis of variables than may not be computed in Analyzer.
Publication of Knapska et al. from 2013 is an example of
how highly specified behavioral assessment—in this case
choosing between nosepoking to reward vs. to a neutral
stimulus, performed right after entering a corner—might be
implemented to identify neuronal circuits underlying
specific cognitive deficits. The analysis in that paper was done
manually, which required substantial effort. PyMICE
facilitates drawing such conclusions by enabling experimenters
with an easy access to highly specific parameters describing
subjects’ behavioral performance.
For those reasons, we argue that PyMICE is a convenient
solution to otherwise time-consuming data analysis and—
more importantly—a valuable tool for in-depth analysis of
previously inaccessible elements of murine behavior.
One of the advantages of using the Python
programming language is that a well-written Python program is
readable to users. In fact, readability is stressed as one of
the core Python principles
, which we have
strived to follow in the design of PyMICE. Our library
provides IntelliCage data as a collection of intuitively designed
data structures (Fig. 2; Table 1), mirroring records
written by the IntelliCage control software: most of the record
fields are represented by attributes of the same or
corresponding name. Also, auxiliary properties are provided,
such as the .Door property of a Nosepoke object (see
Fig. 2) translating integer value of the .Side attribute
to 'left' and 'right' text strings. Manipulating such
structures is straightforward and natural, therefore shifting
the programmer’s focus from technical details of the file
Fig. 2 Visualization of PyMICE data structures. To investigate visit
events recorded by the IntelliCage system, a list of Visit
structures is obtained from the data object by the first command (top
right panel). To focus on a third visit, the next command selects its
item of index 2 (pale blue). To check the name of the mouse
performing the visit, the third command accesses the .Animal attribute of
the visit (pale red). The attribute is an Animal structure and the
next command prints its .Name attribute (yellow). To further
investigate which door was nosepoked during the visit, the .Nosepokes
attribute (a tuple) must be accessed. The fifth command selects the
first item (i.e., index 0) of the tuple, which is a Nosepoke structure
(pink). The last command prints its .Door property (pale green)
format to the data analysis itself. The data structures are
read-only objects,1 which supports the functional
PyMICE operates on ZIP archives saved by the
IntelliCage software controlling the experiment. Data from
several recording sessions may be easily merged and
analyzed together. All visits and nosepokes present in the raw
data are loaded and presented to the user without any
implicit filtering. Note that in some cases this leads to
different results than those obtained with the Analyzer
software bundled with the IntelliCage. One specific case we
are aware of is that Analyzer (v. 188.8.131.52) omits some of
the nosepokes present in the raw data, leading to
potentially significant underestimation of the measured quantities
(the worst case in the data we analyzed was 480 licks of a
single mouse missing within a 6-h-long period of a liquid
consumption study—31% of the total recorded number).
The PyMICE library also facilitates automatic
validation of the loaded data. A collection of auxiliary classes
is provided for that purpose. Currently, possible RFID and
lickometer failures may be detected automatically. Such
events are reported in the IntelliCage logs, respectively,
as Presence Errors and Lickometer Warnings. The set of
detectable abnormal situations may be easily extended.
In this section, we introduce PyMICE through a series of
examples illustrating various aspects of the library.
1The two exceptions are: the Animal semi-mutable class (the .Sex
attribute might be updated if None; the .Notes attribute might be
extended) and the Group mutable class.
In Example 1 we show how to find numbers of visits of
a specific mouse in which the first nosepoke was performed
to either the left side or the right side of the corner. This can
be achieved in PyMICE in just six lines of code.
Example 2 is an extension of Example 1 to analysis of
actual experimental data, obtained with a protocol described
Knapska et al. (2013)
. In this example, we also present a
convention for defining the timeline of the experiment.
In Example 3 we reproduce a plot from an earlier paper
(Pus´cian et al., 2014)
. The plot shows how two cohorts of
mice learn the location of the reward over time (place
preference learning). This kind of analysis can be performed using
Analyzer, the GUI application provided with IntelliCage;
however, using PyMICE we can quickly repeat the analysis
for new cohorts with minimal effort.
Example 4 illustrates how the Python programming
language can be used to extend the repertoire of data analysis
methods. In this example we show how to extract the
information about intervals between visits of different mice to the
same corner. This kind of information would be very hard
(or even impossible) to obtain using Analyzer.
To improve readability of Examples 2–4, we have
omitted some generic code and focused on PyMICE-specific
snippets. Full code of the examples is provided as online
supplementary material at https://github.com/Neuroinflab/
Before the examples can be run, the example data have to
be saved to the current working directory. This can be done
from within PyMICE:
>>> import pymice as pm
In addition to the examples presented here, we have
prepared several tutorials available online at the PyMICE
The data structures represent particular records written by the IntelliCage control software. Most fields are represented by attributes of the same
or corresponding name
(Dzik and Łe˛ski, 2017b)
. The tutorials are in the
Jupyter Notebook (Project Jupyter, 2015) format and may
be downloaded for interactive use. The examples and the
tutorials are provided as a hands-on introduction to PyMICE
and serve as a starting point for further exploration.
Additionally, online documentation is provided
(Dzik & Łe˛ski,
. PyMICE objects and their methods are also
documented with docstrings available with Python built in
Example 1: minimal example—extracting the side of the first nosepokes in six lines of code
This example shows how to obtain the number of visits in
which a mouse performed the first nosepoke to the left side
or the right side of the corner.
In the first line, the library is imported. We use pm as
an abbreviated name of the library. In the second line, the
example data are loaded from a single IntelliCage file. In
the third line, a list of all visits of a mouse named ‘Jerry’
is obtained.2 Note that a list of names is passed as an
Next, the first nosepoke is selected from every visit
v (if any nosepoke was made during that visit). Note
that the condition if v.Nosepokes is met if the list
v.Nosepokes is not empty.
The side the mouse poked is obtained as nosepoke.
Door in the fifth line of the code. This returns either
'left' or 'right', thus disregarding the information
about the corner in which the nosepoke was performed.
Finally, in the last line, the number of visits with the
first nosepoke to the left and the right side is calculated and
2The mice are referred to by names defined in the design of IntelliCage
experiment, not by the RFID tag numbers.
>>> import pymice as pm
>>> data = pm.Loader('demo.zip')
>>> visits = data.getVisits(mice=['Jerry'])
>>> firstNps = [v.Nosepokes
... for v in visits if v.Nosepokes]
>>> sides = [nosepoke.Door
... for nosepoke in firstNps]
>>> print ( sides.count('left'),
Example 2: full analysis example—side discrimination task
The previous example is a simplified version of an analysis
performed to assess place memory during the
discrimination training, as described in
Knapska et al. (2013)
. In this
example, we present the analysis in more detail,
including the estimation of how the mice performance in the
discrimination task changed over time.
The experimental setup was the following: during the
first several days of the experiment, the mice were adapted
to the cage. In this phase, water was freely available in
all corners, at both sides of each corner, and the doors to
the bottles were open. Next, in nosepoke adaptation (NPA)
phase of the experiment, mice had to perform nosepokes to
access the water bottles. The next phase was place
preference learning (PP). In this phase, every mouse could access
bottles in one corner only. The mice were assigned to
different corners as evenly as possible to prevent crowding and
learning interference. The final experimental phase was the
discrimination task (DISC). In this phase, the mice were
presented with two bottles in the same corner to which they
were assigned during the PP phase. However, in contrast to
the PP phase, one bottle contained tap water, and the other
contained 10% sucrose solution (highly motivating reward).
As previously, during each visit the access was granted to
both bottles. The percentage of visits in which the first
nosepoke was performed to the bottle containing reward was
calculated as a measure of memory.
We start by loading the data. Note that some
technical details not crucial for understanding the example (like
importing the libraries) are hidden. The full code is
available at https://github.com/Neuroinflab/PyMICE_SM/blob/
data = pm.Loader('FVB/2016-07-20 10.11.11.zip')
Next, we need to know the start- and end-points of the
experimental phases we are interested in. We defined these
phases in an experiment timeline file. The format of this file
is a derivative of the INI format. The necessary information
required about a phase are: its name (PP dark in the
following example), boundaries (start and end properties) and
timezone of the boundaries (tzinfo property):
start = 2016-07-20 12:00
end = 2016-07-21 00:00
tzinfo = Etc/GMT-1
We load the experiment timeline file into a Timeline
object, and define a list of phases of interest.
timeline = pm.Timeline(‘FVB/timeline.ini’)
PHASES = ['PP dark', 'PP light',
'DISC 1 dark', 'DISC 1 light',
'DISC 2 dark', 'DISC 2 light',
'DISC 3 dark', 'DISC 3 light',
'DISC 4 dark', 'DISC 4 light',
'DISC 5 dark', 'DISC 5 light']
To analyze the data, we define a function get
PerformanceMatrix(), which returns a matrix of
performance (defined as the fraction of first nosepokes in the
accessible corner, which are performed to the rewarded side)
of all mice in the system. Each row in this matrix
contains the performance data of one mouse, and each column
corresponds to one phase of the experiment for all mice.
for mouse in data.getMice()]
For every mouse, the getPerformanceCurve()
function is called to create a row corresponding to the
performance of that mouse across subsequent phases.
return [getPerformance(mouse, phase)
for phase in PHASES]
We use the getPerformance() function to create a
list of the mouse’s performance measures (fraction of first
nosepokes in the accessible corner, which are performed to
the rewarded side) in subsequent phases.
def getPerformance(mouse, phase):
start, end = timeline.getTimeBounds(phase)
visits = data.getVisits(mice=[mouse],
accessibleCornerVisits = filter(
return visit.CornerCondition > 0
In the getPerformance() function, we obtain all
visits performed by the mouse during the phase. Visits
to the accessible corner are passed to the calculate
Performance() function for further analysis. It is easy
to filter the visits—in the IntelliCage experiment design the
accessible corner was marked as ‘correct’. Thus, visits to the
corner have positive value of the .CornerCondition
attribute of the Visit object.
firstNps = [v.Nosepokes
for v in visits if v.Nosepokes]
successes = [isToCorrectSide(nosepoke)
for nosepoke in firstNps]
return nosepoke.SideCondition > 0
To calculate the performance, we check whether the first
nosepoke of every visit was to the rewarded side. The
rewarded side was marked as ‘correct’ in the experiment
design. Thus, nosepokes to the correct side have positive
value of the .SideCondition attribute of the
respective Nosepoke object. The side which was rewarded in
DISC phases was marked as ‘correct’ already during the PP
phases (when both bottles in a corner contained the same
liquid), so that the relevant fraction can be easily extracted
also from the PP phases.
Based on the counts of first nosepokes performed to each
of the sides, we calculate the success ratio (code omitted
With all the functions defined, we obtain the performance
matrix and plot it averaged across mice in Fig. 3 (plotting
code omitted here).
Example 3: reproducibility—batch analysis of data
In this example, we analyze results of a place preference
experiment described in detail in
Pus´cian et al. (2014)
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 (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 (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
Pus´cian et al. (2014)
, and in the final figure obtained in this
example (Fig. 4) we show two learning curves from Fig. 3A
Pus´cian et al. (2014)
(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 data,
timeline and PHASES objects from the relevant dataset
(different than in Example 2; code omitted here, the
full code is available at https://github.com/Neuroinflab/
As in the previous example, we define a function
returning a performance matrix (defined here as the fraction of
visits to the rewarded corner): performanceMatrix().
group = data.getGroup(groupName)
for mouse in group.Animals]
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 Group object, which we request in the first
line of the function.
The getPerformance() and calculatePerformance()
functions are simpler than in the previous example, as
neither filtering of visits nor extracting of nosepokes is
def getPerformance(mouse, phase):
start, end = timeline.getTimeBounds(phase)
visits = data.getVisits(mice=[mouse],
successes = [isToCorrectCorner(v)
for v in visits]
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
.CornerCondition attribute of the Visit object.
With all the functions defined, we obtain a performance
matrix and plot it averaged across mice (Fig. 4) for each
cohort (groups C57A and C57B) separately. Note that
analyzing several cohorts reduces to a loop over the cohorts
included in the analysis.
>>> with DecoratedAxes() as ax:
... for group in ['C57 A', 'C57 B']:
... performance = performanceMatrix(group)
Example 4: implementing new behavioral measures—intervals between visits
In this example, we illustrate the possibility of
programming new data analysis methods in Python. We are going to
investigate durations of intervals between subsequent visits
of mice to a corner. The assumption here is that the
distribution of such intervals is a measure of interactions between
the mice. In this example we will just calculate the measure
without discussing it much, but we believe that such
measure, or a variant of it, would be useful in studying social
behaviors or social structure of the group. In particular, one
could study which mice follow which, and therefore look
into potential modulation of learning or cognitive abilities
by such behaviors as following or imitation.
We want to plot histograms of interval durations for each
corner separately, and we restrict the analysis to just one
phase: Place Pref 3 dark. Such analysis would be very
hard or impossible to perform using Analyzer, and requires
the use of some kind of programming language, which
is the main reason we include it in the paper. Below we
show that the analysis in Python using PyMICE is quite
We begin by selecting all visits performed during the
phase. The order parameter of the .getVisits()
method makes the returned sequence ordered with respect
to the .Start attribute.
start, end = timeline.getTimeBounds(
'Place Pref 3 dark')
visits = data.getVisits(start=start, end=end,
This list contains visits performed to all corners of the
cage. Next we need to extract subsequences of visits
performed to the same corner in the same cage.
def getSubsequence(visits, cage, corner):
return [v for v in visits if v.Cage == cage
and v.Corner == corner]
Since the order of the subsequence is preserved, it is then
easy to determine intervisit intervals.
return [(b.Start - a.End)
for (a, b) in zip(visits[:-1],
The histograms are shown in Fig. 5. As in the
previous examples, the details of plot generation are hidden.
The full code is available at https://github.com/Neuroinflab/
We recommend to use the PyMICE library with the
Anaconda Python distribution
(Continuum Analytics, 2015)
The library requires NumPy
(van der Walt, Colbert,
& Varoquaux, 2011; Oliphant, 2007)
, matplotlib (Hunter,
(Niemeyer, Pieviläinen, & de Leeuw, 2016)
Python packages to be installed in
The library itself is available as a package from the
Python Package Index (PyPI)
(Jones, 2002; Python
Software Foundation, 2016)
for Python version 3.3, 3.4, 3.5 and
3.6, as well as 2.7. It can be installed with either pip
Packaging Authority, 2016)
$ pip install PyMICE
or easy_install (Python Packaging Authority, 2017):
$ easy_install PyMICE
A bleeding edge version of the library might be also
downloaded from https://github.com/Neuroinflab/PyMICE
PyMICE library is open-source and is available for free
under GPL3 license
(Free Software Foundation, 2007)
ask that this article is cited and resource identifier
et al., 2016)
for the library (RRID:nlx_158570) is provided
in any published research making use of PyMICE.
In this paper we have introduced PyMICE, a software
library which allows to access and analyze data from
IntelliCage experiments. The library has been developed to
facilitate automated, reproducible, and customizable analysis
of large data generated by the IntelliCage system.
Analyzer, the software bundled with the IntelliCage, does not
meet these requirements, as it was designed with a different
purpose in mind
(NewBehavior A G, 2011)
: ‘The “Analyzer”
is intended to give an overview of the results [...] The function
of “Analyzer” is to provide the user with data merging,
extraction, and filtering tools in order to generate data sets
appropriate for in-depth graphical and statistical analyses.’
One of the features of the IntelliCage system is that
very different experiments are possible, depending on the
subject of the research. Some protocols focus on
assessment of subjects’ ability of reward location
(Knapska et al.,
and behavioral sequence
(Endo et al., 2011)
learning. Other protocols are dedicated to measure
addictionrelated behavior like subject impulsiveness
and Kaczmarek, 2012; Mijakowska et al., 2017)
often a new experiment requires a completely new approach
to data analysis. Rather than trying to predict the specific
needs of the prospective users, we decided to provide
simple, intuitive and user-friendly interface for accessing the
data. Such interface allows a scientific programmer to tailor
dedicated software focusing on the essence of the
analysis instead of the technical details. To our knowledge,
PyMICE is the only freely available solution for analysis of
IntelliCage data in a scripting language.
PyMICE is written in the Python programming
language. Our choice of Python was directed by the same
factors which made it a popular choice for scientific
computing in general. Python is free, open-source, relatively
easy to learn, and is supported by a number of scientific
tools and libraries, such as: NumPy and SciPy
(Perez & Granger, 2007)
, etc. We believe that PyMICE
will be a useful addition to that collection.
The number of IntelliCage-based publications is
increasing in recent years
(TSE Systems International Group,
, but the system is still relatively little known. We
believe that one of the factors handicapping the
popularity of IntelliCage, or similar automated setups, is the lack
of a proper software ecosystem. We hope that the
availability of PyMICE will have a stimulating effect on the
adoption of automated behavioral systems. While the
current (at the time of the publication) version of the library
only supports the IntelliCage, the library may be
generalized to other behavioral systems. Data from any system
capturing point events (such as visits to specific locations—
as opposed to e.g. continuous trajectories of the animals)
could be presented to the user in a similar way as the
IntelliCage data. Specifically, representing each behavioral event
as a Python object with relevant attributes would allow for
intuitive manipulation of data and for easy extraction of
the quantities which are analyzed. The PyMICE library is
(Free Software Foundation, 2007)
available at GitHub, the largest open source software
(Gousios, Vasilescu, Serebrenik, & Zaidman, 2014)
therefore the extensions to other behavioral systems can be
contributed by the community.
A crucial feature of PyMICE is the possibility of
creating automated data analysis workflows. Such workflows are
useful, for example, when the same protocol is applied to
multiple groups of animals—this is a very common case, as
most experiments will have at least one experimental and
one control group. A workflow defined in a Python script
may be used to perform exactly the same analysis on every
available dataset, which both saves effort and greatly
reduces possibility of mistakes as compared to analyzing each
We also believe that popularization of such workflows
would lead to better research reproducibility. Current efforts
for reproducible research are mostly focused on improving
the experimental procedures, statistical analysis, and the
(Begley & Ellis, 2012; Begley, 2013; Halsey,
Curran-Everett, Vowler, & Drummond, 2015)
unclear or ambiguous description of data analysis is also
given as a factor contributing to poor reproducibility of
(Ince, Hatton, & Graham-Cumming, 2012)
A (non-interactive) computer program is a precise, formal
and unambiguous description of the analysis performed. We
hope that PyMICE could become a common platform for
implementing and sharing workflows for analysis of data
from the IntelliCage (or similar) system, and make data
analysis using scripts more accessible and more popular.
The paper itself is a proof of the concept of the ‘really
(Buckheit & Donoho, 1995)
writing it we followed the literate programming paradigm
. Every of the presented results of analysis
was generated by a Python + PyMICE workflow embedded
in the LATEX
source code of the document
(see the Statement of reproducibility below for details).
Statement of reproducibility (Peng, 2011)
The source code of the paper is available at https://github.
com/Neuroinflab/PyMICE_SM/. Paper compiled from the
source code may differ from the journal version because
of manual formatting. All presented results may be
reproduced with the Pweave tool
& Kowalski, 2016)
an interpreter of Python programming
language v. 2.7.3, PyMICE v. 1.1.0,
(Dzik, Łe˛ski & Pus´cian,
NumPy v. 1.6.1, matplitlib v. 1.1.1rc, dateutil v. 1.5
and pytz v. 2012c. (Wilson et al., 2014).
Acknowledgements JD, KR and SŁ supported by a Symfonia NCN
grant UMO-2013/08/W/NZ4/00691. AP supported by a grant from
Switzerland through the Swiss Contribution to the enlarged European
Union (PSPB-210/2010 to Ewelina Knapska and Hans-Peter Lipp).
KR and ZM supported by an FNP grant POMOST/2011-4/7 to KR.
Open Access This article is distributed under the terms of the
Creative Commons Attribution 4.0 International License (http://
creativecommons.org/licenses/by/4.0/), which permits unrestricted
use, distribution, and reproduction in any medium, provided you give
appropriate credit to the original author(s) and the source, provide a link
to the Creative Commons license, and indicate if changes were made.
Begley , C. G. ( 2013 ). Reproducibility: Six red flags for suspect work . Nature , 497 , 433 - 434 .
Begley , C. G. , & Ellis , L. M. ( 2012 ). Drug development: Raise standards for preclinical cancer research . Nature , 483 , 531 - 533 .
Bishop , S. ( 2016 ). Pytz - world timezone definitions for Python . Retrieved from https://dateutil.readthedocs.org/
Buckheit , J. , & Donoho , D. ( 1995 ). Wavelab and reproducible research . In A. Antoniadis, & G. Oppenheim (Eds.) Wavelets and statistics (pp. 55 - 81 ). New York, NY: Springer. doi: 10 .1007/978-1- 4612 - 2544- 7 _ 5
Chesler , E. J. , Wilson, S. G. , Lariviere , W. R. , Rodriguez-Zas , S. L. , & Mogil , J. S. ( 2002 ). Identification and ranking of genetic and laboratory environment factors influencing a behavioral trait, thermal nociception, via computational analysis of a large data archive . Neuroscience and Biobehavioral Reviews , 26 , 907 - 923 .
Codita , A. , Mohammed , A. H. , Willuweit , A. , Reichelt , A. , Alleva , E. , Branchi , I. , ..., & Krackow , S. ( 2012 ). Effects of spatial and cognitive enrichment on activity pattern and learning performance in three strains of mice in the IntelliMaze . Behavior Genetics , 42 , 449 - 460 .
Continuum Analytics ( 2015 ). Anaconda software distribution [computer software] . Available from: https://continuum.io/.
Crabbe , J. C. , Wahlsten , D. , & Dudek , B. C. ( 1999 ). Genetics of mouse behavior: Interactions with laboratory environment . Science , 284 , 1670 - 1672 .
Daan , S. , Spoelstra , K. , Albrecht , U. , Schmutz , I. , Daan , M. , Daan , B. , ..., & Omo , G. D. ( 2011 ). Lab mice in the field: Unorthodox daily activity and effects of a dysfunctional circadian clock allele . Journal of Biological Rhythms , 26 , 118 - 129 .
de Chaumont , F. , Coura , R. D. S. , Serreau , P. , Cressant , A. , Chabout , J. , Granon , S. , & Olivo-Marin , J. C. ( 2012 ). Computerized video analysis of social interactions in mice . Nature Methods , 9 , 410 - 417 .
Dell'omo , G., Shore , R. F. , & Lipp , H. P. ( 1998 ). An automated system, based on microchips, for monitoring individual activity in wild small mammals . The Journal of Experimental Zoology , 280 , 97 - 99 .
Dzik , J. M. , Łe˛ski, S. , & Pus´cian, A. ( 2016 ). PyMICE: 1.1 .0 release. [computer software; RRID:nlx_158570] doi:10.5281/zenodo.200648.
Dzik , J. M. , & Łe˛ski, S. ( 2017a ). PyMICE documentation. Retrieved 18th-May-2017 , from https://neuroinflab.github.io/PyMICE/
Dzik , J. M. , & Łe˛ski, S. ( 2017b ). PyMICE laboratory of neuroinformatics . Retrieved 18th-May-2017 , from https://neuroinflab. wordpress.com/research/pymice/
Endo , T. , Maekawa , F. , Võikar , V. , Haijima , A. , Uemura , Y. , Zhang , Y. , ..., & Kakeyama , M. ( 2011 ). Automated test of behavioral flexibility in mice using a behavioral sequencing task in IntelliCage . Behavioural Brain Research , 221 , 172 - 181 .
Floyd , R. W. ( 1967 ). Assigning meanings to programs . In Schwartz J. T. (Ed.), Mathematical Aspects of Computer Science (pp. 19 - 32 ) Providence, RI: American Mathematical Society.
Free Software Foundation ( 2007 ). GNU general public license version 3. In The GNU operating system and the free software movement . Retrieved from https://www.gnu.org/licenses/gpl.html
Galsworthy , M. J. , Amrein , I. , Kuptsov , P. A. , Poletaeva , I. I. , Zinn , P. , Rau , A. , ..., & Lipp , H. P. ( 2005 ). A comparison of wildcaught wood mice and bank voles in the IntelliCage: Assessing exploration, daily activity patterns and place learning paradigms . Behavioural Brain Research , 157 , 211 - 217 .
Gousios , G. , Vasilescu , B. , Serebrenik , A. , & Zaidman , A. ( 2014 ). Lean GHTorrent: GitHub data on demand . In Proceedings of the 11th working conference on mining software repositories (pp. 384 - 387 ). New York, NY: USAACM. doi: 10 .1145/2597073. 2597126
Halsey , L. G. , Curran-Everett , D. , Vowler , S. L. , & Drummond , G. B. ( 2015 ). The fickle P value generates irreproducible results . Nature Methods , 12 , 179 - 185 .
Heinrichs , S. C. , & Koob , G. F. ( 2006 ). Application of experimental stressors in laboratory rodents . In Gerfen, C. G., Holmes , A. , Sibley , D. , Skolnick , P. , Wray , S. , Crawley , J. N. , ..., Rogawski , A. M. (Eds.) Current protocols in neuroscience (pp. 8 . 4 .1- 8 .4.17). John Wiley & Sons, Inc. doi: 10 .1002/0471142301.ns0804s34 Retrieved from http://onlinelibrary.wiley.com/doi/10.1002/0471142301. ns0804s34/full
Hoare , C. A. R. ( 1969 ). An axiomatic basis for computer programming . Communications of the ACM , 12 , 576 - 580 .
Hunter , J. D. ( 2007 ). Matplotlib: A 2D graphics environment . Computing in Science and Engineering , 9 ( 3 ), 90 - 95 .
Ince , D. C. , Hatton , L. , & Graham-Cumming , J. ( 2012 ). The case for open computer programs . Nature , 482 , 485 - 488 .
Jones , R. ( 2002 ). PEP 0301 - Package index and metadata for distutils . Retrieved 15th-Jan-2016 , from https://www.python.org/dev/peps/ pep-0301/
Kiryk , A. , Mochol , G. , Filipkowski , R. K. , Wawrzyniak , M. , Lioudyno , V. , Knapska , E. , ..., & Kaczmarek , L. ( 2011 ). Cognitive abilities of Alzheimer's disease transgenic mice are modulated by social context and circadian rhythm . Current Alzheimer Research , 8 , 883 - 892 .
Knapska , E. , Lioudyno , V. , Kiryk , A. , Mikosz , M. , Gorkiewicz , T. , Michaluk , P. , ..., & Kaczmarek , L. ( 2013 ). Reward learning requires activity of matrix metalloproteinase-9 in the central amygdala . Journal of Neuroscience , 33 , 14591 - 14600 .
Knapska , E. , Walasek , G. , Nikolaev , E. , Neuhäusser-Wespy , F. , Lipp , H.P. , Kaczmarek , L. , & Werka , T. ( 2006 ). Differential involvement of the central amygdala in appetitive versus aversive learning . Learning and Memory , 13 , 192 - 200 .
Knuth , D. E. ( 1984 ). Literate programming . The Computer Journal , 27 , 97 - 111 .
Krackow , S. , Vannoni , E. , Codita , A. , Mohammed , A. H. , Cirulli , F. , Branchi , I. , & Lipp , H.P. ( 2010 ). Consistent behavioral phenotype differences between inbred mouse strains in the IntelliCage . Genes, Brain and Behavior , 9 , 722 - 731 .
Lamport , L. ( 1986 ). LaTeX: A document preparation system: User's guide and reference manual . Addison-Wesley Longman Publishing Co. Inc . Reading, MA: Addison-Wesley.
McCarthy , J. ( 1963 ). A basis for a mathematical theory of computation . In Braffort P., & Hirshberg , D . (Eds.) Computer programming and formal systems (pp. 33 - 70 ). Amsterdam, North-Holland.
McKinney , W. ( 2010 ). Data structures for statistical computing in Python . In van der Walt, S. , & Millman , J . (Eds.) Proceedings of the 9th Python in science conference (pp. 51 - 56 ).
Mijakowska , Z. , Łukasiewicz , K. , Ziółkowska , M. , Lipin´ski, M. , Tra˛bczyn´ska, A. , Matuszek , Z ˙ ., ..., & Radwan´ska, K. ( 2017 ). Autophosphorylation of alpha isoform of calcium/calmodulindependent kinase II regulates alcohol addiction-related behaviors . Addiction Biology , 22 , 331 - 341 .
Morrison , S. J. ( 2014 ). Time to do something about reproducibility . eLife , 3 , e03981 .
NewBehavior A G ( 2011 ). IntelliCage plus manual . Zürich: NewBehavior AG.
Niemeyer , G. , Pieviläinen , T. , & de Leeuw, Y. ( 2016 ). Dateutil - powerful extensions to datetime . Retrieved from https://dateutil. readthedocs.org/
Oliphant , T. E. ( 2007 ). Python for scientific computing . Computing in Science and Engineering , 9 ( 3 ), 10 - 20 .
Ozyurt , I. B. , Grethe , J. S. , Martone , M. E. , & Bandrowski , A. E. ( 2016 ). Resource disambiguator for the web: Extracting biomedical resources and their citations from the scientific literature . PLoS ONE , 11 , e0146300. doi:10.1371/journal.pone.0146300
Pastell , M. ( 2015 ). Pweave - reports from data with Python . Retrieved 8th-Oct-2015 , from http://mpastell.com/pweave
Pastell , M. , & Kowalski , J. ( 2016 ). Pweave v0 . 24 - Scientific Reports Using Python [computer software] Zenodo. doi: 10 .5281/ zenodo.45054
Peng , R. D. ( 2011 ). Reproducible research in computational science . Science , 334 , 1226 - 1227 . doi: 10 .1126/science.1213847
Perez , F. , & Granger , B. E. ( 2007 ). IPython: A system for interactive scientific computing . Computing in Science and Engineering , 9 ( 3 ), 21 - 29 .
Pérez-Escudero , A. , Vicente-Page , J. , Hinz , R. C. , Arganda , S. , & de Polavieja, G. G. ( 2014 ). idTracker: Individuals in a group by automatic identification of unmarked animals . Nature Methods , 11 , 743 - 748 .
Peters , T. ( 2004 ). PEP 20 - The Zen of Python. Retrieved 8th-Oct2015 , from https://www.python.org/dev/peps/pep-0020/
Project Jupyter ( 2015 ). The Jupyter Notebook [computer software] . Project Jupyter . Available from https://jupyter.org
Pus´cian, A. , Łe˛ski, S. , Górkiewicz , T. , Meyza , K. , Lipp , H. P. , & Knapska , E. A. ( 2014 ). A novel automated behavioral test battery assessing cognitive rigidity in two genetic mouse models of autism . Frontiers in Behavioral Neuroscience , 8 , 140 .
Pus´cian, A. , Łe˛ski, S. , Kasprowicz , G. , Winiarski , M. , Borowska , J. , Nikolaev , T. , ..., & Knapska , E. ( 2016 ). Eco-HAB as a fully automated and ecologically relevant assessment of social impairments in mouse models of autism . eLife, 5 , e19532 .
Python Packaging Authority ( 2016 ). Pip - pip 7.1.2 documentation. Retrieved 15th-Jan-2016 , from https://pip.pypa.io/
Python Packaging Authority ( 2017 ). Easy install . setuptools 35.0.2 documentation. Retrieved 19th-May-2017 , from https:// setuptools.readthedocs.io/en/latest/easy_install.html
Python Software Foundation ( 2016 ). PyPI - the Python package index . Retrieved from https://pypi.python.org/pypi
Radwan ´ska, K. , & Kaczmarek , L. ( 2012 ). Characterization of an alcohol addiction-prone phenotype in mice . Addiction Biology , 17 , 601 - 612 .
Shemesh , Y. , Sztainberg , Y. , Forkosh , O. , Shlapobersky , T. , Chen , A. , & Schneidman , E. ( 2013 ). High-order social interactions in groups of mice . eLife, 2 , e00759 .
Smutek , M. , Turbasa , M. , Sikora , M. , Piechota , M. , Zajdel , J. , Przewlocki , R. , & Parkitna , J. R. ( 2014 ). A model of alcohol drinking under an intermittent access schedule using group-housed mice . PLOS ONE , 9 ( 5 ), e96787 .
Sorge , R. E. , Martin , L. J. , Isbester , K. A. , Sotocinal , S. G. , Rosen , S. , Tuttle , A. H. , ..., & Mogil , J. S. ( 2014 ). Olfactory exposure to males, including men, causes stress and related analgesia in rodents . Nature Methods , 11 , 629 - 632 .
TSE Systems International Group ( 2016 ). IntelliCage reference list . Retrieved 19th-May-2017 from http://www.tse-systems.com/ download/TSE_IntelliCage_Publications.pdf.
Turing , A. ( 1937 ). On computable numbers, with an application to the entscheidungsproblem . Proceedings of the London Mathematical Society , s2 - 42 , 320 - 265 .
van der Walt , S. , Colbert , S. C. , & Varoquaux , G. ( 2011 ). The NumPy array: A structure for efficient numerical computation . Computing in Science and Engineering , 13 ( 2 ), 22 - 30 . doi: 10 .1109/ MCSE . 2011 .37
Vannoni , E. , Võikar , V. , Colacicco , G. , Sánchez , M. A. , Lipp , H. P. , & Wolfer , D. P. ( 2014 ). Spontaneous behavior in the social homecage discriminates strains, lesions and mutations in mice . Journal of Neuroscience Methods , 234 , 26 - 37 .
van Rossum , G. ( 1995 ). Python tutorial (Amsterdam No. CS-r9526) . Amsterdam: Centrum voor Wiskunde en Informatica (CWI).
Weissbrod , A. , Shapiro , A. , Vasserman , G. , Edry , L. , Dayan , M. , Yitzhaky , A. , ..., & Kimchi , T. ( 2013 ). Automated long-term tracking and social behavioural phenotyping of animal colonies within a semi-natural environment . Nature Communications , 4 , doi:10.1038/ncomms3018
Wilson , G. , Aruliah , D. A. , Brown , C. T., Chue Hong , N. P. , Davis , M. , Guy , R. T., ..., & Wilson, P. ( 2014 ). Best practices for scientific computing . PLoS Biology , 12 ( 1 ), e1001745 . doi:10.1371/ journal.pbio.1001745