Load libraries

Install WormTensor package from CRAN or GitHub in advance and then type the code below in the R console window.

library(WormTensor)

worm_download

worm_download is a function to retrieve data from figshare for a total of 28 animals (24 normal and 4 noisy). If there is no argument, mSBD distance matrices (including 24 normal animals) will be downloaded.

object <- worm_download()

as_worm_tensor

as_worm_tensor is a function to generate a WormTensor object from distance matrices. A WormTensor object S4 class is used by worm_membership, worm_clustering, worm_evaluate, and worm_visualize.

object <- as_worm_tensor(object$Ds)

worm_membership

worm_membership is a function to generate a membership tensor from a WormTensor object with distance matrices. Set the assumed number of clusters to k(>=2).

object <- worm_membership(object, k=6)

worm_clustering

worm_clustering is a function to generate a clustering result from a WormTensor object with a membership tensor.

object <- worm_clustering(object)

worm_evaluate

worm_evaluate is a function to generate an evaluation result from a WormTensor object with a worm_clustering result.

object <- worm_evaluate(object)

worm_visualizeworm_visualize`is a function to visualize`worm_clustering`and`worm_evaluate` results.

object <- worm_visualize(object)
#> Warning: Using `size` aesthetic for lines was deprecated in ggplot2 3.4.0.
#> ℹ Please use `linewidth` instead.
#> ℹ The deprecated feature was likely used in the WormTensor package.
#>   Please report the issue at <https://github.com/rikenbit/WormTensor/issues>.
#> This warning is displayed once per session.
#> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
#> generated.

Figure1a : Silhouette plots

Figure1b : Dimensional reduction Plots colored by cluster

Figure1c : Dimensional reduction Plots colored by no. of identified cells

Figure1d : ARI with a merge result and each animal(with MCMI)

Pipe Operation

The above functions can also be run by connecting them with R’s native pipe.

worm_download()$Ds |>
    as_worm_tensor() |>
        worm_membership(k=6) |>
            worm_clustering() |>
                worm_evaluate() |>
                    worm_visualize() -> object

Pipe Operation (with Labels)

If you have a label for the cells, you can use it for external evaluation.

# Sample Labels
worm_download()$Ds |>
    as_worm_tensor() |>
        worm_membership(k=6) |>
            worm_clustering() -> object
labels <- list(
    label1 = sample(3, length(object@clustering), replace=TRUE),
    label2 = sample(4, length(object@clustering), replace=TRUE),
    label3 = sample(5, length(object@clustering), replace=TRUE))
# WormTensor (with Labels)
worm_download()$Ds |>
    as_worm_tensor() |>
        worm_membership(k=6) |>
            worm_clustering() |>
                worm_evaluate(labels) |>
                    worm_visualize() -> object_labels

Figure2a : Silhouette plots

Figure2b : Dimensional reduction Plots colored by cluster

Figure2c : Dimensional reduction Plots colored by no. of identified cells

Figure2d : ARI with a merge result and each animal(with MCMI)

Figure2e : Dimensional reduction Plots colored by label

Figure2f : Consistency of labels and cluster members

worm_distance

worm_distance helps you analyze your time-series data matrices with WormTensor. worm_distance is a function to convert time-series data matrices into distance matrices. The distance matrices can be used for analysis by WormTensor.

# Toy data (data of 3 animals)
n_cell_x <- 13
n_cell_y <- 24
n_cell_z <- 29
n_cells <- 30
n_time_frames <- 100

# animal_x : 13 cells, 100 time frames
animal_x <- matrix(runif(n_cell_x*n_time_frames),
    nrow=n_cell_x, ncol=n_time_frames)
rownames(animal_x) <- sample(seq(n_cells), n_cell_x)
colnames(animal_x) <- seq(n_time_frames)

# animal_y : 24 cells, 100 time frames
animal_y <- matrix(runif(n_cell_y*n_time_frames),
    nrow=n_cell_y, ncol=n_time_frames)
rownames(animal_y) <- sample(seq(n_cells), n_cell_y)
colnames(animal_y) <- seq(n_time_frames)

# animal_z : 29 cells, 100 time frames
animal_z <- matrix(runif(n_cell_z*n_time_frames),
    nrow=n_cell_z, ncol=n_time_frames)
rownames(animal_z) <- sample(seq(n_cells), n_cell_z)
colnames(animal_z) <- seq(n_time_frames)

# Input list for worm_distnce
X <- list(animal_x=animal_x,
    animal_y=animal_y,
    animal_z=animal_z)

# Pipe Operation
# tsne.perplexity must be adjusted for data size
worm_distance(X, "mSBD") |>
    as_worm_tensor() |>
        worm_membership(k=6) |>
            worm_clustering() |>
                worm_evaluate() |>
                    worm_visualize(tsne.perplexity=5) -> object

Session Information

#> R version 4.6.0 (2026-04-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.4 LTS
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#>  [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: Etc/UTC
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] WormTensor_0.1.2 rmarkdown_2.31  
#> 
#> loaded via a namespace (and not attached):
#>  [1] ade4_1.7-24           tidyselect_1.2.1      viridisLite_0.4.3    
#>  [4] dplyr_1.2.1           farver_2.1.2          S7_0.2.2             
#>  [7] fastmap_1.2.0         promises_1.5.0        shinyjs_2.1.1        
#> [10] digest_0.6.39         mime_0.13             lifecycle_1.0.5      
#> [13] factoextra_2.0.0      cluster_2.1.8.2       magrittr_2.0.5       
#> [16] compiler_4.6.0        rlang_1.2.0           sass_0.4.10          
#> [19] tools_4.6.0           yaml_2.3.12           knitr_1.51           
#> [22] ggsignif_0.6.4        labeling_0.4.3        plyr_1.8.9           
#> [25] RColorBrewer_1.1-3    abind_1.4-8           Rtsne_0.17           
#> [28] withr_3.0.2           purrr_1.2.2           sys_3.4.3            
#> [31] grid_4.6.0            stats4_4.6.0          ggpubr_0.6.3         
#> [34] xtable_1.8-8          e1071_1.7-17          aricode_1.0.3        
#> [37] ggplot2_4.0.3         scales_1.4.0          iterators_1.0.14     
#> [40] MASS_7.3-65           cli_3.6.6             generics_0.1.4       
#> [43] otel_0.2.0            RcppParallel_5.1.11-2 RSpectra_0.16-2      
#> [46] reshape2_1.4.5        usedist_0.4.0         cachem_1.1.0         
#> [49] proxy_0.4-29          stringr_1.6.0         splines_4.6.0        
#> [52] modeltools_0.2-24     parallel_4.6.0        clValid_0.7          
#> [55] vctrs_0.7.3           Matrix_1.7-5          carData_3.0-6        
#> [58] jsonlite_2.0.0        car_3.1-5             ggrepel_0.9.8        
#> [61] rstatix_0.7.3         Formula_1.2-5         clue_0.3-68          
#> [64] maketools_1.3.2       foreach_1.5.2         jquerylib_0.1.4      
#> [67] tidyr_1.3.2           glue_1.8.1            dtw_1.23-2           
#> [70] codetools_0.2-20      cowplot_1.2.0         flexclust_1.5.0      
#> [73] uwot_0.2.4            stringi_1.8.7         gtable_0.3.6         
#> [76] rTensor_1.5.0         later_1.4.8           tibble_3.3.1         
#> [79] pillar_1.11.1         htmltools_0.5.9       clusterSim_0.51-6    
#> [82] R6_2.6.1              evaluate_1.0.5        shiny_1.13.0         
#> [85] lattice_0.22-9        backports_1.5.1       dtwclust_6.0.0       
#> [88] broom_1.0.12          httpuv_1.6.17         bslib_0.10.0         
#> [91] class_7.3-23          Rcpp_1.1.1-1.1        nlme_3.1-169         
#> [94] mgcv_1.9-4            xfun_0.57             buildtools_1.0.0     
#> [97] pkgconfig_2.0.3

Clustering and visualization of time-series whole-brain activity data of C. elegans using WormTensor