Introduction¶

PyMICE is a Python® library for mice behavioural data analysis.

The library can be used for loading and analysing of data obtained from IntelliCage™ system in an intuitive way in Python programming language.

The library provides user with an object oriented application programming interface (API) and a data abstraction layer. It also comes with auxiliary tools supporting development of analysis workflows, like data validators and a tool for workflow configuration.

For more details please see The project website.

PyMICE package manual¶

Package pymice¶

A collection of tools to access IntelliCage data.

class pymice.Loader(fname, getNp=True, getLog=False, getEnv=False, getHw=False, verbose=False, **kwargs)¶

__init__(fname, getNp=True, getLog=False, getEnv=False, getHw=False, verbose=False, **kwargs)¶

Parameters:	fname (basestring) – a path to the data file. getNp (bool) – whether to load nosepoke data. getLog (bool) – whether to load log. getEnv (bool) – whether to load environmental data. getHw (bool) – whether to load hardware data. verbose (bool) – whether to output verbose messages

getVisits(mice=None, start=None, end=None, order=None)¶

Parameters:	mice (str or unicode or `Animal` or collection of them or None) – mouse (or mice) which visits are requested start (datetime.datetime or None) – a lower bound of the visit Start attribute end (datetime.datetime or None) – an upper bound of the visit Start attribute order (str or unicode or their sequence or None) – attributes that the returned list is ordered by
Returns:	visits
Return type:	[`Visit`, ...]

>>> data.getVisits(mice='Mickey')
[< Visit of "Mickey" to corner #1 of cage #1 (at 2012-12-18 12:31:00.000) >]

>>> data.getVisits(mice=['Mickey', 'Minnie'], order='Start')
[< Visit of "Minnie" to corner #4 of cage #1 (at 2012-12-18 12:30:02.360) >,
 < Visit of "Mickey" to corner #1 of cage #1 (at 2012-12-18 12:31:00.000) >]

>>> mice = [data.getAnimal(m) for m in ['Mickey', 'Minnie']]
>>> data.getVisits(mice=mice, order='Start')
[< Visit of "Minnie" to corner #4 of cage #1 (at 2012-12-18 12:30:02.360) >,
 < Visit of "Mickey" to corner #1 of cage #1 (at 2012-12-18 12:31:00.000) >]

getLog(start=None, end=None, order=None)¶

Parameters:	start (datetime.datetime or None) – a lower bound of the log entries DateTime attribute end (datetime.datetime or None) – an upper bound of the log entries DateTime attribute order (str or unicode or their sequence or None) – attributes that the returned list is ordered by
Returns:	log entries
Return type:	[`LogEntry`, ...]

>>> data.getLog(order='DateTime')
[< Log Info, Application (at 2012-12-18 12:13:02.437) >,
 < Log Info, Application (at 2012-12-18 12:20:37.718) >]

getEnvironment(start=None, end=None, order=None)¶

Parameters:	start (datetime.datetime or None) – a lower bound of the sample DateTime attribute end (datetime.datetime or None) – an upper bound of the sample DateTime attribute order (str or unicode or their sequence or None) – attributes that the returned list is ordered by
Returns:	sampled environment conditions
Return type:	[`EnvironmentalConditions`, ...]

>>> data.getEnvironment(order=('DateTime', 'Cage'))
[< Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:13:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:13:02.000) >,
 < Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:14:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:14:02.000) >,
 < Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:15:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:15:02.000) >,
 < Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:16:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:16:02.000) >,
 < Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:17:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:17:02.000) >,
 < Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:18:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:18:02.000) >,
 < Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:19:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:19:02.000) >,
 < Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:20:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:20:02.000) >]

getHardwareEvents(start=None, end=None, order=None)¶

Parameters:	start (datetime.datetime or None) – a lower bound of the event DateTime attribute end (datetime.datetime or None) – an upper bound of the event DateTime attribute order (str or unicode or their sequence or None) – attributes that the returned list is ordered by
Returns:	hardware events
Return type:	[`HardwareEvent`, ...]

getAnimal(name=None)¶

Parameters:	name (unicode convertable or None) – name of the animal
Returns:	animal data if name given else names of animals
Return type:	`Animal` if name given else frozenset([unicode, ...])

getCage(mouse)¶

Parameters:	mouse (basestring or `Animal`) – mouse name or representation
Returns:	cage(s) where mouse’s visits has been registered
Return type:	convertable to int or (convertable to int, ...)

>>> data.getCage('Minnie')
1

>>> data.getCage(data.getAnimal('Minnie'))
1

getInmates(cage=None)¶

Parameters:	cage (convertable to int or None) – number of the cage
Returns:	animals detected in the cage if given else available cages
Return type:	frozenset(`Animal`, ...) if cage is given else frozenset(int, ...)

getGroup(name=None)¶

Parameters:	name (basestring or None) – name of the group
Returns:	group data if name given else names of groups
Return type:	`Group` if name given else frozenset([unicode, ...])

getStart()¶

Returns:	time of the earliest visit registration
Return type:	datetime.datetime or None

getEnd()¶

Returns:	time of the latest visit registration
Return type:	datetime.datetime or None

class pymice.Merger(*dataSources, **kwargs)¶

>>> mm = Merger(ml_icp3, ml_l1)
>>> for v in mm.getVisits(order='Start'):
...   print('%s %d %s' % (str(v.Animal), len(v.Nosepokes), list(v.Animal.Tag)[0]))
Minnie 0 1337
Mickey 1 42
Jerry 2 69
Minnie 1 1337
Mickey 1 42
Jerry 2 69

>>> mm = Merger(ml_empty, ml_l1)
>>> for v in mm.getVisits(order='Start'):
...   print('%s %d' % (str(v.Animal), len(v.Nosepokes)))
Minnie 1
Mickey 1
Jerry 2

>>> mm = Merger(ml_retagged, ml_l1)
>>> for v in mm.getVisits(order='Start'):
...   print('%s %d' % (str(v.Animal), len(v.Nosepokes)))
...   print("  %s" % (', '.join(sorted(v.Animal.Tag))))
Mickey 0
  1337, 42
Minnie 1
  1337, 42
Jerry 2
  69
Minnie 1
  1337, 42
Mickey 1
  1337, 42
Jerry 2
  69

__init__(*dataSources, **kwargs)¶

Usage: Merger(data_1, [data_2, ...] [parameters])

Parameters:

dataSources ([Data, ...]) – objects containing IntelliCage data
getNp (bool) – whether to load nosepoke data (defaults to False).
getLog (bool) – whether to load log (defaults to False).
getEnv (bool) – whether to load environmental data (defaults to False).
getHw (bool) – whether to load hardware data (defaults to False).
ignoreMiceDifferences (bool) – whether to ignore encountered differences in animal description (e.g. sex)

getVisits(mice=None, start=None, end=None, order=None)¶

Parameters:	mice (str or unicode or `Animal` or collection of them or None) – mouse (or mice) which visits are requested start (datetime.datetime or None) – a lower bound of the visit Start attribute end (datetime.datetime or None) – an upper bound of the visit Start attribute order (str or unicode or their sequence or None) – attributes that the returned list is ordered by
Returns:	visits
Return type:	[`Visit`, ...]

>>> data.getVisits(mice='Mickey')
[< Visit of "Mickey" to corner #1 of cage #1 (at 2012-12-18 12:31:00.000) >]

>>> data.getVisits(mice=['Mickey', 'Minnie'], order='Start')
[< Visit of "Minnie" to corner #4 of cage #1 (at 2012-12-18 12:30:02.360) >,
 < Visit of "Mickey" to corner #1 of cage #1 (at 2012-12-18 12:31:00.000) >]

>>> mice = [data.getAnimal(m) for m in ['Mickey', 'Minnie']]
>>> data.getVisits(mice=mice, order='Start')
[< Visit of "Minnie" to corner #4 of cage #1 (at 2012-12-18 12:30:02.360) >,
 < Visit of "Mickey" to corner #1 of cage #1 (at 2012-12-18 12:31:00.000) >]

getLog(start=None, end=None, order=None)¶

Parameters:	start (datetime.datetime or None) – a lower bound of the log entries DateTime attribute end (datetime.datetime or None) – an upper bound of the log entries DateTime attribute order (str or unicode or their sequence or None) – attributes that the returned list is ordered by
Returns:	log entries
Return type:	[`LogEntry`, ...]

>>> data.getLog(order='DateTime')
[< Log Info, Application (at 2012-12-18 12:13:02.437) >,
 < Log Info, Application (at 2012-12-18 12:20:37.718) >]

getEnvironment(start=None, end=None, order=None)¶

Parameters:	start (datetime.datetime or None) – a lower bound of the sample DateTime attribute end (datetime.datetime or None) – an upper bound of the sample DateTime attribute order (str or unicode or their sequence or None) – attributes that the returned list is ordered by
Returns:	sampled environment conditions
Return type:	[`EnvironmentalConditions`, ...]

>>> data.getEnvironment(order=('DateTime', 'Cage'))
[< Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:13:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:13:02.000) >,
 < Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:14:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:14:02.000) >,
 < Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:15:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:15:02.000) >,
 < Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:16:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:16:02.000) >,
 < Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:17:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:17:02.000) >,
 < Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:18:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:18:02.000) >,
 < Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:19:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:19:02.000) >,
 < Illumination:   0, Temperature: 22.0 (at 2012-12-18 12:20:02.000) >,
 < Illumination:   0, Temperature: 23.6 (at 2012-12-18 12:20:02.000) >]

getHardwareEvents(start=None, end=None, order=None)¶

Parameters:	start (datetime.datetime or None) – a lower bound of the event DateTime attribute end (datetime.datetime or None) – an upper bound of the event DateTime attribute order (str or unicode or their sequence or None) – attributes that the returned list is ordered by
Returns:	hardware events
Return type:	[`HardwareEvent`, ...]

getAnimal(name=None)¶

Parameters:	name (unicode convertable or None) – name of the animal
Returns:	animal data if name given else names of animals
Return type:	`Animal` if name given else frozenset([unicode, ...])

getCage(mouse)¶

Parameters:	mouse (basestring or `Animal`) – mouse name or representation
Returns:	cage(s) where mouse’s visits has been registered
Return type:	convertable to int or (convertable to int, ...)

>>> data.getCage('Minnie')
1

>>> data.getCage(data.getAnimal('Minnie'))
1

getInmates(cage=None)¶

Parameters:	cage (convertable to int or None) – number of the cage
Returns:	animals detected in the cage if given else available cages
Return type:	frozenset(`Animal`, ...) if cage is given else frozenset(int, ...)

getGroup(name=None)¶

Parameters:	name (basestring or None) – name of the group
Returns:	group data if name given else names of groups
Return type:	`Group` if name given else frozenset([unicode, ...])

getStart()¶

Returns:	time of the earliest visit registration
Return type:	datetime.datetime or None

getEnd()¶

Returns:	time of the latest visit registration
Return type:	datetime.datetime or None

Auxilary tools¶

class pymice.ExperimentTimeline(path, fname=None, tzinfo=None)¶

A class of objects for loading experiment timeline definition files.

As a subclass of matplotlib.ticker.Formatter the class is also time axis formatter in matplotlib.dates coordinates.

File format description

The format is a constrained INI format. Every section defined corresponds to phase of same name. The minimal information required about a phase are its boundaries given as start and end properties in format YYYY-MM-DD HH:MM or YYYY-MM-DD HH:MM:SS. Optional information about timezone of start and end properties might be provided by tzinfo property (name of timezone defined in pytz module).

__init__(path, fname=None, tzinfo=None)¶

Read the description of the experiment timeline.

Parameters:	path (basestring) – a path to either the experiment timeline file or a directory containing experiment timeline file of either `fname` or ‘config.txt’ or ‘config.(txt\|ini)’ name (matching in that order). fname* (basestring or None) – name of the experiment timeline file in `path` directory tzinfo (`datetime.tzinfo`) – default timezone

getTime(phases)¶

Parameters:	phases ([basestring, ...] or basestring) – name(s) of phase(s)
Returns:	timezone-aware boundaries of minimal period of time covering all phases given
Return type:	(`datetime.datetime`, `datetime.datetime`)

sections()¶: Return a list of section names, excluding [DEFAULT]

class pymice.DataValidator(*analyzers)¶

A class of objects performing data validation.

__init__(*analyzers)¶

Parameters:	analyzers – a set of analyzers defining validation criteria

__call__(data)¶

Parameters:	data (`pymice.Data.Data`) – data to be validated
Returns:	description of data found invalid
Return type:	(`ExcludeMiceData`, ...)

class pymice.LickometerLogAnalyzer(shortThreshold=3, medThreshold=None)¶

A class of objects detecting Lickometer type of warnings.

‘Lickometer is active but nosepoke is inactive’ errors might indicate a failure of the lickometer.

__init__(shortThreshold=3, medThreshold=None)¶

Parameters:	shortThreshold (int or float) – not used explicitly medThreshold (int or float) – a maximal acceptable number of lickometer warnings within 1 hour bin; defaults to 4*``shortThreshold``

class pymice.PresenceLogAnalyzer¶

Class of objects validating data against ‘Presence’ warnings using a sophisticated heuristic.

The ‘Presence signal without antenna registration.’ warning might indicate that either an antenna is not working properly or a mouse has its transponder lost.

class pymice.TestMiceData(issue=None)¶

Class of objects for checking whether report generated by DataValidator objects confirms validity of given scope of data.

__init__(issue=None)¶

Parameters:	issue (basestring) – type of the invalidating issue

__call__(report, interval, **kwargs)¶

Parameters:	report (collection(`ExcludeMiceData`, ...)) – report generated by `DataValidator` interval ((`datetime.datetime`, `datetime.datetime`)) – boundaries of temporal scope of validated data cage (int) – cage to which the scope of data is restricted corner (int) – corner to which the scope of data is restricted side (int) – side to which the scope of data is restricted
Returns:	`True` if the scope of data is valid else `False`
Return type:	bool

pymice.getTutorialData(path=None, quiet=False, fetch=None)¶

Write to disk example dataset(s) used in tutorials.

Parameters:	path (basestring) – a directory where tutorial data are to be loaded into (defaults to working directory) quiet (bool) – a switch disabling stdout output. fetch (collection(basestring, ...)) – the datasets to download

pymice.__PGP_PUBLIC_KEY__ = < ASCII armored PGP public key >¶: PGP public key for verifying of package updates from PyPI

Module pymice.debug¶

A collection of auxilary validation tools for PyMICE library.

pymice.debug.plotPhases(timeline, tzone=None, ax=None)¶

Plot a diagnostic plot of phases of the experiment timeline.

Parameters:	timeline (`pymice.ExperimentTimeline`) – the timeline tzone (`datetime.tzinfo` or None) – timezone of the plot or None ax (`matplotlib.axes.Axes` or None) – axis or None
Returns:	a new figure if `ax` parameter not provided else None
Return type:	`matplotlib.figure.Figure` or None

Authors¶

The library
- Jakub Kowalski
- Szymon Łęski
Tutorial data
- Alicja Puścian

Acknowledgement¶

JK and SŁ supported by 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).