📖 lickcalc

lickcalc is a web-based application for analysing licking microstructure in rodent behavioural experiments. It processes timestamp data from licking events and provides detailed statistical analysis including:

• Session-level analysis: Overall licking patterns over time
• Microstructural analysis: Burst patterns, intraburst frequency, and lick durations
• Statistical modeling: Weibull distribution fitting for burst probability
• Data export: Excel exports with customizable data selection

The application is based on the lickcalc function from the trompy module. More details about installing trompy and using lickcalc to code lick microstructure can be found in the section, Using lickcalc without the app

Session Overview Graph

The session graph shows the overall pattern of licking throughout your experimental session. You can choose between two visualization modes:

Bin Size Control

Adjust the time bin size to change the temporal resolution of your analysis. Smaller bins show more detail but may be noisier.

Session Length

By default, the session length will be based on the length of the data. If you want a specific session length, you can set it here or by using a custom config file.

Excel Export Options

Export your analysis results to Excel format with customizable data selection:

Analyzing Session Subdivisions

The app supports dividing your session into temporal or burst-based epochs for detailed analysis:

Installing locally

Reasons to install locally include working offline, avoiding server outages, and enabling modification or customization. Follow these steps to install using Anaconda or Mamba:

1. Clone the repository using git:

git clone https://github.com/uit-no/lickcalc.git
cd lickcalc

2. Create and activate the environment:

conda env create -f environment.yml
conda activate lickcalc

3. Run the app:

python app.py

4. Open a browser and go to localhost:8050

Using underpinning functions

The application is based on a utility included in the package trompy. It can be installed via pip and is hosted on Github at https://www.github.com/mccutcheonlab/trompy. The function lickcalc calls a class, Lickcalc, and is documented fully in the parent package. trompy also includes the file parsers and some helper functions Some example code using the function follows:

Historical background

Microstructural analysis was first described in Davis and Smith (1992) and has since then been used understand diverse phenomena. In-depth reviews on many of these, and microstructural parameters used to study them, are available (Johnson, 2018; Naneix et al., 2020; Smith, 2001). Briefly, although much of the foundational work on drinking microstruture was on licking for nutritive solutions (e.g., sucrose solutions), microstructural analysis can also be used to study intake of water (McKay & Daniels, 2013; Santollo et al., 2021), ethanol (Patwell et al., 2021), and other tastants such as non-caloric artificial sweeteners, sodium, and quinine (Lin et al., 2012; Spector & St. John, 1998; Verharen et al., 2019). Lick microstructure has been used to shed light on, for example, how licking is affected by neuropeptides (McKay & Daniels, 2013), enzymes in the mouth (Chometton et al., 2022), ovarian hormones (Santollo et al., 2021), nutrient restriction (Naneix et al., 2020), response to alcohol (Patwell et al., 2021), and diet (Johnson, 2012). The number of lick bouts over a session are thought to reflect postingestive feedback from the consumed fluid, wheras the number of licks in a bout are thought to reflect palatability of the solution.

Interpreting microstructure data

Lick microstructure can provide a great deal of interesting information about why an animal is drinking. Often, changes in microstructure are accompanied by changes in total intake, but this is not always the case: sometimes, equal intake will be achieved by quite different licking patterns that indicate changes in orosensory and postingestive feedback (Johnson et al., 2010; Volcko et al., 2020). Analyzing lick microstructure is therefore highly valuable in understanding how a manipulation affects appetite; if X causes an animal to feel more satiated after drinking, that may lead to a different interpretation than if X were to reduce the palatability of the solution.

Hardware considerations

Traditionally, researchers have used contact lickometers to detect individual licks. These generally pass a small amount of current through the animal and contacts with a (metal) spout cause completion of the circuit and lick detection. Recently, capacitive touch is more commonly used or deflections of a piezo or optic fibre. Several open-source lickometer designs are now available (e.g., Frie & Khokhar, 2024; Monfared et al., 2024; Petersen et al., 2024; Raymond et al., 2018; Silva et al., 2024).

Practical considerations: extended contacts

One problem that can arise are extended contacts with the spout, generally due to a fluid bridge forming between the animal's tongue and the spout. This can lead to very long "licks" that are in fact not individual licks but rather extended contacts. These can be prevented by ensuring that the sipper is recessed some distance from the wall of the chamber. To be sure that extended contacts do not affect the analysis, we recommend recording the offset time of each lick in addition to the onset time. In lickcalc, it is then possible to check for extended contacts and either adjust the behavioural setup (e.g., by moving the bottle back) or filter out extended contacts.

Setting up hardware to capture offsets

The instructions below refer to Med Associates hardware but the general principles can likely be transferred to other systems. First, in Med it is critical to adjust the jumper on the card so that the inputs from the lickometers are set to 'Level' mode rather than 'Toggle'. We then use state sets to track whether the tongue is in contact or not with the spout at all times but only write changes to this value to our data arrays. Example code can be downloaded from here and adapted as needed.