s-jSDM

A scalable and fast method for estimating joint Species Distribution Models (jSDMs) for big community data, including eDNA data.
https://github.com/theoreticalecology/s-jsdm

Category: Biosphere
Sub Category: Species Distribution Modeling

Keywords

deep-learning gpu-acceleration machine-learning species-distribution-modelling species-interactions

Last synced: about 22 hours ago
JSON representation

Repository metadata

Scalable joint species distribution modeling

README.md


output: github_document

Project Status: Active -- The project has reached a stable, usable state and is being actively developed. License: GPL v3 CRAN_Status_Badge R-CMD-check Publication

s-jSDM - Fast and accurate Joint Species Distribution Modeling

About sjSDM

The sjSDM package is an R package for estimating joint species distribution models. A jSDM is a GLMM that models a multivariate (i.e. a many-species) response to the environment, space and a covariance term that models conditional (on the other terms) correlations between the outputs (i.e. species).

image

A big challenge in jSDM implementation is computational speed. The goal of the sjSDM (which stands for "scalable joint species distribution models") is to make jSDM computations fast and scalable. Unlike many other packages, which use a latent-variable approximation to make estimating jSDMs faster, sjSDM fits a full covariance matrix in the likelihood, which is, however, numerically approximated via simulations. The method is described in Pichler & Hartig (2021) A new joint species distribution model for faster and more accurate inference of species associations from big community data, https://www.doi.org/10.1111/2041-210X.13687.

Since version 1.1.0 the core code of sjSDM is implemented in R on top of torch (libtorch). Earlier versions wrapped a Python / PyTorch backend through reticulate; that is gone, and with it the need for python, conda and a separate PyTorch installation. Model code runs unchanged, but results differ from 1.0.x: the default optimizer is now Adam() (sjSDMControl(optimizer = RMSprop()) restores the old one), predict() returns marginal predictions, and anova() and Rsquared() results change because several defects were fixed. See news(package = "sjSDM").

To get citation info for sjSDM when you use it for your reseach, type

citation("sjSDM")

Installing the R package

sjSDM is distributed via CRAN. For most users, it will be best to install the package from CRAN

install.packages("sjSDM")

The only dependency that is not an ordinary R package is the libtorch binary, which torch downloads on first use. If that has not happened yet, run

sjSDM::install_sjSDM()   # wrapper around torch::install_torch()

There is no separate CPU and GPU build any more: whether the GPU can be used follows from the torch installation (torch::cuda_is_available(), or torch::backends_mps_is_available() on Apple silicon). Pass device = "gpu" or device = "mps" to sjSDM() to use it.

For advanced users: if you want to install the current (development) version from this repository, run

devtools::install_github("https://github.com/TheoreticalEcology/s-jSDM", subdir = "sjSDM", ref = "master")

If the installation fails, check out the help of ?install_sjSDM and ?installation_help.

  1. Run sjSDM::install_diagnostic() and check whether libtorch is installed
  2. If not, run torch::install_torch() and restart R
  3. If you still do not get the pkg to run, create an issue on the issue tracker or write an email to maximilian.pichler at ur.de

Basic Workflow

Load the package

library(sjSDM)

Simulate some community data

set.seed(42)
community <- simulate_SDM(sites = 100, species = 10, env = 3)
Env <- community$env_weights
Occ <- community$response
SP <- matrix(rnorm(200, 0, 0.3), 100, 2) # spatial coordinates (no effect on species occurences)

This fits the standard SDM with environmental, spatial and covariance terms

model <- sjSDM(Y = Occ, env = linear(data = Env, formula = ~X1+X2+X3), spatial = linear(data = SP, formula = ~0+X1:X2), se = TRUE, family=binomial("probit"), sampling = 100L, verbose = FALSE)
summary(model)
## Family:  binomial 
## 
## LogLik:  -497.2144 
## Regularization loss:  0 
## 
## Species-species correlation matrix: 
## 
## 	sp1	 1.0000									
## 	sp2	 0.6820	 1.0000								
## 	sp3	 0.6730	 0.5890	 1.0000							
## 	sp4	-0.2840	-0.4660	-0.4360	 1.0000						
## 	sp5	 0.4090	 0.5100	 0.2880	-0.4000	 1.0000					
## 	sp6	 0.4020	 0.3400	 0.5710	-0.2850	 0.3540	 1.0000				
## 	sp7	 0.1360	-0.0520	 0.4840	-0.2290	 0.0950	 0.5180	 1.0000			
## 	sp8	 0.0410	 0.0520	-0.2300	 0.2600	-0.2730	-0.4100	-0.5610	 1.0000		
## 	sp9	-0.4050	-0.0030	-0.0850	-0.2170	 0.0430	 0.0400	 0.0520	-0.2240	 1.0000	
## 	sp10	 0.3360	 0.4290	 0.5850	-0.2930	 0.0450	 0.3740	 0.2800	-0.0860	 0.1390	 1.0000
## 
## 
## 
## Spatial: 
##             sp1        sp2       sp3       sp4       sp5      sp6      sp7
## X1:X2 0.3514133 -0.8500652 -1.957628 0.5300332 0.7929875 1.074655 1.609042
##            sp8       sp9      sp10
## X1:X2 0.450536 -2.314983 0.4139834
## 
## 
## 
##                  Estimate Std.Err Z value Pr(>|z|)    
## sp1 (Intercept)   -0.2027  0.3024   -0.67  0.50262    
## sp1 X1             1.0651  0.5788    1.84  0.06573 .  
## sp1 X2             1.8100  0.5174    3.50  0.00047 ***
## sp1 X3             1.3130  0.5048    2.60  0.00929 ** 
## sp2 (Intercept)   -0.5442  0.2949   -1.84  0.06504 .  
## sp2 X1             1.4173  0.5605    2.53  0.01145 *  
## sp2 X2             1.0692  0.5166    2.07  0.03846 *  
## sp2 X3            -0.9501  0.5094   -1.87  0.06217 .  
## sp3 (Intercept)   -0.1459  0.2686   -0.54  0.58710    
## sp3 X1            -1.1306  0.4906   -2.30  0.02119 *  
## sp3 X2            -0.3583  0.4502   -0.80  0.42610    
## sp3 X3             1.5558  0.4687    3.32  0.00090 ***
## sp4 (Intercept)    0.3756  0.1839    2.04  0.04107 *  
## sp4 X1            -1.4691  0.3672   -4.00  6.3e-05 ***
## sp4 X2             0.6849  0.3107    2.20  0.02751 *  
## sp4 X3             0.4500  0.3135    1.44  0.15118    
## sp5 (Intercept)   -0.5160  0.2164   -2.38  0.01712 *  
## sp5 X1            -1.3180  0.4068   -3.24  0.00120 ** 
## sp5 X2            -0.9073  0.3657   -2.48  0.01310 *  
## sp5 X3             0.5397  0.3702    1.46  0.14484    
## sp6 (Intercept)    0.1168  0.2045    0.57  0.56797    
## sp6 X1             0.2329  0.3865    0.60  0.54673    
## sp6 X2             1.5486  0.3726    4.16  3.2e-05 ***
## sp6 X3             1.2412  0.3717    3.34  0.00084 ***
## sp7 (Intercept)    0.0194  0.2353    0.08  0.93412    
## sp7 X1             0.8847  0.4299    2.06  0.03961 *  
## sp7 X2             0.7401  0.4029    1.84  0.06624 .  
## sp7 X3            -1.0197  0.4238   -2.41  0.01611 *  
## sp8 (Intercept)    0.2507  0.2069    1.21  0.22575    
## sp8 X1            -1.3380  0.4027   -3.32  0.00089 ***
## sp8 X2             1.4653  0.3811    3.85  0.00012 ***
## sp8 X3             1.4441  0.3938    3.67  0.00025 ***
## sp9 (Intercept)   -0.0981  0.2004   -0.49  0.62454    
## sp9 X1            -0.6684  0.3691   -1.81  0.07016 .  
## sp9 X2            -1.0043  0.3498   -2.87  0.00409 ** 
## sp9 X3            -0.8923  0.3593   -2.48  0.01301 *  
## sp10 (Intercept)   0.0723  0.1908    0.38  0.70476    
## sp10 X1           -1.7041  0.3845   -4.43  9.3e-06 ***
## sp10 X2           -0.5234  0.3306   -1.58  0.11332    
## sp10 X3           -0.6881  0.3213   -2.14  0.03221 *  
## ---
## Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1

Plot the niche estimates, i.e the estimates in the environmental component:

plot(model)
## 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 sjSDM package.
##   Please report the issue at
##   <https://github.com/TheoreticalEcology/s-jSDM/issues>.
## This warning is displayed once per session.
## Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
## generated.

plot of chunk unnamed-chunk-9

Visualize the species-species association matrix

image(getCor(model))

plot of chunk unnamed-chunk-10

Anova / Variation partitioning

Global ANOVA

As in other models, it can be interesting to analyze how much variation is explained by which parts of hte model.

image{{width=70%}}
For the Env, Spatial, Covariance terms, this is implemented in

an = anova(model, verbose = FALSE)
summary(an)
## Analysis of Deviance Table
## 
##                Deviance Residual deviance R2 Nagelkerke R2 McFadden
## Abiotic      1.9813e+02        1.1747e+03    8.6211e-01      0.1443
## Associations 1.8424e+02        1.1886e+03    8.4156e-01      0.1342
## Spatial      6.0126e+00        1.3669e+03    5.8355e-02      0.0044
## Full         3.8838e+02        9.8449e+02    9.7943e-01      0.2829
plot(an)

plot of chunk unnamed-chunk-12

The anova shows the relative changes in the R^2^ of the groups and their intersections.

Internal metacommunity structure

Following Leibold et al., 2022 we can calculate and visualize the internal metacommunity structure (=partitioning of the three components for species and sites). The internal structure is already calculated by the ANOVA and we can visualize it with the plot method:

results = internalStructure(an)

The internal structure can be plotted:

plot(results)

plot of chunk unnamed-chunk-14

Which can be regressed against covariates to analyse assembly processes:

plotAssemblyEffects(results)

plot of chunk unnamed-chunk-15


Owner metadata


GitHub Events

Total
Last Year

Committers metadata

Last synced: 2 days ago

Total Commits: 525
Total Committers: 6
Avg Commits per committer: 87.5
Development Distribution Score (DDS): 0.251

Commits in past year: 19
Committers in past year: 1
Avg Commits per committer in past year: 19.0
Development Distribution Score (DDS) in past year: 0.0

Name Email Commits
MaximilianPi m****r@b****e 393
Maximilian Pichler M****r@s****e 103
Florian Hartig f****g 26
CaiWang0503 4****3 1
CaiWang0503 4****T 1
MaximilianPi m****r@M****l 1

Committer domains:


Issue and Pull Request metadata

Last synced: 5 days ago

Total issues: 127
Total pull requests: 31
Average time to close issues: 7 months
Average time to close pull requests: 9 days
Total issue authors: 47
Total pull request authors: 2
Average comments per issue: 2.76
Average comments per pull request: 0.13
Merged pull request: 29
Bot issues: 0
Bot pull requests: 0

Past year issues: 8
Past year pull requests: 3
Past year average time to close issues: about 2 months
Past year average time to close pull requests: 1 day
Past year issue authors: 7
Past year pull request authors: 1
Past year average comments per issue: 0.5
Past year average comments per pull request: 0.0
Past year merged pull request: 3
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/theoreticalecology/s-jsdm

Top Issue Authors

  • MaximilianPi (22)
  • florianhartig (20)
  • dougwyu (7)
  • frmunoz (5)
  • wevertonbio (4)
  • sogm (4)
  • YJ781 (3)
  • dansmi-hub (3)
  • CaiWang0503 (3)
  • AndrewCSlater (3)
  • mtva0001 (3)
  • agnes-duhamet (3)
  • chnpenny (2)
  • mdayii (2)
  • Cdevenish (2)

Top Pull Request Authors

  • MaximilianPi (30)
  • CaiWang0503 (1)

Top Issue Labels

  • enhancement (18)
  • bug (11)
  • question (5)
  • documentation (3)
  • future (2)
  • installation help (2)
  • help wanted (2)
  • CRAN (1)

Top Pull Request Labels


Package metadata

pypi.org: sjsdm-py

jSDM package

  • Homepage: https://github.com/TheoreticalEcology/s-jSDM
  • Documentation: https://sjsdm-py.readthedocs.io/
  • Licenses: GNU General Public License v3 (GPLv3)
  • Latest release: 0.1.1 (published over 5 years ago)
  • Last Synced: 2026-11-19T18:01:30.999159Z (2 days ago)
  • Versions: 5
  • Dependent Packages: 0
  • Dependent Repositories: 1
  • Downloads: 37 Last month
  • Rankings:
    • Dependent packages count: 7.313%
    • Stargazers count: 8.867%
    • Forks count: 9.89%
    • Average: 19.372%
    • Dependent repos count: 22.093%
    • Downloads: 48.697%
  • Maintainers (1)
cran.r-project.org: sjSDM

Scalable Joint Species Distribution Modeling

  • Homepage: https://github.com/TheoreticalEcology/s-jSDM/
  • Documentation: http://cran.r-project.org/web/packages/sjSDM/sjSDM.pdf
  • Licenses: GPL-3
  • Latest release: 1.0.7 (published about 1 year ago)
  • Last Synced: 2026-11-19T18:01:30.670309Z (2 days ago)
  • Versions: 8
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 603 Last month
  • Rankings:
    • Forks count: 5.648%
    • Stargazers count: 7.245%
    • Average: 26.185%
    • Dependent packages count: 29.797%
    • Dependent repos count: 35.455%
    • Downloads: 52.779%
  • Maintainers (1)

Dependencies

sjSDM/DESCRIPTION cran
  • R >= 3.0 depends
  • Metrics * imports
  • Ternary * imports
  • abind * imports
  • checkmate * imports
  • cli * imports
  • crayon * imports
  • ggplot2 * imports
  • ggtern * imports
  • grDevices * imports
  • graphics * imports
  • mathjaxr * imports
  • mgcv * imports
  • mvtnorm * imports
  • parallel * imports
  • reticulate * imports
  • rstudioapi * imports
  • stats * imports
  • utils * imports
  • knitr * suggests
  • rmarkdown * suggests
  • testthat * suggests
.github/workflows/rcmdcheck.yaml actions
.github/workflows/installation.yaml actions
  • actions/cache v2 composite
  • actions/checkout v2 composite
  • actions/upload-artifact main composite
  • r-lib/actions/setup-pandoc v2 composite
  • r-lib/actions/setup-r v2 composite
  • r-lib/actions/setup-tinytex v2 composite
  • teatimeguest/setup-texlive-action v2 composite

Score: 12.921343287577741