ColonyRack

ColonyRack is a development package that facilitates the analysis and visualization of data generated by the ColonyRack system. Its primary objective is to process data from RFID readers and save the results in separate files and plots, allowing users to derive detailed maps and movement patterns of mice. The package comprises metadata, raw data, and an interactive markdown vignette with examples to facilitate user understanding of how to use the functions for analysis. To account for the high variance in ColonyRack setups, such as the number and positioning of cages, the package utilizes metadata information about the experiment system.

Contents

• ColonyRack
• Contents
• Hardware
• Requirements
  • R
  • RStudio
• Installation
• Parameters
• Usage
• Project structure
• Results
• Getting Help

Hardware

The ColonyRack system uses animal-friendly enrichment equipment to provide automated tracking for long-term investigations of large social groups of mice. The system is composed of cage levels in standardized rack mounts, with interconnecting tubes that allow animals to move freely through all cages. RFID readers with micro-controllers are installed at each connection, continuously tracking all transponder activities. The system operates 24/7, producing data on each passage of a tagged animal with time and position.

Requirements

R

To clean, analyze, and plot the data, we chose R, a programming language for statistical computing and graphics.

You can download the latest version of R for your operating system from CRAN.

Here are direct download pages for different operating systems:

• R for Windows.
• R for MacOS.
• R for Linux.

RStudio

RStudio is an open-source IDE that can enhance the experience of using R by providing a console, debugging tools, and workspace management features. Although it is not mandatory to use RStudio, we strongly recommend it as it can improve the user-friendliness and efficiency of the R programming process.

It is not RStudio is available in two formats:

• RStudio Desktop: a regular desktop application
• RStudio Server: runs on a remote server and allows accessing RStudio using a web browser.

To download RStudio, visit the RStudio download homepage. For the desktop version, use the RStudio-Desktop link.

Please note:

• RStudio is not functional without an installation of R. You therefore need to install R regardless of whether or not you use RStudio.
• RStudio requires an installation of R 3.0.1 or higher.

The following interactive guides cover the important steps for the installation of R and RStudio:

• YouTube: How to install R and RStudio on Windows
• YouTube: How to install R and RStudio on MacOS

Installation

To install the development version of ColonyRack library from the GitHub repository, open RStudio and enter the following command in the console tab of the lower window:

# install.packages("devtools")  # install `devtools` if not yet installed 
devtools::install_github("Orabe/ColonyRack")

You can check where the library is saved by running the following R command in your console:

.libPaths() 

Alternatively, you can list all the installed R packages by running installed.packages(), or if you can run library(ColonyRack) without encountering any errors, then the library has been successfully installed.

Parameters

The activities are measured using the following parameters:

• Distance
• Duration
• Speed
• Cage visits
• Spatiality

Detailed analysis of mice activities can be derived from these datasets. The analyzed data are divided into these three sections and stored in the corresponding directory of each parameter in the project directory vignettes/results/csv. Gaphical representation of the statistical results can be found in the vignettes/results/jpg directory. See Results and Getting Help sections for further information.

Usage

Once you have installed the ColonyRack package, you can begin using it by importing it into your RStudio workspace (or R script file) using the following command:

library(ColonyRack)

After importing the package, you can use the functions provided within it. Refer to the Help section for further details.

However, to gain a deeper understanding of how to coordinate multiple functions to perform an analysis and to comprehend the intricacies of the ColonyRack package, we provide a vignette. This is a markdown document that serves as a pipeline model and the main runner script for the package. It contains embedded chunks of R code similar to a Jupyter Notebook.

To run or edit the vignette, follow the steps below:

Step 1: If you do not have Git installed, install it on your system. Open your terminal (or prompt on Windows) and type:

# You can also type this command in the terminal of RStudio
git clone https://github.com/WinterLab-Berlin/ColonyRack.git

Alternatively, you can download the package manually from the Git repository.

Step2: In the package repository, we provide a project file named ColonyRack.Rproj that sets up your working directory correctly. Open RStudio and import the project file. Alternatively, you can click on the project file, and RStudio will start and load the project automatically.

Step3: To edit, and run the vignette, go to the Files window in RStudio and open the vignettes directory in your project directory. You will find a file named meta_exploration.Rmd. Click on it to load the vignette in RStudio. Alternatively, navigate to the vignettes directory in your file explorer and open meta_exploration.Rmd in RStudio.

Project structure

The package contains the following main directories:

ColonyRack:
├───docs
├───inst
│   ├───figures
│   ├───metadata_age
│   ├───metadata_cage
│   └───rawdata
├───man
├───R
└───vignettes
    └───results       

Once you have followed the instructions in the Usage section and run all the cells in meta_exploration.Rmd, the cloned directory will be updated with new directories for the results. Here is an example of how your directory structure could look like:

ColonyRack:
├───docs
├───inst
│   ├───figures
│   ├───metadata_age
│   ├───metadata_cage
│   └───rawdata
├───man
├───R
└───vignettes
    └───results
        ├───csv
        │   ├───analyzed
        │   │   ├───distance
        │   │   ├───duration
        │   │   ├───speed
        │   │   ├───cage_visits
        │   │   └───spatial
        │   │
        │   ├───tour_processed
        │   │   └───All
        │   │       ├───<mouse id 1>
        │   │       │   ├───24hours
        │   │       │   │   ├───<date 1>.csv   
        │   │       │   │   ├───<date 2>.csv   
        │   │       │   │   └───...   
        │   │       │   │    
        │   │       │   └───Phases
        │   │       │       ├───<date 1>
        │   │       │       │   ├───dark.csv
        │   │       │       │   └───light.csv
        │   │       │       ├───<date 2>
        │   │       │       │   ├───dark.csv
        │   │       │       │   └───light.csv     
        │   │       │       └───...                                  
        │   │       │
        │   │       ├───<mouse id 2>
        │   │       │    ├───24hours
        │   │       │    │   ├───<date 1>.csv   
        │   │       │    │   ├───<date 2>.csv   
        │   │       │    │   └───...   
        │   │       │    │    
        │   │       │    └───Phases
        │   │       │        ├───<date 1>
        │   │       │        │   ├───dark.csv
        │   │       │        │   └───light.csv
        │   │       │        ├───<date 2>
        │   │       │        │   ├───dark.csv
        │   │       │        │   └───light.csv     
        │   │       │        └───...   
        │   │       └───...
        │   │
        │   └───tour_raw
        │       └───All
        │           ├───<mouse id 1>
        │           │   ├───24hours
        │           │   │   ├───<date 1>.csv   
        │           │   │   ├───<date 2>.csv   
        │           │   │   └───...   
        │           │   │    
        │           │   └───Phases
        │           │       ├───<date 1>
        │           │       │   ├───dark.csv
        │           │       │   └───light.csv
        │           │       ├───<date 2>
        │           │       │   ├───dark.csv
        │           │       │   └───light.csv     
        │           │       └───...                                  
        │           │
        │           ├───<mouse id 2>
        │           │   ├───24hours
        │           │   │   ├───<date 1>.csv   
        │           │   │   ├───<date 2>.csv   
        │           │   │   └───...   
        │           │   │    
        │           │   └───Phases
        │           │       ├───<date 1>
        │           │       │   ├───dark.csv
        │           │       │   └───light.csv
        │           │       ├───<date 2>
        │           │       │   ├───dark.csv
        │           │       │   └───light.csv     
        │           │       └───...   
        │           └───... 
        │
        └───jpg
            ├───distance
            ├───duration
            ├───speed
            ├───cage_visits
            └───spatial

A brief explanation of the relevant directories:

• inst - This directory stores all data files and has three subdirectories:

  • rawdata - This directory contains raw data files, which are measurements of mice activity collected via RFID readers. Each file contains 24 hours of data and is saved in CSV format. These files should not be changed or modified in any way.

  • metadata_cage - This subdirectory contains a CSV file that serves as a configuration file for cages. It includes the readers and their cage neighbors as adjacency lists. The file R/my_graph.R provides conventions and restrictions.

  • metadata_age - This subdirectory contains a CSV file that serves as a configuration file for mice age. It includes the mice IDs and their age as adjacency lists.

• R - This directory contains all custom functions required for the analysis. It includes four R scripts:

  • data_funcitons.R- Contains all necessary functions to run the analysis.
  • graph.R- Reads the adjacency list of the reader+cage neighborhood from the inst/metadata_cage directory and creates a graph (reader+cage neighborhood).
  • plots.R- Contains all plots functions.

• vignettes - This directory includes a single Rmarkdown file named meta_exploration.Rmd. It is a discursive document designed to illustrate and explain the package's features and functions. It also demonstrates how to use them properly. Additionally, there is a subdirectory for Results where analyzed data are stored according to the function. See the results section for more information.

Results

The analysis produces csv and jpg files that can be found in the vignettes/results directory. There are three types of csv files:

• tour_raw - Contains edited and intermediate manipulated data, which is a copy of the raw state of the final state.

• tour_processed - Contains the final and clean data used for analysis, with additional segments such as cage numbers, distance, duration, etc.

analyzed - Contains the filtered and analyzed data, organized into subdirectories for distance, duration, speed, cage visits, and spatial.

tour_raw and tour_processed results are automatically stored in subdirectories and separated for each mouse by the appropriate day/phase of occurrence.

Getting Help

R provides two functions, help() and ??, which give access to the documentation pages for R functions, data sets, and other objects. To access the package documentation functions, data sets, and other objects, use the command help(cleanRawData) or ??cleanRawData, for example.

To discover the vignette, use the browseVignettes() function. It displays the vignettes in your browser. Similarly, vignette() can be used to display a list of vignettes in text form. Here is an example code:

# devtools::install(build_vignettes = TRUE) # this might take a long time to run

# opens the vignette inside your RStudio in the help window tab.
vignette("meta_exploration", package="ColonyRack")

# Opens the vignette in your internet browser
# The vignette page provides three things: the original source file, a readable HTML page and a file of R code.
browseVignettes("ColonyRack")

If you encounter any problems using the library, you can always use the script independently. Navigate to vignettes and open meta_exploration.Rmd. At the top of the markdown, add the following:

source('R/data_functions.R')
source('R/my_graph.R')
source('R/Plots.R')

After importing the above scripts, you should be able to run meta_exploration.Rmd without any problem.

To remove the ColonyRack library from your system, you can use the following command in your R console:

remove.packages("ColonyRack")