docs: redesign README with banner and lighter content (audit #5)

Author: MaartenMarsman

README.md

@@ -1,20 +1,7 @@
 
 <!-- README.md is generated from Readme.Rmd. Please edit that file -->
 
-<!-- # bgms <a href="https://bayesiangraphicalmodeling.com"><img src="man/figures/bgms_sticker.svg" height="200" align="right" alt="bgms website" /></a> -->
-
-<div style="display:flex; align-items:center; justify-content:space-between;">
-
-<h1>
-
-bgms
-</h1>
-
-<a href="https://bayesiangraphicalmodeling.com">
-<img src="man/figures/bgms_sticker.svg" height="200" alt="bgms website" />
-</a>
-
-</div>
+![bgms](man/figures/bgms-banner.svg)
 
 <!-- badges: start -->
 
@@ -29,209 +16,82 @@ stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://
 
 **Bayesian analysis of graphical models**
 
-The **bgms** package implements Bayesian estimation and model comparison
-for graphical models of binary, ordinal, continuous, and mixed variables
-(<span class="nocase">Marsman, van den Bergh, et al.</span>, 2025). It
-supports **ordinal Markov random fields (MRFs)** for discrete data,
-**Gaussian graphical models (GGMs)** for continuous data, and **mixed
-MRFs** that combine discrete and continuous variables in a single
-network. The likelihood is approximated with a pseudolikelihood, and
-Markov chain Monte Carlo (MCMC) methods are used to sample from the
-corresponding pseudoposterior distribution of the model parameters.
+The **bgms** package provides Bayesian estimation and edge selection for
+Markov random field models of mixed binary, ordinal, and continuous
+variables. The variable types in the data determine the model: an
+**ordinal MRF** for ordinal data, a **Gaussian graphical model** for
+continuous data, or a **mixed MRF** combining both. Posterior inference
+uses Markov chain Monte Carlo, combining a Metropolis approach for
+between-model moves (i.e., edge selection) with the No-U-Turn sampler
+for within-model parameter updates. The package supports both
+single-threaded and parallel chains, and uses a C++ backend for
+computational efficiency.
 
 ## Main functions
 
-The package has two main entry points:
-
-- `bgm()` – estimates a single network in a one-sample design. Use
-  `variable_type = "ordinal"` for an MRF, `"continuous"` for a GGM, or a
-  per-variable vector mixing `"ordinal"`, `"blume-capel"`, and
-  `"continuous"` for a mixed MRF.
-- `bgmCompare()` – compares networks between groups in an
-  independent-sample design.
-
-## Effect selection
-
-Both functions support **effect selection** with spike-and-slab priors:
-
-- **Edges in one-sample designs**: `bgm()` models the presence or
-  absence of edges between variables. Posterior inclusion probabilities
-  indicate the plausibility of each edge and can be converted into Bayes
-  factors for conditional independence tests (see
-  <span class="nocase">Marsman, van den Bergh, et al.</span>, 2025;
-  <span class="nocase">Sekulovski et al.</span>, 2024).
-
-- **Communities/clusters in one-sample designs**: `bgm()` can also model
-  community structure. Posterior probabilities for the number of
-  clusters quantify the plausibility of clustering solutions and can be
-  converted into Bayes factors (see Sekulovski et al., 2025).
-
-- **Group differences in independent-sample designs**: `bgmCompare()`
-  models differences in edge weights and category thresholds between
-  groups. Posterior inclusion probabilities indicate the plausibility of
-  parameter differences and can be converted into Bayes factors for
-  tests of parameter equivalence (see Marsman, Waldorp, et al., 2025).
-
-## Learn more
+- `bgm()` — estimate a graphical model in a one-sample design.
+- `bgmCompare()` — compare graphical models between groups.
 
-For worked examples and tutorials, see the package vignettes:
+Both functions support **edge selection** via spike-and-slab priors,
+yielding posterior inclusion probabilities for each edge. `bgm()` can
+additionally model **community structure**, and `bgmCompare()` can test
+for **group differences** in individual parameters.
 
-- [Getting
-  Started](https://bayesian-graphical-modelling-lab.github.io/bgms/articles/intro.html)
-- [Model
-  Comparison](https://bayesian-graphical-modelling-lab.github.io/bgms/articles/comparison.html)
-- [Diagnostics and Spike-and-Slab
-  Summaries](https://bayesian-graphical-modelling-lab.github.io/bgms/articles/diagnostics.html)
+## Installation
 
-You can also access these directly from R with:
+Install from CRAN:
 
 ``` r
-browseVignettes("bgms")
+install.packages("bgms")
 ```
 
-## Why use Markov Random Fields?
-
-Graphical models or networks have become central in recent psychological
-and psychometric research (Contreras et al., 2019; Marsman & Rhemtulla,
-2022; Robinaugh et al., 2020). Most are **Markov random field (MRF)**
-models, where the graph structure reflects partial associations between
-variables (Kindermann & Snell, 1980).
-
-In an MRF, a missing edge between two variables implies **conditional
-independence** given the rest of the network (Lauritzen, 2004). In other
-words, the remaining variables fully explain away any potential
-association between the unconnected pair.
-
-## Why use a Bayesian approach?
-
-When analyzing an MRF, we often want to compare competing hypotheses:
-
-- **Edge presence vs. edge absence** (conditional dependence
-  vs. independence) in one-sample designs.
-- **Parameter difference vs. parameter equivalence** in
-  independent-sample designs.
-
-Frequentist approaches are limited in such comparisons: they can reject
-a null hypothesis, but they cannot provide evidence *for* it. As a
-result, when an edge or difference is excluded, it remains unclear
-whether this reflects true absence or simply insufficient power.
-
-Bayesian inference avoids this problem. Using **inclusion Bayes
-factors** (<span class="nocase">Huth et al.</span>, 2023;
-<span class="nocase">Sekulovski et al.</span>, 2024), we can quantify
-evidence in both directions:
-
-- **Evidence of edge presence** vs. **evidence of edge absence**, or
-- **Evidence of parameter difference** vs. **evidence of parameter
-  equivalence**.
-
-This makes it possible not only to detect structure and group
-differences, but also to conclude when there is an *absence of
-evidence*.
-
-## Installation
-
-The current developmental version can be installed with
+Or install the development version from GitHub:
 
 ``` r
-if(!requireNamespace("remotes")) {
-  install.packages("remotes")
-}
+# install.packages("remotes")
 remotes::install_github("Bayesian-Graphical-Modelling-Lab/bgms")
 ```
 
-## References
-
-<div id="refs" class="references csl-bib-body hanging-indent"
-entry-spacing="0" line-spacing="2">
-
-<div id="ref-ContrerasEtAl_2019" class="csl-entry">
-
-Contreras, A., Nieto, I., Valiente, C., Espinosa, R., & Vazquez, C.
-(2019). The study of psychopathology from the network analysis
-perspective: A systematic review. *Psychotherapy and Psychosomatics*,
-*88*(2), 71–83. <https://doi.org/10.1159/000497425>
-
-</div>
-
-<div id="ref-HuthEtAl_2023_intro" class="csl-entry">
-
-<span class="nocase">Huth, K., de Ron, J., Goudriaan, A. E., Luigjes,
-K., Mohammadi, R., van Holst, R. J., Wagenmakers, E.-J., & Marsman,
-M.</span> (2023). Bayesian analysis of cross-sectional networks: A
-tutorial in R and JASP. *Advances in Methods and Practices in
-Psychological Science*, *6*, 1–18.
-<https://doi.org/10.1177/25152459231193334>
-
-</div>
-
-<div id="ref-KindermannSnell1980" class="csl-entry">
-
-Kindermann, R., & Snell, J. L. (1980). *Markov random fields and their
-applications* (Vol. 1). American Mathematical Society.
-
-</div>
-
-<div id="ref-Lauritzen2004" class="csl-entry">
+## Citation
 
-Lauritzen, S. L. (2004). *Graphical models*. Oxford University Press.
+If you use bgms in your work, please cite:
 
-</div>
+1.  Marsman, M., van den Bergh, D., & Haslbeck, J. M. B. (2025).
+    Bayesian analysis of the ordinal Markov random field.
+    *Psychometrika*, *90*(1), 146–182.
+    [DOI:10.1017/psy.2024.4](https://doi.org/10.1017/psy.2024.4)
 
-<div id="ref-MarsmanRhemtulla_2022_SIintro" class="csl-entry">
+Related methodological papers:
 
-Marsman, M., & Rhemtulla, M. (2022). Guest editors’ introduction to the
-special issue “network psychometrics in action”: Methodological
-innovations inspired by empirical problems. *Psychometrika*, *87*, 1–11.
-<https://doi.org/10.1007/s11336-022-09861-x>
+2.  Sekulovski, N., Keetelaar, S., Huth, K. B. S., Wagenmakers, E.-J.,
+    van Bork, R., van den Bergh, D., & Marsman, M. (2024). Testing
+    conditional independence in psychometric networks: An analysis of
+    three Bayesian methods. *Multivariate Behavioral Research*, *59*,
+    913–933.
+    [DOI:10.1080/00273171.2024.2345915](https://doi.org/10.1080/00273171.2024.2345915)
 
-</div>
+3.  Marsman, M., Waldorp, L. J., Sekulovski, N., & Haslbeck, J. M. B.
+    (2025). Bayes factor tests for group differences in ordinal and
+    binary graphical models. *Psychometrika*, *90*(5), 1809–1842.
+    [DOI:10.1017/psy.2025.10060](https://doi.org/10.1017/psy.2025.10060)
 
-<div id="ref-MarsmanVandenBerghHaslbeck_2025" class="csl-entry">
+4.  Sekulovski, N., Arena, G., Haslbeck, J. M. B., Huth, K. B. S.,
+    Friel, N., & Marsman, M. (2025). A stochastic block prior for
+    clustering in graphical models.
+    [PsyArXiv:29p3m](https://osf.io/preprints/psyarxiv/29p3m_v1)
 
-<span class="nocase">Marsman, M., van den Bergh, D., & Haslbeck, J. M.
-B.</span> (2025). Bayesian analysis of the ordinal Markov random field.
-*Psychometrika*, *90*(1), 146–182. <https://doi.org/10.1017/psy.2024.4>
+You can also retrieve the citation from R:
 
-</div>
-
-<div id="ref-MarsmanWaldorpSekulovskiHaslbeck_2024" class="csl-entry">
-
-Marsman, M., Waldorp, L. J., Sekulovski, N., & Haslbeck, J. M. B.
-(2025). Bayes factor tests for group differences in ordinal and binary
-graphical models. *Psychometrika*, *90*(5), 1809–1842.
-<https://doi.org/10.1017/psy.2025.10060>
-
-</div>
-
-<div id="ref-RobinaughEtAl_2020" class="csl-entry">
-
-Robinaugh, D. J., Hoekstra, R. H. A., Toner, E. R., & Borsboom, D.
-(2020). The network approach to psychopathology: A review of the
-literature 2008–2018 and an agenda for future research. *Psychological
-Medicine*, *50*, 353–366. <https://doi.org/10.1017/S0033291719003404>
-
-</div>
-
-<div id="ref-SekulovskiEtAl_2025" class="csl-entry">
-
-Sekulovski, N., Arena, G., Haslbeck, J. M. B., Huth, K. B. S., Friel,
-N., & Marsman, M. (2025). A stochastic block prior for clustering in
-graphical models. *Retrieved from
-<a href="https://osf.io/preprints/psyarxiv/29p3m_v1"
-class="uri">Https://Osf.io/Preprints/Psyarxiv/29p3m_v1</a>*.
-
-</div>
+``` r
+citation("bgms")
+```
 
-<div id="ref-SekulovskiEtAl_2024" class="csl-entry">
+## Contributing
 
-<span class="nocase">Sekulovski, N., Keetelaar, S., Huth, K. B. S.,
-Wagenmakers, E.-J., van Bork, R., van den Bergh, D., & Marsman,
-M.</span> (2024). Testing conditional independence in psychometric
-networks: An analysis of three Bayesian methods. *Multivariate
-Behavioral Research*, *59*, 913–933.
-<https://doi.org/10.1080/00273171.2024.2345915>
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for
+how to get started.
 
-</div>
+## Code of Conduct
 
-</div>
+This project follows the [Contributor Covenant Code of
+Conduct](CODE_OF_CONDUCT.md).