+
+# BSTVC
-
-
-
-
+
[](https://doi.org/10.1016/j.ijdrr.2022.103078)
-**Spatiotemporal heterogeneous perspective for analyzing influencing factors, identifying key drivers, and making dynamic predictions, all within a unified 'full-map' framework.**
+**A powerful tool for ante-hoc spatiotemporal interpretable analysis.**
+
+**Spatiotemporal heterogeneous perspective for analyzing local influencing factors (local spatiotemporal interpretability), identifying key global factors (global spatiotemporal interpretability), and making dynamic predictions, all within a unified 'full-map' framework.**
+
+
+
+
BSTVC unifies local spatiotemporal interpretability, global spatiotemporal interpretability, and dynamic prediction within a Bayesian full-map framework.
+ +## Scientific overview + +BSTVC is a Bayesian modeling framework for investigating spatiotemporal +heterogeneity in relationships between an outcome and its potential +determinants. It is designed for research questions that require more than +overall association estimates: the framework characterizes where and when +local effects vary, evaluates the relative contribution of candidate factors +at the global level, and supports prediction under changing spatiotemporal +conditions. By integrating these analytical targets within one coherent +workflow, BSTVC helps researchers connect local variation, global attribution, +and predictive inference while retaining parameter uncertainty. The framework +is applicable to spatiotemporal panel and areal data in public health, +medical geography, environmental research, and related fields. + +### Interpretability framework + +- **Ante-hoc spatiotemporal interpretability** means that interpretability is + built into the statistical model through explicitly estimated parameters, + rather than approximated after fitting an opaque predictive model. +- **Local spatiotemporal interpretability** describes how the direction and + magnitude of a variable's association with the outcome vary across space + and time. +- **Global spatiotemporal interpretability** evaluates the overall importance + of candidate factors in explaining spatiotemporal variation. +- **Full-map framework** refers to the unified analysis of local effects, + global factor importance, and dynamic prediction across the complete + study domain. @@ -37,48 +70,68 @@ knitr::opts_chunk$set( ## Installation -**- Install the `BSTVC` R package** +### Install the `BSTVC` R package -The package is currently in the internal testing phase. At present, it -only supports local installation from GitHub. +Install BSTVC directly from GitHub: ``` r # Install using the devtools package # install.packages("devtools") -devtools::install_github("songbi123/BSTVC") +devtools::install_github("bayesianstvc/BSTVC") # Install using the remotes package # install.packages("remotes") -remotes::install_github("songbi123/BSTVC") +remotes::install_github("bayesianstvc/BSTVC") ``` -**- Install the dependency package - the `INLA` R package** - -When installing the `BSTVC` package in RStudio, the system will prompt -you to install additional R packages that come with it. However, since -`INLA` is a larger package, installing the `BSTVC` package might lead to -a failure. To avoid this issue, we provide a separate method for -installing the `INLA` package for your reference. +### Install the `INLA` dependency -If the installation of the `BSTVC` package in the previous step failed, -please install the `BSTVC` package after successfully installing the -`INLA` package. If you have successfully installed the `INLA` package -while installing the `BSTVC` package, you can skip this step. +BSTVC uses the `INLA` package for Bayesian latent Gaussian modeling. If +`INLA` is not already available in your R environment, install it from +the official INLA repository before installing BSTVC. ``` r -## To install the INLA package, more information can be found at
+
+### Chinese desktop version — BSTVC Desktop (时空可解释工具)
+
+The Chinese desktop version, **BSTVC桌面版（时空可解释工具）**, provides a more accessible graphical workflow for spatiotemporal analysis and interpretation. Visit the [official website](https://bayesianstvc.github.io/BSTVC-R/) for the latest introduction and access information.
+
+The English desktop version is coming soon — stay tuned.
+
+## Scientific capabilities
The `BSTVC` R package is designed to provide a comprehensive suite of
functionalities for advanced spatiotemporal heterogeneous analysis.
-Here's what our package can do for you:
+Its principal scientific capabilities include:
+
+### Model families and scientific outputs
+
+| Analytical target | Supported model or output |
+|:--|:--|
+| Continuous response | Log-Gaussian regression |
+| Binary response | Logistic regression |
+| Count response | Poisson regression |
+| Local interpretation | Spatiotemporally varying coefficient estimates |
+| Global interpretation | Explainable-percentage and key-factor assessment |
+| Prediction | Spatiotemporal smoothing, missing-value imputation, and forecasting |
+| Model assessment | DIC, WAIC, effective number of parameters (pD), and logarithmic score (LS) |
- **Targeting multiple types of response variables**: It supports
three mainstream types of response variables: continuous
@@ -95,14 +148,14 @@ Here's what our package can do for you:
- **Identifying spatiotemporal driving factors**: On the basis of
identifying spatiotemporal heterogeneous impact mechanisms, it
clarifies key driving factors by calculating the spatiotemporal
- explainable percentage, providing strong evidence for geographical
+ explainable percentage, supporting geographical
spatiotemporal attribution.
-- **Improving spatiotemporal prediction accuracy**: Considering the
- spatiotemporal heterogeneity of local variable relationships, it
- significantly improves model fitting and prediction accuracy, which
- can be used for spatiotemporal missing value imputation,
- spatiotemporal smoothing, and future forecasting.
+- **Supporting spatiotemporal prediction**: By accounting for
+ spatiotemporal heterogeneity in local variable relationships, the
+ framework can improve model fit and predictive performance when such
+ nonstationarity is present. It supports spatiotemporal missing-value
+ imputation, smoothing, and forecasting.
- **Bayesian model assessment**: It provides a comprehensive
evaluation of Bayesian regression models, including model fitting (DIC, WAIC), complexity (pd), and prediction accuracy (LS)
@@ -110,13 +163,12 @@ Here's what our package can do for you:
- **Rich visualization outputs**: It provides a variety of
spatiotemporal visualization tools and codes to help users
- intuitively understand model results, enhance the interpretability
- of data analysis, and promote innovation in your applied research.
+ examine model results and communicate spatiotemporal patterns and
+ uncertainty in applied research.
-Bayesian STVC model is a powerful analytical tool with many advantages
-that other similar tools lack, such as **a *"full-map" modeling
-framework*, *parameter uncertainty*, *friendliness to missing values*,
-and *support for more spatial weight matrices***, among others.
+The BSTVC framework integrates a **full-map modeling strategy, Bayesian
+parameter uncertainty, support for missing values, and flexible spatial
+weight matrices** within a unified analytical workflow.
## Usage Guide
@@ -126,7 +178,7 @@ guides, as follows:
| Guide | Details |
|-------------------|------------------------------|
-| **User's Guide for the BSTVC R Package** | This usage guide covers detailed example operations and important considerations for each key step, including data import, inspection, preprocessing, model fitting, result output and result visualization. You can view it in the `GetStart.Rmd` document under the `vignettes` folder, but it's in R markdown format. 
-
-## Reference
-
-- **[Bayesian STVC series models]** Song, Chao, Yin, Hao, Shi, Xun,
- Xie, Mingyu, Yang, Shujuan, Zhou, Junmin, Wang, Xiuli, Tang,
- Zhangying, Yang, Yili, & Pan, Jay. (2022). Spatiotemporal
- disparities in regional public risk perception of COVID-19 using
- Bayesian Spatiotemporally Varying Coefficients (STVC) series models
- across Chinese cities. *International Journal of Disaster Risk
- Reduction*, 77, 103078.
-
-- **[STVPI]** Wan, Qin, Tang, Zhangying, Pan, Jay, Xie, Mingyu, Wang,
- Shaobin, Yin, Hao, Li, Junmin, Liu, Xin, Yang, Yang, & Song, Chao.
- (2022). Spatiotemporal heterogeneity in associations of national
- population ageing with socioeconomic and environmental factors at
- the global scale. *Journal of Cleaner Production*, 373, 133781.
-
-- Song, Chao, Shi, Xun, & Wang, Jinfeng. (2020). Spatiotemporally
- Varying Coefficients (STVC) model: a Bayesian local regression to
- detect spatial and temporal nonstationarity in variables
- relationships. *Annals of GIS*, 26(3), 277-291.
-
-- Song, Chao, Shi, Xun, Bo, Yanchen, Wang, Jinfeng, Wang, Yong, &
- Huang, Dacang. (2019). Exploring Spatiotemporal Nonstationary
- Effects of Climate Factors on Hand, Foot, and Mouth Disease Using
- Bayesian Spatiotemporally Varying Coefficients (STVC) Model in
- Sichuan, China. *Science of The Total Environment*, 648, 550-560.
+
+
+## References
+
+- **Bayesian STVC series models:** Song, C., Yin, H., Shi, X., Xie, M.,
+ Yang, S., Zhou, J., Wang, X., Tang, Z., Yang, Y., & Pan, J. (2022).
+ Spatiotemporal disparities in regional public risk perception of
+ COVID-19 using Bayesian spatiotemporally varying coefficients (STVC)
+ series models across Chinese cities. *International Journal of Disaster
+ Risk Reduction, 77*, 103078.
+
+- **STVPI:** Wan, Q., Tang, Z., Pan, J., Xie, M., Wang, S., Yin, H.,
+ Li, J., Liu, X., Yang, Y., & Song, C. (2022). Spatiotemporal
+ heterogeneity in associations of national population ageing with
+ socioeconomic and environmental factors at the global scale.
+ *Journal of Cleaner Production, 373*, 133781.
+
+- Song, C., Shi, X., & Wang, J. (2020). Spatiotemporally varying
+ coefficients (STVC) model: A Bayesian local regression to detect
+ spatial and temporal nonstationarity in variable relationships.
+ *Annals of GIS, 26*(3), 277–291.
+
+- Song, C., Shi, X., Bo, Y., Wang, J., Wang, Y., & Huang, D. (2019).
+ Exploring spatiotemporal nonstationary effects of climate factors on
+ hand, foot, and mouth disease using a Bayesian spatiotemporally varying
+ coefficients (STVC) model in Sichuan, China. *Science of the Total
+ Environment, 648*, 550–560.
diff --git a/README.md b/README.md
index 041b525..e9d7607 100644
--- a/README.md
+++ b/README.md
@@ -1,174 +1,240 @@
-
-
-
-# BSTVC
-
-
-
-
-
-
-
-
-[](https://doi.org/10.1016/j.ijdrr.2022.103078)
-
-
-
-**Spatiotemporal heterogeneous perspective for analyzing influencing
-factors, identifying key drivers, and making dynamic predictions, all
-within a unified ‘full-map’ framework.**
-
-
-
-
-## Installation
-
-**- Install the `BSTVC` R package**
-
-The package is currently in the internal testing phase. At present, it
-only supports local installation from GitHub.
-
-``` r
-# Install using the devtools package
-# install.packages("devtools")
-devtools::install_github("songbi123/BSTVC")
-
-# Install using the remotes package
-# install.packages("remotes")
-remotes::install_github("songbi123/BSTVC")
-```
-
-**- Install the dependency package - the `INLA` R package**
-
-When installing the `BSTVC` package in RStudio, the system will prompt
-you to install additional R packages that come with it. However, since
-`INLA` is a larger package, installing the `BSTVC` package might lead to
-a failure. To avoid this issue, we provide a separate method for
-installing the `INLA` package for your reference.
-
-If the installation of the `BSTVC` package in the previous step failed,
-please install the `BSTVC` package after successfully installing the
-`INLA` package. If you have successfully installed the `INLA` package
-while installing the `BSTVC` package, you can skip this step.
-
-``` r
-## To install the INLA package, more information can be found at
-
-## Reference
-
-- **\[Bayesian STVC series models\]** Song, Chao, Yin, Hao, Shi, Xun,
- Xie, Mingyu, Yang, Shujuan, Zhou, Junmin, Wang, Xiuli, Tang,
- Zhangying, Yang, Yili, & Pan, Jay. (2022). Spatiotemporal disparities
- in regional public risk perception of COVID-19 using Bayesian
- Spatiotemporally Varying Coefficients (STVC) series models across
- Chinese cities. *International Journal of Disaster Risk Reduction*,
- 77, 103078.
-
-- **\[STVPI\]** Wan, Qin, Tang, Zhangying, Pan, Jay, Xie, Mingyu, Wang,
- Shaobin, Yin, Hao, Li, Junmin, Liu, Xin, Yang, Yang, & Song, Chao.
- (2022). Spatiotemporal heterogeneity in associations of national
- population ageing with socioeconomic and environmental factors at the
- global scale. *Journal of Cleaner Production*, 373, 133781.
-
-- Song, Chao, Shi, Xun, & Wang, Jinfeng. (2020). Spatiotemporally
- Varying Coefficients (STVC) model: a Bayesian local regression to
- detect spatial and temporal nonstationarity in variables
- relationships. *Annals of GIS*, 26(3), 277-291.
-
-- Song, Chao, Shi, Xun, Bo, Yanchen, Wang, Jinfeng, Wang, Yong, & Huang,
- Dacang. (2019). Exploring Spatiotemporal Nonstationary Effects of
- Climate Factors on Hand, Foot, and Mouth Disease Using Bayesian
- Spatiotemporally Varying Coefficients (STVC) Model in Sichuan, China.
- *Science of The Total Environment*, 648, 550-560.
+
+
+
+# BSTVC
+
+
+
+
+
+[](https://doi.org/10.1016/j.ijdrr.2022.103078)
+
+
+
+**A powerful tool for ante-hoc spatiotemporal interpretable analysis.**
+
+**Spatiotemporal heterogeneous perspective for analyzing local
+influencing factors (local spatiotemporal interpretability), identifying
+key global factors (global spatiotemporal interpretability), and making
+dynamic predictions, all within a unified ‘full-map’ framework.**
+
+
+
+
BSTVC unifies local spatiotemporal interpretability, global spatiotemporal interpretability, and dynamic prediction within a Bayesian full-map framework.
+ +## Scientific overview + +BSTVC is a Bayesian modeling framework for investigating spatiotemporal +heterogeneity in relationships between an outcome and its potential +determinants. It is designed for research questions that require more than +overall association estimates: the framework characterizes where and when +local effects vary, evaluates the relative contribution of candidate factors +at the global level, and supports prediction under changing spatiotemporal +conditions. By integrating these analytical targets within one coherent +workflow, BSTVC helps researchers connect local variation, global attribution, +and predictive inference while retaining parameter uncertainty. The framework +is applicable to spatiotemporal panel and areal data in public health, +medical geography, environmental research, and related fields. + +### Interpretability framework + +- **Ante-hoc spatiotemporal interpretability** means that interpretability is + built into the statistical model through explicitly estimated parameters, + rather than approximated after fitting an opaque predictive model. +- **Local spatiotemporal interpretability** describes how the direction and + magnitude of a variable's association with the outcome vary across space + and time. +- **Global spatiotemporal interpretability** evaluates the overall importance + of candidate factors in explaining spatiotemporal variation. +- **Full-map framework** refers to the unified analysis of local effects, + global factor importance, and dynamic prediction across the complete + study domain. + + + + +## Installation + +### Install the `BSTVC` R package + +Install BSTVC directly from GitHub: + +``` r +# Install using the devtools package +# install.packages("devtools") +devtools::install_github("bayesianstvc/BSTVC") + +# Install using the remotes package +# install.packages("remotes") +remotes::install_github("bayesianstvc/BSTVC") +``` + +### Install the `INLA` dependency + +BSTVC uses the `INLA` package for Bayesian latent Gaussian modeling. If +`INLA` is not already available in your R environment, install it from +the official INLA repository before installing BSTVC. + +``` r +# Installation details:
+
+### Chinese desktop version — BSTVC Desktop (时空可解释工具)
+
+The Chinese desktop version, **BSTVC桌面版（时空可解释工具）**, provides a more accessible graphical workflow for spatiotemporal analysis and interpretation. Visit the [official website](https://bayesianstvc.github.io/BSTVC-R/) for the latest introduction and access information.
+
+The English desktop version is coming soon — stay tuned.
+
+## Scientific capabilities
+
+The `BSTVC` R package is designed to provide a comprehensive suite of
+functionalities for advanced spatiotemporal heterogeneous analysis.
+Its principal scientific capabilities include:
+
+### Model families and scientific outputs
+
+| Analytical target | Supported model or output |
+|:--|:--|
+| Continuous response | Log-Gaussian regression |
+| Binary response | Logistic regression |
+| Count response | Poisson regression |
+| Local interpretation | Spatiotemporally varying coefficient estimates |
+| Global interpretation | Explainable-percentage and key-factor assessment |
+| Prediction | Spatiotemporal smoothing, missing-value imputation, and forecasting |
+| Model assessment | DIC, WAIC, effective number of parameters (pD), and logarithmic score (LS) |
+
+- **Targeting multiple types of response variables**: It supports three
+ mainstream types of response variables: continuous (log-Gaussian
+ regression), binary (logistic regression), and count (Poisson
+ regression), accommodating various analytical scenarios.
+
+- **Detecting spatiotemporal heterogeneous impact mechanisms**: By
+ fitting spatiotemporal regression coefficients, it reveals local
+ spatiotemporal differences between explanatory variables (X) and
+ response variables (Y), facilitating an in-depth analysis of
+ context-specific patterns and exploring the impact mechanisms brought
+ by spatiotemporal heterogeneity.
+
+- **Identifying spatiotemporal driving factors**: On the basis of
+ identifying spatiotemporal heterogeneous impact mechanisms, it
+ clarifies key driving factors by calculating the spatiotemporal
+ explainable percentage, supporting geographical
+ spatiotemporal attribution.
+
+- **Supporting spatiotemporal prediction**: By accounting for
+ spatiotemporal heterogeneity in local variable relationships, the
+ framework can improve model fit and predictive performance when such
+ nonstationarity is present. It supports spatiotemporal missing-value
+ imputation, smoothing, and forecasting.
+
+- **Bayesian model assessment**: It provides a comprehensive evaluation
+ of Bayesian regression models, including model fitting (DIC, WAIC),
+ complexity (pd), and prediction accuracy (LS) indicators, helping
+ users fully understand model performance.
+
+- **Rich visualization outputs**: It provides a variety of
+ spatiotemporal visualization tools and codes to help users intuitively
+ examine model results and communicate spatiotemporal patterns and
+ uncertainty in applied research.
+
+The BSTVC framework integrates a **full-map modeling strategy, Bayesian
+parameter uncertainty, support for missing values, and flexible spatial
+weight matrices** within a unified analytical workflow.
+
+## Usage Guide
+
+To help you quickly and fully get started with our R package for complex
+data analysis, we have prepared several detailed and comprehensive usage
+guides, as follows:
+
+| Guide | Details |
+|----|----|
+| **User’s Guide for the BSTVC R Package** | This usage guide covers detailed example operations and important considerations for each key step, including data import, inspection, preprocessing, model fitting, result output and result visualization. You can view it in the `GetStart.Rmd` document under the `vignettes` folder, but it’s in R markdown format.
+
+## References
+
+- **Bayesian STVC series models:** Song, C., Yin, H., Shi, X., Xie, M.,
+ Yang, S., Zhou, J., Wang, X., Tang, Z., Yang, Y., & Pan, J. (2022).
+ Spatiotemporal disparities in regional public risk perception of
+ COVID-19 using Bayesian spatiotemporally varying coefficients (STVC)
+ series models across Chinese cities. *International Journal of Disaster
+ Risk Reduction, 77*, 103078.
+
+- **STVPI:** Wan, Q., Tang, Z., Pan, J., Xie, M., Wang, S., Yin, H.,
+ Li, J., Liu, X., Yang, Y., & Song, C. (2022). Spatiotemporal
+ heterogeneity in associations of national population ageing with
+ socioeconomic and environmental factors at the global scale.
+ *Journal of Cleaner Production, 373*, 133781.
+
+- Song, C., Shi, X., & Wang, J. (2020). Spatiotemporally varying
+ coefficients (STVC) model: A Bayesian local regression to detect
+ spatial and temporal nonstationarity in variable relationships.
+ *Annals of GIS, 26*(3), 277–291.
+
+- Song, C., Shi, X., Bo, Y., Wang, J., Wang, Y., & Huang, D. (2019).
+ Exploring spatiotemporal nonstationary effects of climate factors on
+ hand, foot, and mouth disease using a Bayesian spatiotemporally varying
+ coefficients (STVC) model in Sichuan, China. *Science of the Total
+ Environment, 648*, 550–560.
diff --git a/man/Figure/BSTVC_desktop_logo.png b/man/Figure/BSTVC_desktop_logo.png
new file mode 100644
index 0000000..81a6f9c
Binary files /dev/null and b/man/Figure/BSTVC_desktop_logo.png differ
diff --git a/man/Figure/BSTVC_desktop_logo_motion.webp b/man/Figure/BSTVC_desktop_logo_motion.webp
new file mode 100644
index 0000000..a00f6cf
Binary files /dev/null and b/man/Figure/BSTVC_desktop_logo_motion.webp differ
diff --git a/man/Figure/BSTVC_full_map_framework.webp b/man/Figure/BSTVC_full_map_framework.webp
new file mode 100644
index 0000000..348a601
Binary files /dev/null and b/man/Figure/BSTVC_full_map_framework.webp differ