calipR

Project Status: Active Licence CRAN_Status_Badge packageversion

A Calcium Imaging Data Analysis Pipeline in R

calipR is a free and open source software dedicated to calcium imaging data analysis. It is fully coded in R and is distributed as an R package, a standalone windows application, a docker image.

Key Features

Project Goals

Important Notes

Option 1 : Windows Application Installation (recommended)

To install the Graphical User Interface (GUI) based version for windows, you only need to download and execute the last version of the calipR.exe file available in the release section. Once installed, just run the program and start your data analysis!

Note that if you want to interact with the package by coding, there is an embedded R version in the installation folder with all necessary packages + calipR.

Option 2 : Docker image downloading (recommended for macOS and linux)

For macOS and linux users, the best way to use calipR is from its docker image. The calipr_base image contains all the necessary packages to run calipR + calipR itself. Since it is not installed in your global environment, it will prevent any installation errors.

The very first thing you need is to download docker through : https://docs.docker.com/get-docker/.

Once Docker is installed, just open the docker desktop application (it needs to be open for the docker commands to work). Then open your command terminal and type the following to download the calipr_base v1.0.0-alpha docker image (or any other available version):

docker pull etrives/calipr_base:v1.0.0-alpha

calipR needs to take inputs from and write outputs into your local machine. In the following command, you need to replace the path with your true absolute path to a folder which contains the folder containing your data (every output generated by calipR like projects created, sql database, banks and results outputs will be written to this destination folder):

docker run --rm -it -p 3838:3838 -v c:/replace/by/absolute/path/to/folder/containing/data/:/inst -t etrives/calipr_base:v1.0.0-alpha

This will open an R session in your command terminal. You then need to load the calipR package:

library(calipR)

To use the graphical user interface type :

shiny::runApp(guigui(), host = '0.0.0.0', port = 3838)

To access the interface, go to : http://localhost:3838/

Option 3 : R package Installation

Warning : calipR currently has a lot of dependencies so this option may cause dependency errors while installing (see the troubleshooting section below if it happens). Before trying the following commands, make sure you have the admin rights.

You can download the latest version from r-universe


install.packages('calipR', repos = c('https://etrives.r-universe.dev', 'https://cloud.r-project.org'))

or from github with devtools

# Install devtools if necessary
if (!require("devtools")) install.packages("devtools")

#load devtools
library(devtools)

#install calipR from github
install_github("ETrives/calipR")

if you want to install a specific version

# Install devtools if necessary
if (!require("devtools")) install.packages("devtools")

#load devtools
library(devtools)

#Install calipR version v1.0.0-alpha
install_github("ETrives/calipR@v1.0.0-alpha")

Troubleshooting option 3 Installation

MacOS

You lack a software to build packages with compiled code

During calipR installation, a window should open and say you don’t have this software and ask you if you want to install it. Say Yes ! it is necessary. After being installed, launch again calipR installation through devtools or r-universe.

if the window doesn’t show up or if you want to install it by your self, the software you need is Xcode Command Line Tools. To install it, open your command terminal, type the following and press enter :

xcode-select --install
Installation successfull but GUI not working : X11 library is missing : install xquartz

You may succeed the installation step but encounter this error when trying to use calipR’s graphical user interface. On macOS you need to install xquartz from here after downloading and installing XQuartz, the application should work correctly.

Windows

You lack a software to build packages with compiled code

if you use Rstudio, during calipR installation, a window will open and tell you don’t have this software and ask you if you want to install it. Say Yes ! it is necessary. After being installed, launch again calipR installation through devtools or r-universe.

if you don’t use Rstudio or want to install it by your self, RTools is the software you need if you work on a PC. Be careful, you need to install an RTools version which matches your R version. So if you have R 4.3, you should install RTools 4.3

OS independent :

If you encounter package dependency issues and you want to go for a radical option you can either :

update your R packages

update.packages(ask = FALSE, checkBuilt = TRUE)

Delete R and the associated packages and download a fresh R this might help

# In your fresh R session install devtools
install.packages("devtools")

# Then install calipR from github
install_github("ETrives/calipR")
    
# Or from r-universe
install.packages('calipR', repos = c('https://etrives.r-universe.dev', 'https://cloud.r-project.org'))

Research using calipR

Preparing a correct Input for calipR

Fluorescence Data

calipR v1.0.0 starts the analysis workflow after the cell detection step. So you first need to do cell detection by yourself and end up with a csv file that can be of two different types :

meta.csv

You need to create a .csv file containing the meta data in two columns, with dimensions (coverslip_number * stimulus_number)*2 :

The meta data for all animals/groups/coverslips should be placed in one single meta.csv file. calipR takes each fluorescence data file in order. Each new coverslip meta data should be placed in line, below the previous one (eg. if 2 coverslips and 4 stimuli/coverslip, then your file has 8 lines and 2 columns)

marker.csv (optional)

This file is optional. It is a .csv file with dimensions 1*cell number. Each column contains one fluorescence value corresponding to the fluorescent reporter or IHC staining, on the same field of the corresponding recording. This data is used to attribute a molecular identity to recorded cells. You can enter your threshold value in the GUI when loading the data into calipR.

Folder Organization


├───Folder_Name               # Type the Path to this main folder to load data
│   ├───Group1
│   │   └───Individual1
│   │       └───1.csv         # Fluorescence data -- coverslip 1 Animal 1
│   │       └───2.csv         # Fluorescence data -- coverslip 2 Animal 1
│   │       └───marker1.csv
│   │       └───marker2.csv
│   │   └───Individual2
│   │       └───1.csv
│   │       └───2.csv
│   │       └───marker1.csv
│   │       └───marker2.csv
│   └───meta.csv              # Meta data file with stimulus and timing informations

Folder localisation

You first need to find the path where calipR was installed. The previously described folder containing your data should be placed in the installation folder of calipR as follows: calipR/shiny/data/your_folder.

Starting your Analysis

CalipR allows to manage several projects. When starting a new analysis project, you need to tick “create project”, give it a unique name, provide the path to the data (data/your_folder_name) and the acquisition rate. If you formated your data as in the “long format” above description, you should tick “ROI detection with trackmate” otherwise leave empty. By clicking “load and tidy data”, a new folder is created with your project name in calipR/shiny/projects. Inside each project folder, the loaded data is stored as an SQLite database. In your future sessions, you can directly start with “load existing project” by ticking this option and providing an existing project name. All the results of your analysis will be stored as a tab in the SQLite file and the banks you will create will be stored in the project folder as RDS files. So once a result has been generated or a bank has been created (and saved!), you can safely close the App, everything is in this folder and will be reloaded when loading an existing project.