Skip to contents

NEBULA

NEBULA is an R package designed to analyze genotype-phenotype associations between SNPs within SNP-sets.

🚀 Installation

Install from GitLab

You can install NEBULA directly from GitLab using the following commands:

library(devtools)
install_gitlab("sysbiobig/nebula", build_opts = c("--no-resave-data", "--no-manual"), build_vignettes = TRUE)

This command installs NEBULA along with its dependencies and builds the vignettes for detailed usage examples. If you prefer to skip vignette building, use:

library(devtools)
install_gitlab("sysbiobig/nebula")

📦 Run with container

Prerequisites

Ensure the following tools are installed:

Build Docker image

Use the provided Dockerfile (in the /docker directory) to build the image:

docker build -t nebula .

Run Docker container 

docker run -v $(pwd)/data:/data \
           -v $(pwd)/output:/output \
           -ti nebula \
           Rscript <your_script.R>

This mounts the data and output directories into the container and executes your R script using NEBULA.

Note for Linux users: To run Docker without sudo, follow the post-installation steps.

Run Singularity container (suggested)

If you’re using a high-performance computing cluster, you can run NEBULA via Singularity.

We provide a pre-built Singularity image nebula.sif. To execute your script:

singularity exec --bind $(pwd)/data:/data \
                 --bind $(pwd)/output:/output \
                 nebula.sif \
                 Rscript <your_script.R>

📖 Getting Started

Access the package vignettes for tutorials and examples:

library(nebula)
browseVignettes("nebula")

Usage Examples

Input data

The genotype data must be provided in PLINK binary format (.bed, .bim, .fam). Pass the full path without the file extension as root_file_name.

SNP-sets

SNP-sets group SNPs by biological or functional relevance. NEBULA requires:

  • A directory containing one tab-delimited file per SNP-set.
  • A tab-delimited list file with one row per SNP-set in the form: SNP_SET_NAME<TAB>NUMBER_OF_SNPS.

Each SNP-set file must be named <SNP_SET_NAME>.txt and must contain 3 tab-delimited columns with no header:

  1. SNP ID
  2. chromosome
  3. base-pair position

Example SNP-set file (snpsets/gene_BRCA1.txt):

rs123 [TAB] 17 [TAB] 43044295
rs456 [TAB] 17 [TAB] 43047654
rs789 [TAB] 17 [TAB] 43049122

Example list file (snpset_list.txt):

gene_BRCA1 [TAB] 3
gene_TP53 [TAB] 2

Example layout:

snpsets/
  gene_BRCA1.txt
  gene_TP53.txt
snpset_list.txt

The SNP IDs in the first column of each SNP-set file must match the SNP IDs in the PLINK .bim file.

Generating synthetic data (no download required)

You can test the full pipeline without any external files using NEBULA’s built-in simulation functions:

library(nebula)

root_folder <- "/path/to/project"   # directory where files will be saved

# 1. Simulate synthetic genotype data
synthetic_data <- nebula::simulate_synthetic_genotype(
  n_snps         = 10,   # total number of SNPs
  n_individuals  = 10,   # number of individuals
  n_causal_snps  = 2     # number of causal SNPs
)
head(synthetic_data)

# 2. Save as PLINK-compatible files (.bed / .bim / .fam)
nebula::save_synthetic_genotype(
  synthetic_data,
  file = file.path(root_folder, "synthetic_genotype")
)

# 3. Generate synthetic SNP-sets from the .bim file
nebula::generate_synthetic_snpsets(
  input_file   = paste0(root_folder, "/synthetic_genotype.bim"),
  snps_per_set = 10,
  num_sets     = 10,
  root_dir     = root_folder
)

This creates:

  • a SNP-set directory at file.path(root_folder, "simulation_10snp")
  • a list file at file.path(root_folder, "simulation_10snp_snpsetlist.txt")

Running the NEBULA analysis 

library(nebula)

root_folder <- "/path/to/project"
res_folder  <- file.path(root_folder, "results")

# Step 1 – compute the null hypothesis distribution
nebula::compute_null_hypothesis(
  root_file_name  = file.path(root_folder, "synthetic_genotype"),
  pathpathways    = file.path(root_folder, "simulation_10snp"),
  pathwaylistfile = file.path(root_folder, "simulation_10snp_snpsetlist.txt"),
  nullhypmsfile   = file.path(res_folder,  "null_ms.txt"),
  nullhyps2file   = file.path(res_folder,  "null_s2.txt"),
  seed        = 1,
  B           = -1,
  alpha       = 0.05,
  min_snps    = 2,
  max_snps    = 999999,
  N_cores     = 6,
  n_rows      = 10,
  verbosity   = 0,
  mode        = 0,
  implementation = 0
)

# Step 2 – compute SNP-set associations
results <- nebula::compute_association(
  root_file_name  = file.path(root_folder, "synthetic_genotype"),
  pathpathways    = file.path(root_folder, "simulation_10snp"),
  pathwaylistfile = file.path(root_folder, "simulation_10snp_snpsetlist.txt"),
  nullhypmsfile   = file.path(res_folder,  "null_ms.txt"),
  nullhyps2file   = file.path(res_folder,  "null_s2.txt"),
  alpha       = 0.05,
  B           = -1,
  out_selected    = file.path(res_folder,  "association_results.txt"),
  min_snps    = 2,
  max_snps    = 999999,
  N_cores     = 6,
  n_rows      = 5000,
  verbosity   = 0,
  mode        = 0,
  association_mode = "MAX"
)

# Step 3 – correct for multiple hypothesis testing (BH / BY)
corrected_results <- nebula::correct_association(
  results,
  GRCh        = "38",
  output_path = res_folder
)

🥾 Reporting Issues

If you encounter bugs or have feature requests, please open an issue.

📜 License

NEBULA is released under the GNU General Public License v3.0. See the LICENSE file for details.

👥 Authors and Contact

  1. Department of Information Engineering, University of Padova, Italy
  2. Department of Comparative Biomedicine and Food Science, University of Padova, Italy