Introduction

Understanding the conservation of gene neighborhoods across species provides important insights into genome organization, functional linkage, and evolutionary processes. geneClusterPattern is a package developed to facilitate the systematic characterization of orthologous gene arrangements surrounding a focal gene across multiple species.

Given a gene of interest, the package supports two complementary strategies to define orthology relationships. It can retrieve homologous genes directly from Ensembl (via Compara), or it can incorporate user-provided ortholog group assignments generated by OrthoFinder. These flexible input options allow users to integrate gene homology information from widely used comparative genomics pipelines.

Based on the orthology information, geneClusterPattern constructs an ordered representation of genes within a configurable genomic window upstream and downstream of the focal gene. The resulting ortholog gene pattern captures the relative arrangement of ortholog groups across species, enabling direct comparison of local genomic structure.

This framework is particularly useful for investigating conserved synteny, identifying lineage-specific rearrangements, and exploring the evolutionary stability of gene clusters. The package outputs are designed to be analysis- and visualization-friendly, supporting downstream statistical analysis and graphical representation of gene neighborhood conservation.

Installation

if (!require("BiocManager", quietly = TRUE)) {
    install.packages("BiocManager")
}
BiocManager::install('geneClusterPattern')
# or install from github
BiocManager::install('jianhong/geneClusterPattern')

Quick start

There are main steps to create the gene cluster pattern for a given gene.

Step 1. Load the required libraries.

Step 2. Prepare homolog information for the reference species. Homologs can be retrieved from the Ensembl database or obtained from ortholog group assignments. In this example, we use a pre-saved homolog dataset downloaded from Ensembl.

Step 3. Define the gene cluster.

Step 4. Visualize the gene cluster.

## load library
library(geneClusterPattern)
library(org.Dr.eg.db)
library(GenomeInfoDb)
## prepare all the ensembl ids
ids <- as.list(org.Dr.egENSEMBL)
ensembl_gene_ids <- sort(unique(unlist(ids)))
## extract gene information via biomaRt
fish_mart <- guessSpecies('zebrafish', output='mart', version=112)
fish <- grangesFromEnsemblIDs(mart = fish_mart,
                              ensembl_gene_ids = ensembl_gene_ids)
## if failed, try load presaved data
# fish <- readRDS(system.file('extdata', 'fish.rds',
#                             package = 'geneClusterPattern'))
## subset the ensembl_gene_ids to save time
ensembl_gene_ids <- names(fish[seqnames(fish)=='24'])
## keep the standard sequence only
fish <- pruningSequences(fish)
## define the species scientific name
species <- guessSpecies(c('human', 'house mouse', 'Japanese medaka', 'turquoise killifish', 'gaculeatus'), version=112) # three-spined stickleback
species
## [1] "hsapiens"   "mmusculus"  "olatipes"   "nfurzeri"   "gaculeatus"
## retrieve homologs from Ensembl
homologs <- getHomologGeneList(species, fish_mart, ensembl_gene_ids)
homologs <- pruningSequences(homologs)
## if failed, try to load pre-saved data
# homologs <- readRDS(system.file('extdata', 'homologs.rds',
#                                 package = 'geneClusterPattern'))
## get gene cluster for target gene
queryGene <- 'pcolce2b'
## define the gene cluster
nearest10neighbors <- getGeneCluster(fish, queryGene, homologs, k=10)

## prepare the gene annotations for all homologs for plot
genesList <- c(drerio=fish, homologs)[
  c("hsapiens", "mmusculus", "drerio", "olatipes", "nfurzeri", "gaculeatus")]

## plot the cluster
pgp <- plotGeneClusterPatterns(genesList, nearest10neighbors)

The plot consists of two panels. The top panel shows the Gene Pattern plot, while the bottom panel displays the actual genomic coordinates of the genes in the cluster for each species. By default, the reference gene is positioned at the center of the plot. Homologous genes across different species are displayed using the same fill color.

In the Gene Pattern plot, gene lengths are shown schematically rather than to scale, making the gene order and orientation easier to visualize. In contrast, the genomic tracks in the bottom panel represent the true genomic coordinates and actual gene lengths.

From OrthoFinder results

Homolog information can also be obtained from ortholog group assignments. For example, you can start from the orthogroup table generated by OrthoFinder, which groups homologous genes across multiple species into orthologous groups. These group assignments can be used directly as input for downstream gene cluster analysis.

## import the ortholog groups
path <- system.file('extdata/orthofinder/Danio_rerio.GRCz11.pep.all.tsv.gz',
                    package='geneClusterPattern')
orthologs <- orthologPairsFromOrthoFinder(path)
## annotations
annoGR_list <- readRDS(
    system.file('extdata/orthofinder/grange.obj.rds',
                 package='geneClusterPattern'))
## reformat to meet the requirement of the package
homologs <- getHomologListForOrthoFinder(orthologs, annoGR_list[-1])
## set reference species
queryGR <- annoGR_list[["Danio rerio"]]
## define the gene cluster
nearest10neighbors <- getGeneCluster(queryGR, queryGene, homologs, k=10)
pgp <- plotGeneClusterPatterns(c('zebrafish'=queryGR, homologs),
                               nearest10neighbors)

Session Info

sessionInfo()

R version 4.6.1 (2026-06-24) Platform: x86_64-pc-linux-gnu Running under: Ubuntu 24.04.4 LTS

Matrix products: default BLAS: /home/biocbuild/bbs-3.24-bioc/R/lib/libRblas.so LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0 LAPACK version 3.12.0

locale: [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
[3] LC_TIME=en_GB LC_COLLATE=C
[5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
[7] LC_PAPER=en_US.UTF-8 LC_NAME=C
[9] LC_ADDRESS=C LC_TELEPHONE=C
[11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C

time zone: America/New_York tzcode source: system (glibc)

attached base packages: [1] stats4 stats graphics grDevices utils datasets methods
[8] base

other attached packages: [1] GenomeInfoDb_1.49.1 Seqinfo_1.3.2
[3] geneClusterPattern_0.99.2 org.Dr.eg.db_3.22.0
[5] AnnotationDbi_1.75.2 IRanges_2.47.5
[7] S4Vectors_0.51.10 Biobase_2.73.2
[9] BiocGenerics_0.59.12 generics_0.1.4

loaded via a namespace (and not attached): [1] DBI_1.3.0 bitops_1.1-0
[3] httr2_1.3.0 biomaRt_2.69.2
[5] rlang_1.3.0 magrittr_2.0.5
[7] otel_0.2.0 matrixStats_1.5.0
[9] compiler_4.6.1 RSQLite_3.53.3
[11] GenomicFeatures_1.65.0 png_0.1-9
[13] vctrs_0.7.3 txdbmaker_1.9.0
[15] stringr_1.6.0 pwalign_1.9.1
[17] pkgconfig_2.0.3 crayon_1.5.3
[19] fastmap_1.2.0 dbplyr_2.6.0
[21] XVector_0.53.0 trackViewer_1.49.2
[23] Rsamtools_2.29.0 rmarkdown_2.32
[25] UCSC.utils_1.9.0 strawr_0.0.92
[27] bit_4.6.0 xfun_0.61
[29] cachem_1.1.0 cigarillo_1.3.1
[31] jsonlite_2.0.0 progress_1.2.3
[33] blob_1.3.0 rhdf5filters_1.25.4
[35] DelayedArray_0.39.6 Rhdf5lib_2.1.0
[37] BiocParallel_1.47.0 parallel_4.6.1
[39] prettyunits_1.2.0 R6_2.6.1
[41] bslib_0.12.0 stringi_1.8.9
[43] RColorBrewer_1.1-3 rtracklayer_1.73.0
[45] GenomicRanges_1.65.4 jquerylib_0.1.4
[47] Rcpp_1.1.2 SummarizedExperiment_1.43.0 [49] knitr_1.52 BiocBaseUtils_1.15.1
[51] Matrix_1.7-6 tidyselect_1.2.1
[53] dichromat_2.0-1 abind_1.4-8
[55] yaml_2.3.12 codetools_0.2-20
[57] curl_8.0.0 lattice_0.23-1
[59] tibble_3.3.1 InteractionSet_1.41.0
[61] KEGGREST_1.53.6 evaluate_1.0.5
[63] BiocFileCache_3.3.0 Biostrings_2.81.9
[65] pillar_1.11.1 BiocManager_1.30.27
[67] filelock_1.0.3 MatrixGenerics_1.25.0
[69] RCurl_1.98-1.20 hms_1.1.4
[71] scales_1.4.0 BiocStyle_2.41.0
[73] grImport_0.9-7 glue_1.8.1
[75] tools_4.6.1 BiocIO_1.23.3
[77] GenomicAlignments_1.49.2 RANN_2.6.3
[79] XML_3.99-0.24 rhdf5_2.57.15
[81] grid_4.6.1 restfulr_0.0.17
[83] cli_3.6.6 S4Arrays_1.13.0
[85] dplyr_1.2.1 sass_0.4.10
[87] digest_0.6.39 SparseArray_1.13.2
[89] rjson_0.2.23 htmlwidgets_1.6.4
[91] farver_2.1.2 memoise_2.0.1
[93] htmltools_0.5.9 lifecycle_1.0.5
[95] httr_1.4.9 bit64_4.8.6