--- title: "Information-filtering networks with TMFG and LoGo" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Information-filtering networks with TMFG and LoGo} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 6) library(psychnets) has_cograph <- requireNamespace("cograph", quietly = TRUE) ``` ## What an information-filtering network is An information-filtering network reduces a large set of associations to a structured backbone. The practical goal is to retain the connections that best organize the variables while removing many weak or redundant links. This approach is useful when a complete correlation network is too dense to support a clear interpretation. The workflow has two stages. The Triangulated Maximally Filtered Graph (TMFG) selects the network structure. Its edge weights are ordinary correlations, so a TMFG edge describes the association between two variables before adjustment for the others. The Local-Global method (LoGo) then estimates partial correlations on the selected structure. A LoGo edge describes the association that remains above and beyond what the other variables in the network can explain. Consider motivation and academic achievement in a larger network that also contains prior achievement, study effort, self-efficacy, and test anxiety. TMFG can retain the motivation-achievement correlation as part of the backbone. LoGo then asks how much of that association remains after the other variables have been accounted for. A large TMFG weight and a small LoGo weight would suggest that much of the ordinary correlation is shared with the other measured variables. TMFG and LoGo therefore answer related but distinct questions. TMFG identifies a compact organization of the correlations. LoGo converts that organization into a conditional-dependence network. Neither method identifies causal direction. ## The data The worked example uses `SRL_GPT`, a data frame with 300 observations on five self-regulated learning constructs. Cognitive strategy use (`CSU`), intrinsic value (`IV`), self-efficacy (`SE`), self-regulation (`SR`), and test anxiety (`TA`) are composite scores on a 1 to 7 scale. ```{r data-preview} head(SRL_GPT) ``` Rows are observations and columns are network nodes. The analysis treats these composite scores as continuous. The data are complete, so the default Pearson correlations use all 300 observations. Applications to other data should examine missingness, distributions, unusual observations, and measurement scales before network estimation. ## Building the correlation backbone with `psychnet()` `psychnet()` builds a TMFG network when `method = "tmfg"`. It computes the correlation matrix and selects a planar, connected structure. The returned `psychnet` object stores signed correlations on the retained edges. ```{r fit-tmfg} tmfg_net <- psychnet(data = SRL_GPT, method = "tmfg") tmfg_net ``` The fitted backbone contains 5 nodes and 9 edges. With five nodes, only one of the ten possible pairs is removed. Information filtering becomes more selective as the number of nodes increases because the number of retained edges grows approximately linearly with the number of nodes. ## Inspecting the TMFG edges with `summary()` `summary()` prints the fitted network and returns its edge table invisibly. The columns `from`, `to`, and `weight` identify each retained pair and its signed Pearson correlation. ```{r summarize-tmfg} summary(tmfg_net) ``` The learning constructs form a strongly correlated block. Their retained correlations range from 0.779 for `SE`-`SR` to 0.861 for `CSU`-`IV`. Test anxiety has negative correlations with the learning constructs in the backbone. Its largest absolute relation is with self-regulation ($r = -0.302$). The `SE`-`TA` pair is the single edge excluded from the five-node backbone. Its absence means that TMFG did not select that pair within the constrained network structure. It does not imply a zero population correlation. TMFG chooses edges as a connected system, so edge inclusion depends on how a pair contributes to the complete topology. ## Estimating conditional associations with LoGo `psychnet()` estimates the LoGo network when `method = "logo"`. It constructs the same TMFG support and estimates a sparse precision matrix on that structure. The returned edge weights are partial correlations. ```{r fit-logo} logo_net <- psychnet(data = SRL_GPT, method = "logo") logo_net ``` The LoGo model contains the same number of nodes and edges as the TMFG backbone. Its weights have a different meaning because each relation is adjusted for the remaining variables. ```{r summarize-logo} summary(logo_net) ``` The largest positive partial correlation joins `CSU` and `IV` ($r = 0.404$). Cognitive strategy use and intrinsic value remain positively associated above and beyond self-efficacy, self-regulation, and test anxiety. The `CSU`-`SE` and `CSU`-`SR` partial correlations are also positive, at 0.393 and 0.377. The `SR`-`TA` edge is negative ($r = -0.372$). Higher self-regulation is associated with lower test anxiety after the other constructs have been taken into account. This adjusted relation is slightly larger in absolute magnitude than its TMFG correlation of -0.302. The change in the `IV`-`SE` edge illustrates why the two stages should not be interpreted interchangeably. Its TMFG correlation is 0.785, while its LoGo partial correlation is 0.165. Much of the ordinary association between intrinsic value and self-efficacy is shared with the other learning constructs. The LoGo edge represents the smaller association that remains after this shared structure is accounted for. ## Checking the TMFG structure with `certificate()` `certificate()` checks the defining properties of a fitted network and returns `method`, `certificate`, `kind`, and `certified`. For TMFG, the certificate is structural. A zero value means that the graph has the required edge count, is connected, and has the chordal structure required by the method. ```{r certify-tmfg} certificate(tmfg_net) ``` The TMFG certificate is 0 and `certified` is `TRUE`. The fitted backbone satisfies all three structural checks. This diagnostic verifies the construction of the graph. It does not evaluate whether the retained edges are stable across samples or whether the variables are measured adequately. ## Checking the LoGo solution with `certificate()` `certificate()` evaluates numerical optimality for a LoGo network. Its `certificate` value is the largest discrepancy between the observed correlation matrix and the covariance matrix implied by the fitted precision on retained edges and diagonal entries. It also checks that precision entries outside the selected structure are zero. ```{r certify-logo} certificate(logo_net) ``` The LoGo residual is $1.33 \times 10^{-15}$ and `certified` is `TRUE`. The value is at the order of machine precision, which indicates that the fitted precision matrix satisfies the defining numerical conditions to numerical precision. This check concerns computation. It does not assess sampling uncertainty or causal validity. ## Describing node position with `net_centralities()` `net_centralities()` summarizes the position of each node in the LoGo network. Its default output contains `node`, `strength`, and `expected_influence`. Strength sums the absolute partial correlations at a node. Expected influence sums the signed partial correlations, allowing positive and negative edges to offset each other. ```{r logo-centrality} net_centralities(logo_net) ``` Cognitive strategy use has the largest strength and expected influence, both 1.284, because all of its edges are positive. Self-regulation has strength 1.247 and expected influence 0.503. Its negative edge with test anxiety reduces the signed total. Test anxiety has strength 0.628 and expected influence -0.116. These values describe its connections within the fitted model. They do not imply that a node with high centrality causes the other variables or should automatically become an intervention target. ## Quantifying node predictability with `net_predict()` `net_predict()` reports the proportion of each node's variance accounted for by the remaining nodes. For LoGo, the function returns `node`, `type`, `metric`, `predictability`, and `accuracy`. The continuous nodes use $R^2$, and classification accuracy is recorded as `NA`. ```{r logo-predictability} net_predict(logo_net) ``` Cognitive strategy use has the highest predictability ($R^2 = 0.835$). Self-regulation ($R^2 = 0.792$), intrinsic value ($R^2 = 0.782$), and self-efficacy ($R^2 = 0.723$) are also strongly accounted for by the remaining constructs. Test anxiety has the lowest predictability ($R^2 = 0.159$), leaving most of its variance outside this network. Predictability is an in-sample model quantity here. Claims about performance on new observations require a separate validation procedure. ## Visualizing the conditional network with `cograph::splot()` `cograph::splot()` draws the LoGo network when the optional `cograph` package is available. Psychological styling uses green for positive partial correlations and red for negative partial correlations. The predictability ring displays the node-level $R^2$ values. ```{r plot-logo, eval = has_cograph} cograph::splot(logo_net, psych_styling = TRUE, predictability = TRUE) ``` The plot is a visual summary of the LoGo edge table. Edge colour represents sign and edge width represents magnitude. Node positions are produced by a layout algorithm and have no statistical unit. Numerical interpretation should use the printed edge table and node summaries. ## Sensitivity to rank correlations `psychnet()` accepts `cor_method = "spearman"` for a rank-based sensitivity analysis. Applying this option to LoGo checks whether the conditional structure has a similar interpretation when the analysis uses monotonic rank associations. ```{r fit-logo-spearman} logo_spearman <- psychnet(data = SRL_GPT, method = "logo", cor_method = "spearman") logo_spearman ``` ```{r summarize-logo-spearman} summary(logo_spearman) ``` The rank-based LoGo model retains the same nine pairs. The main relations also persist. The `CSU`-`IV` and `CSU`-`SE` partial correlations are 0.412 and 0.440, and the `SR`-`TA` edge remains negative at -0.301. The weak `CSU`-`TA` edge decreases from 0.110 to 0.071. The main structure is consistent across the two correlation estimators, while some edge magnitudes remain sensitive. ```{r certify-logo-spearman} certificate(logo_spearman) ``` The rank-based LoGo model has a residual of $1.67 \times 10^{-15}$ and is certified, indicating numerical agreement with its defining conditions to numerical precision. ## Reporting the analysis A report should identify the variables, sample size, correlation estimator, missing-data procedure, and the distinct roles of TMFG and LoGo. TMFG weights must be described as correlations, while LoGo weights must be described as partial correlations. Edge tables should be reported numerically, and conditional associations should be kept separate from causal claims. The present analysis used Pearson correlations on 300 complete observations. TMFG selected a nine-edge backbone. LoGo estimated partial correlations on that structure and returned a numerical residual of $1.33 \times 10^{-15}$. The largest positive LoGo edge was `CSU`-`IV` ($r = 0.404$), and the negative `SR`-`TA` edge was -0.372. A Spearman sensitivity model retained the same edge set and preserved the main qualitative pattern. ## How information filtering works TMFG builds a network under a fixed structural rule. It begins with four nodes that have strong associations within the correlation matrix. Each remaining node is added to the triangular location where its connections contribute the greatest total association. This sequential construction produces a connected graph made of linked triangles. A TMFG with $p$ nodes retains exactly $3(p-2)$ edges. The edge count grows linearly with the number of nodes, while the number of all possible pairs grows quadratically. The method therefore performs stronger filtering in larger networks. Edge selection is determined by the structure as a whole, so TMFG is not a simple list of the globally largest correlations. LoGo uses the triangular structure to estimate the conditional network. The TMFG graph can be decomposed into overlapping groups of four nodes and their shared three-node separators. LoGo combines covariance information from these small blocks to obtain the precision matrix. This construction yields partial correlations on the TMFG support without a penalty parameter or an iterative optimization path. ## Mathematical foundations This section states the structural and statistical identities precisely. It can be skipped when the practical workflow is the main interest. ### TMFG edge count TMFG begins with a four-node clique containing six edges. Each subsequent node is inserted into one triangular face and connected to its three corners. Every insertion adds one node and three edges. A network with $p$ nodes therefore has $$ 6 + 3(p-4) = 3(p-2) $$ edges. The insertion rule preserves planarity and chordality throughout the construction. ### LoGo precision matrix Let $\mathbf{S}$ be the sample correlation matrix, $\mathcal{C}$ the set of four-node cliques, and $\mathcal{T}$ the set of three-node separators. LoGo constructs the precision matrix as $$ \widehat{\mathbf{K}} = \sum_{c \in \mathcal{C}} [\mathbf{S}_{cc}^{-1}]^{0} - \sum_{t \in \mathcal{T}} [\mathbf{S}_{tt}^{-1}]^{0}, $$ where the superscript $0$ denotes placement of each inverse block into the full $p \times p$ matrix with zeros outside that block. The required block inverses must exist, so duplicate or perfectly collinear variables must be resolved before fitting LoGo. The partial correlation between nodes $i$ and $j$ is $$ \rho_{ij \cdot \mathrm{rest}} = -\frac{K_{ij}}{\sqrt{K_{ii}K_{jj}}}. $$ ### Numerical certificate Let $\mathbf{W} = \widehat{\mathbf{K}}^{-1}$. On every retained edge and every diagonal entry, the fitted covariance $\mathbf{W}$ equals the corresponding entry of $\mathbf{S}$. Precision entries outside the TMFG support are zero. `certificate()` reports the largest absolute discrepancy across these conditions. A value near machine precision indicates that the LoGo construction satisfies the defining identities to numerical precision. ### Predictability For node $j$, LoGo predictability follows from the diagonal precision entry: $$ R_j^2 = 1 - \frac{1}{K_{jj}S_{jj}}. $$ `net_predict()` evaluates this identity for every node in the conditional network.