Summarizing a Solution

Chapters 02, 03 and 05 end with a qiime gglasso summarize call that sets only --p-label-size; chapter 04 adds --p-n-cov. Chapters 01, 06 and 07 do not call it at all. The remaining parameters size the heatmaps and split taxa from covariates, and two of the four tabs in the .qzv change shape depending on how the solution was fitted.

summarize accepts any single-instance GGLassoProblem artifact, sparse or latent. Use it to look at a solution before you export anything.

Note

Multi-group solutions — MGL and the non-conforming variant — are not handled. The visualizer builds its tables by wrapping the stored covariance and precision arrays in a DataFrame with no dimension check, which a \(K \times p \times p\) stack cannot satisfy. The failure is unreachable: Multiple Graphical Lasso sets out, in its gap 3, that a stack of \(K\) covariance matrices cannot be supplied through the QIIME 2 interface at all, so no such solution artifact can be produced to pass here. Pending verification against QIIME 2 2026.7.

Running the visualizer

qiime gglasso summarize \
    --i-solution data/atacama-solution-slr.qza \
    --p-width 900 \
    --p-height 900 \
    --p-label-size 12pt \
    --o-visualization data/slr-summary-annotated.qzv

Explanation:

• --i-solution: the solution artifact from solve-problem.

• --p-width / --p-height: heatmap size in pixels, 1500 each by default.

• --p-label-size: tick-label font, "5pt" by default.

• --p-n-cov: number of trailing covariate columns; unset by default. A wrong value mislabels the heatmap without raising anything.

• --o-visualization: open with qiime tools view or at QIIME 2 View.

Note

No QIIME 2 2026.7 environment exists yet, so the .qzv has not been regenerated. Its rendered output is pending verification against QIIME 2 2026.7.

Sizing: --p-width, --p-height, --p-label-size

The heatmap is drawn at a fixed pixel size regardless of how many features it contains, so the three sizing parameters interact with p rather than being cosmetic. At the default 1500 × 1500 the 13-ASV Atacama matrix gives enormous cells and a lot of whitespace, which is why the earlier chapters pair it with a large --p-label-size 25pt; the same 1500 px spread over the 300-ASV table of the high-dimensional chapters gives cells a few pixels wide, where the default "5pt" labels are the only ones that fit.

Keep width and height equal — the matrix is square and a non-square canvas distorts the diagonal — and scale the label size so that p × label height stays under the canvas height. If labels still collide, the plot is zoomable and the hover tooltip reports taxa_x, taxa_y and the cell value, so an unreadable axis is an inconvenience rather than a loss of information.

--p-label-size is a string handed straight to bokeh and is not validated by the plugin, so give it a proper CSS-style font size with a unit ("5pt", "12pt", "25pt"). A bare number is rejected by bokeh, not by QIIME 2, so the error arrives late and mentions a property name rather than your flag.

--p-n-cov must match the appended covariates

When you run transform-features --p-add-metadata True, the numeric metadata columns are standardized and joined onto the transformed table, and they end up as the last rows and columns of the covariance matrix that calculate-covariance produces. The matrix is therefore blocked: an ASV × ASV block, an ASV × covariate block, and a small covariate × covariate block.

summarize reorders rows and columns by hierarchical clustering (average linkage, Euclidean distance) so that block structure is visible. Reordering is not optional — there is no flag to switch it off. --p-n-cov tells it how many trailing entries are covariates: with the parameter set, only the ASV block is clustered and reordered, and the covariate rows and columns are pinned at the edge of the matrix in their original order. Covariates shuffled into the middle of a taxon dendrogram are unreadable.

Note

If --p-n-cov does not equal the number of columns actually appended, the split happens in the wrong place. Some ASVs get pinned as if they were covariates, some covariates get clustered as if they were ASVs, and the axis labels stop corresponding to the cells they sit next to. Nothing errors — you get a plausible-looking heatmap that is wrong.

Count the covariates the way transform-features does: only numeric metadata columns are appended, because the metadata is filtered by column type first. A categorical column in your metadata file is not appended and must not be counted. That is why Adaptive Graphical Lasso, whose metadata file selected-atacama-sample-metadata.tsv carries exactly four numeric covariates — ph, average-soil-relative-humidity, elevation and average-soil-temperature — passes --p-n-cov 4. The file that does carry a categorical vegetation column is atacama-selected-covariates-veg.tsv, but that is the q2-classo covariate file, not the one chapter 04 hands to transform-features.

If you did not use --p-add-metadata, leave --p-n-cov unset rather than passing 0. Unset means one block, cluster everything, which is correct for a pure ASV covariance. Zero takes a different code path: because -0 == 0, the ASV slice iloc[:-0, :-0] comes out empty while the covariate slice iloc[-0:, -0:] swallows the whole matrix, and the clustering step is handed an empty frame.

The four tabs

Sample covariance

The input matrix S — exactly what calculate-covariance produced — after clustering. Use it as the “before” picture: whatever structure the graphical lasso later attributes to direct edges should be visible here as marginal correlation.

The clustering order is computed from this matrix and then reused verbatim for the precision heatmap, so the two tabs are cell-for-cell comparable.

The colour scale is fixed to [-1, 1], red for positive and blue for negative, and is not rescaled to the data. With calculate-covariance --p-method scaled (the default, i.e. a correlation matrix) that is exactly right. With --p-method unscaled the entries are unbounded, everything beyond ±1 saturates to solid red or blue, and the tab becomes uninformative. If you need to view an unscaled covariance, expect that limitation.

Estimated inverse covariance

The fitted precision matrix Θ, which is the result itself: an off-diagonal entry that is nonzero is an edge, and a zero is a conditional independence.

The tab is titled “Estimated inverse covariance”, but the matrix drawn is negated — the plot title inside the tab says “Estimated (negative) inverse covariance”. Precision entries carry the opposite sign to the corresponding partial correlation, so negating restores the intuitive reading: red means a positive partial association, consistent with the sample covariance tab next to it. Without the flip, every association would appear to change sign between the two tabs.

Low-rank

The low-rank component L. This tab exists only for latent solutions — those fitted with --p-latent True, as in Sparse + Low-Rank. For a sparse-only SGL solution there is no lowrank_ group and the tab is absent; the visualizer logs NO low-rank solution has been found., which you will see if you pass --verbose.

Read it as the counterpart to the sparse tab: dense, smooth, no isolated cells. Bands of taxa moving together here are the global structure that the sparse component was relieved of. To turn that into a per-sample statement, project it with pca.

Note

The tab is built inside a try block whose except catches everything and emits the same NO low-rank solution has been found. message. Any failure while rendering the low-rank heatmap — not only a genuinely missing component — is therefore reported as an absent low-rank solution, and the tab disappears from a latent solution with no traceback. In the current sources, the clustered low-rank branch calls the reordering helper with an argument name that helper does not accept, and it derives a fresh clustering order from the already reordered covariance matrix rather than reusing the one applied to the other tabs. Both would be swallowed in exactly this way. Whether the tab renders, and in what order, is pending verification against QIIME 2 2026.7. If a latent solution shows only three tabs, this is the first thing to check.

Statistics

Tables rather than heatmaps, and the tab whose contents depend most on how you fitted the model.

If the solution came from a model-selection run — a grid with more than one value — the tab shows one row per grid point with sparsity, lambda, mu and rank, followed by a summary table giving the selected best lambda, best mu, and the percentage of positive edges. That per-grid-point table is where you read the achieved rank needed by pca --p-n-components, and where you see how sparsity responds to λ₁ before committing to a value; the fuller treatment is in Regularization Paths & Model Selection.

If the solution came from a single fit, none of that exists. The solver writes no modelselect_stats group, so the grid table and the best-parameter table are both omitted and the tab is reduced to the positive-edge percentage alone.

Important

A single fit is harder to get than it looks. Model selection runs unless every grid collapses to exactly one value: lambda1 and lambda2 for a sparse problem, plus mu1 for a latent one. Leaving --p-lambda2-min / --p-lambda2-max unset does not count as one value — an unset pair of bounds expands to the 5-point default np.logspace(-1, -4, 5) and warns Default values for lambda2 have been used., which is more than one value and so forces model selection on. Since none of the commands in these chapters pin λ₂, all of them run model selection and all of them get the full statistics tab.

The likely accident is therefore the opposite of what you might expect: you ask for a single fit and get a path. To obtain one, pin λ₂ explicitly (and μ₁ too, if latent) to a single value each. λ₂ is not used by the single-instance solver at all — it only decides this branch. A reduced statistics tab is the symptom of a genuine single fit. See Troubleshooting.

The table to the right of the grid and best-parameter tables — not below them — lists the precision-matrix entries pair by pair, with the diagonal removed and the taxon labels substituted in. It is sortable, and it is the quickest way to get a ranked edge list out of the visualization without exporting the artifact.

Important

Treat the taxon names in that pair table with suspicion until they are checked. In the current sources, the table is built from the precision matrix as stored — in the original feature order — while the labels substituted into it are the ones renumbered by the clustering applied to the heatmaps. Wherever clustering changes the order, which is almost always, the two would not line up, and the values would carry the wrong pair of names. The magnitudes themselves are unaffected. Pending verification against QIIME 2 2026.7; until then, confirm any edge you intend to report against the heatmap hover tooltip, which is built from the reordered matrix and its matching labels.

The complete parameter list for all six actions is in the q2-gglasso parameter reference.