Overview

Lipsia is a collection of tools for the analysis of functional magnetic resonance imaging (fMRI) data. Its primary focus lies in implementing novel algorithms, including laminar-specific fMRI analysis (cylarim), statistical inference (LISA), and Eigenvector centrality mapping (ECM). Lipsia is designed with a focus on compactness and ease of installation, making it readily accessible for researchers to incorporate these advanced analysis methods into their workflows.

Installation

Lipsia supports Linux and other operating systems via Singularity and Docker, see the files “singularity-recipe.txt” and/or “Dockerfile”. Follow the instructions here: Installation.

Lipsia file format

Lipsia uses its own data format, which is called vista (extension .v). Many lipsia programs also accept gzipped files or nifti-files as input (.v.gz or .nii.gz). The output is always in unzipped vista-format. You can easily convert your NIfTI data from and to lipsia with the program *vnifti:

vnifti -in data.nii -out data.v
vnifti -in data.nii.gz -out data.v
vnifti -in result.v -out result.nii

Getting started

Lipsia generally uses the “-in” parameter to specify input images and “-out” for output images. Many programs within Lipsia offer additional parameters, such as brain masks or thresholds, to fine-tune the analysis.

As an example, consider Eigenvector Centrality Mapping (ECM). To compute an ECM map, you would typically use the following command-line instruction:

vecm -in functional.nii.gz -mask brainmask.nii.gz -out ecm.v

This command processes the input fMRI data (functional.nii.gz) within the specified brain mask (brainmask.nii.gz) and generates an ECM map in the vista format (ecm.v).

To further process or visualize the ECM map with tools that may not support the vista format, you can convert it to NIfTI format using the following command:

vnifti -in ecm.v -out ecm.nii

Reference:

Lohmann, G. (2010), “Eigenvector centrality mapping for analyzing connectivity patterns in fMRI data of the human brain”: PLoS ONE, https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0010232>

Laminar-specific fMRI analysis (Cylarim) - under construction

Laminar-specific fMRI is implemented in several programs: vrim, vmetric, vcylarim and vcylarim_stats. The programs vrim and vmetric implement preparatory steps used for generating a rim image and a metric image. The program vcylarim expects as input an activation map, a rim image and a metric image. Optionally, a brain mask may be used to restrict the analysis to certain parts of the cortex. The rim image must have the following codes: 1(CSF-cortex boundary), 2:(WM-cortex boundary), 3: (cortex interior). These images may be generated by the software package LayNii. They can also be generated using the

The cylinder radius is specified using the parameter “-radius”. The output of vcylarim is a file containing the GLM coefficients. In a second step (cylarim_stats), this file is used to compute contrasts between the GLM coefficients.

Example usage:

vcylarim -in zmap.v -metric metric.v -mask mask.v -rim rim.v -radius 3 -out cylbeta.v

vcylarim_stats -in cylbeta.v -out result.v -type middle

Statistical inference (LISA) in examples:

Onesample test at the 2nd level (LISA onesample test (vlisa_onesample)). Example: the input is a set of contrast maps called “data_*.nii.gz”:

vlisa_onesample -in data_*.nii.gz -mask mask.nii -out result.v
vnifti -in result.v -out result.nii

Twosample test at the 2nd level (LISA twosample test (vlisa_twosample)). Example: input are two sets of contrast maps called “data1_*.nii.gz” and “data2_*.nii.gz”:

vlisa_twosample -in1 data1_*.nii.gz -in2 data2_*.nii.gz -mask mask.nii -out result.v
vnifti -in result.v -out result.nii

Single subject test (1st level) (LISA single subject analysis using prewhitening (vlisa_prewhitening)). Example: input are two runs acquired in the same session called “run1.nii.gz” and “run2.nii.gz”.

vlisa_prewhitening -in run1.nii.gz run2.nii.gz -design des1.txt des2.txt -mask mask.nii -out result.v vnifti -in result.v -out result.nii

Note: preprocessing should include a correction for baseline drifts:

*Reference:*

Lohmann et al (2018) “LISA improves statistical analysis for fMRI”, Nature Comm, https://www.nature.com/articles/s41467-018-06304-z