q2-gglasso Parameter Reference

Every parameter of every registered q2-gglasso action, with its CLI spelling, its type as registered with QIIME 2, its default as declared in the function signature, and the chapter where the tutorial exercises it.

Turn to Troubleshooting when a flag does something other than what you expected. Command Coverage Matrix lists which actions the tutorial covers at all.

Important

These tables are maintained by hand today and can drift away from the plugin. The intended end state is to capture qiime gglasso <action> --help into docs/_data/help/gglasso-<action>.txt at build time, render it with {literalinclude}, and add a CI check asserting that the documented parameter set equals the set registered in q2_gglasso/plugin_setup.py and q2_gglasso/_dict.py. That generation step is not wired up yet. Until it is, treat --help on your own install as the final authority and open an issue wherever the tables disagree with it.

Note

Every name, type and default below was read directly from q2_gglasso/plugin_setup.py, q2_gglasso/_dict.py and the function signatures in q2_gglasso/_func.py. They have not yet been checked against captured --help output from a QIIME 2 2026.7 build, because that environment does not exist yet. None of it is a recorded command output.

How to read the tables

QIIME 2 derives every CLI flag mechanically from the registered name: a parameter foo_bar becomes --p-foo-bar, an input becomes --i-foo-bar, an output --o-foo-bar, and a Metadata parameter becomes --m-foo-bar-file. Underscores in the registered name are not collapsed, which is why the deprecated cv__nlam in the sibling plugin surfaces as --p-cv--nlam.

List[...] parameters are repeatable options on the command line: pass the flag once per value (--p-lambda1-path 1.0 --p-lambda1-path 0.1 ...). Several List[...] parameters here — the lambda*_min/lambda*_max/mu1_* bounds — are registered as lists but consumed as scalars, so in practice you pass them exactly once. (n_samples is the exception: pass it once per instance.)

Two conventions used in the Notes column:

• always raises — the parameter is registered and accepted by the CLI, but every call that sets it fails. It exists so the limitation is explicit rather than silently ignored.

• no Choices() — the plugin does not constrain the accepted strings, so a typo passes argument parsing and fails, or is silently accepted, inside the function. See “String parameters have no validation” below.

The Demonstrated in column names the chapter that exercises the parameter, or the closest chapter that discusses it. not demonstrated means no runnable command in this tutorial passes the parameter; it may still be discussed in prose, and it says nothing about whether the parameter works.

transform-features

Turns a count table into a CLR- or mCLR-transformed table suitable for covariance estimation. Optionally joins scaled sample metadata onto the table as extra rows, which is how continuous covariates enter the network.

Inputs and outputs

Name	CLI flag	Type	Required	Notes
table	--i-table	FeatureTable[Composition | Frequency | Design]	yes
taxonomy	--i-taxonomy	FeatureData[Taxonomy]	yes	Required but never read. The function body ignores it entirely.
transformed_table	--o-transformed-table	FeatureTable[Frequency]	yes	Output is stored feature-major (p x n).

Parameters

Parameter	CLI flag	Type	Default	Demonstrated in	Notes
sample_metadata	--m-sample-metadata-file	Metadata	None	Data Preparation	Only read when add_metadata is True.
transformation	--p-transformation	Str	clr	Data Preparation	clr or mclr. No Choices() — a typo is a runtime ValueError.
pseudo_count	--p-pseudo-count	Int	1	The 300-ASV Dataset	Zero replacement before the log. Only meaningful for clr; mclr handles zeros itself.
scale_metadata	--p-scale-metadata	Bool	True	Data Preparation	Standardises metadata columns before joining.
add_metadata	--p-add-metadata	Bool	False	Data Preparation	Appends metadata columns as additional variables of the network. Only numeric columns are used — filter_columns(column_type='numeric') silently drops categorical ones, so a categorical covariate never becomes a node. Missing values in the retained columns are filled with 0 behind a Missing values are imputed with 0! warning.
keep_original_id	--p-keep-original-id	Bool	True	The 300-ASV Dataset	Rows are always reordered by ascending total abundance, at either setting, with ties broken on the feature ID so the order depends only on the table’s contents. With False the index is additionally replaced by ASV-1 … ASV-p, so ASV-1 is the least abundant feature. ASV-k is a position, not an identifier — it is only meaningful inside the artifact that defines it and must never be used as a join key across artifacts. Ties are common (209 of the 300 Atacama features share a total-abundance value), so before ties were broken deterministically the same table could yield different ASV-k assignments. Prefer the default.

add_metadata decides what kind of question the network answers: with it off you get taxon-taxon conditional dependencies only; with it on, environmental covariates become nodes and a taxon-covariate edge means the association survives conditioning on every other taxon. scale_metadata matters because the CLR-transformed taxa and a raw covariate such as elevation live on very different scales, and the graphical lasso applies one global lambda1 to all of them — leaving a covariate unscaled effectively changes its penalty relative to everything else.

Note

The registration requires --i-taxonomy and the implementation never reads it. Pass any valid FeatureData[Taxonomy] artifact; its contents cannot change the result. Troubleshooting tracks this.

build-groups

Builds the bookkeeping array that a non-conforming Group Graphical Lasso needs when the K instances do not share the same feature set.

Name	CLI flag	Type	Default	Demonstrated in	Notes
tables	--i-tables	List[FeatureTable[Frequency]]	required	Multiple Graphical Lasso	Repeat the flag once per instance.
check_groups	--p-check-groups	Bool	True	Multiple Graphical Lasso	Validates the constructed overlap groups.
group_array	--o-group-array	TensorData	required	Multiple Graphical Lasso	(2, L, K) index array: L overlap groups across K instances.

Important

Known gap: build-groups does not chain into solve-problem. This action emits a TensorData artifact, while solve-problem accepts group_array as a List[Int] parameter. The QIIME 2 type system cannot connect the two: export the artifact and pass the indices explicitly with --p-group-array. Multiple Graphical Lasso writes out the workaround.

calculate-covariance

Name	CLI flag	Type	Default	Demonstrated in	Notes
table	--i-table	FeatureTable[Frequency]	required	Data Preparation	Expects the p x n output of transform-features.
method	--p-method	Str	scaled	Data Preparation	scaled divides by the square root of the diagonal (a correlation matrix); unscaled returns the raw covariance. No Choices().
bias	--p-bias	Bool	True	The 300-ASV Dataset	True normalises by N, False by N-1.
covariance_matrix	--o-covariance-matrix	PairwiseFeatureData	required	Data Preparation	p x p, rounded to 10 decimals.

A single lambda1 penalises every entry of the precision matrix equally, so on an unscaled covariance the taxa with the largest variance absorb the penalty budget. method defaults to scaled for that reason, and the tutorial uses it throughout.

solve-problem

The core solver. Twenty parameters, but they fall into five groups: how big the problem is, the sparsity grid, the low-rank grid, the multiple-instance settings, and model selection.

Inputs and outputs

Name	CLI flag	Type	Notes
covariance_matrix	--i-covariance-matrix	PairwiseFeatureData	p x p, positive semi-definite.
solution	--o-solution	GGLassoProblem	Zarr store holding the solution and the hyperparameters used.

Parameters

Parameter	CLI flag	Type	Default	Demonstrated in	Notes
n_samples	--p-n-samples	List[Int]	required	Single Graphical Lasso	Number of samples behind the covariance estimate; one value per instance. The only parameter with no default.
lambda1_min	--p-lambda1-min	List[Float]	None	Single Graphical Lasso	Lower bound of the sparsity grid. If unset while lambda1_max is set, falls back to 1e-3.
lambda1_max	--p-lambda1-max	List[Float]	None	Single Graphical Lasso	Upper bound of the sparsity grid. If unset while lambda1_min is set, falls back to 1.
n_lambda1	--p-n-lambda1	Int	1	Single Graphical Lasso	Grid points between min and max. Leaving it at 1 only limits the lambda1 grid to one point; on its own it does not turn model selection off — see “When model selection runs” below.
lambda1_path	--p-lambda1-path	List[Float]	None	Lambda Paths	Explicit grid. Overrides lambda1_min/lambda1_max/n_lambda1 and path_scale; values are used verbatim.
lambda2_min	--p-lambda2-min	List[Float]	None	Multiple Graphical Lasso	Across-instance penalty, MGL only. Same 1e-3 fallback.
lambda2_max	--p-lambda2-max	List[Float]	None	Multiple Graphical Lasso	Same 1 fallback.
n_lambda2	--p-n-lambda2	Int	1	Multiple Graphical Lasso
mu1_min	--p-mu1-min	List[Float]	None	Sparse + Low-Rank	Low-rank penalty. Only used when latent is True.
mu1_max	--p-mu1-max	List[Float]	None	Sparse + Low-Rank
n_mu1	--p-n-mu1	Int	1	Choosing the Latent Rank
mu1_path	--p-mu1-path	List[Float]	None	Lambda Paths	Explicit low-rank grid; overrides mu1_min/mu1_max/n_mu1 and path_scale. Ignored unless latent is True.
path_scale	--p-path-scale	Str	log	Lambda Paths	log or linear spacing when a grid is built from min/max/count. Ignored when an explicit path is given. No Choices() — an unrecognised value raises ValueError, but only once a grid is actually built from bounds: with every lambda1/lambda2/mu1 bound unset the misspelling is never reached.
latent	--p-latent	Bool	None	Sparse + Low-Rank	Switches on the sparse + low-rank decomposition. Required for pca.
rank	--p-rank	Int	None	Choosing the Latent Rank	Always raises. See the box below.
weights	--p-weights	List[Str]	None	Adaptive Graphical Lasso	entry weight pairs, applied element-wise to lambda1. Later entries override earlier ones, so order matters. SGL only.
non_conforming	--p-non-conforming	Bool	None	Multiple Graphical Lasso	Instances with differing feature sets; requires group_array.
group_array	--p-group-array	List[Int]	None	Multiple Graphical Lasso	A parameter, not an input — see the build-groups gap above.
reg	--p-reg	Str	GGL	Multiple Graphical Lasso	GGL (group) or FGL (fused). MGL only. No Choices().
gamma	--p-gamma	Float	0.01	Model Selection	eBIC parameter in [0, 1]. Larger values push model selection toward sparser solutions.

Important

--p-rank always raises — ValueError if --p-latent is not set, NotImplementedError otherwise. No released GGLasso (up to and including 0.3.0) can fix the rank of the low-rank component; it exposes only the continuous mu1 penalty and reports the achieved rank as an output. The parameter is registered and guarded so that setting it fails loudly instead of being ignored.

Size the low-rank block through mu1 instead: a larger mu1 gives a smaller rank. Scout a small mu1 grid and read the achieved rank out of the solution — Choosing the Latent Rank walks through this. Setting rank without latent=True raises ValueError before the version check is reached.

Substituted defaults

Leave a grid entirely unset and the solver substitutes a built-in path, emitting a warning rather than failing:

Grid	Substituted when both bounds are unset	Warning
lambda1	np.logspace(0, -4, 15)	Default values for lambda1 have been used.
lambda2	np.logspace(-1, -4, 5)	Default values for lambda2 have been used.
mu1 (only if latent=True)	np.logspace(2, -1, 10)	Default values for mu1 have been used.

Setting only one of the two bounds does not trigger this. A missing lower bound silently becomes 1e-3 and a missing upper bound silently becomes 1, which is easy to mistake for a grid you specified yourself.

When model selection runs

Model selection runs whenever at least one grid ends up with more than one value, and the grids the solver sees are the ones left after it has filled in the defaults above. That substitution is what makes single fits harder to get than the flags suggest:

• Non-latent (SGL/MGL). A run counts as a single fit only if lambda1 collapses to one value and at least one of --p-lambda2-min/ --p-lambda2-max is set (with --p-n-lambda2 1). Leave lambda2 unset and the solver substitutes the 5-point default grid even for SGL, so model_selection is on and modelselect_stats is written. Pinning --p-lambda1-min/--p-lambda1-max to the same value, or passing a one-element --p-lambda1-path, is not enough on its own.

• Latent (--p-latent True). lambda1, lambda2 and mu1 must all collapse to a single value. Supplying a lambda1 range while forgetting mu1 — or the reverse — produces a grid search when you expected one fit.

Look for a modelselect_stats group in the solution: a genuine single fit has none, and summarize omits the statistics accordingly. Because of the lambda2 substitution, most non-latent runs will have one.

Note

This describes current solver behaviour, not a design decision. Applying the lambda2 default only to MGL problems would be the cleaner fix, but that is a behaviour change in q2_gglasso/utils.py and needs a maintainer decision. The same inaccurate “n_lambda1 == 1 means a single fit” rule is repeated as a code comment in q2_gglasso/_summarize/_visualizer.py.

pca (visualizer)

Projects samples onto the principal components of the low-rank component of an SLR solution.

Name	CLI flag	Type	Default	Demonstrated in	Notes
table	--i-table	FeatureTable[Frequency]	required	PCA of the Latent Space	The transformed table, p x n.
solution	--i-solution	GGLassoProblem	required	PCA of the Latent Space	Must have been solved with --p-latent True.
sample_metadata	--m-sample-metadata-file	Metadata	None	PCA of the Latent Space	Optional in the signature, required in practice — the visualizer dereferences it unconditionally.
n_components	--p-n-components	Int	3	Latent PCA	Number of components to plot.
color_by	--p-color-by	Str	None	PCA of the Latent Space	Name of a metadata column. Must exist in the file passed above.

Note

Two failure modes, both easy to hit:

• Running pca on a sparse-only (SGL) solution fails, because the visualizer reads solution/lowrank_, which only exists when --p-latent True was used.

• Omitting --m-sample-metadata-file crashes with an AttributeError despite the parameter being optional in the signature. Treat it as required.

summarize (visualizer)

Name	CLI flag	Type	Default	Demonstrated in	Notes
solution	--i-solution	GGLassoProblem	required	Summarize	Works for sparse-only and latent solutions alike.
width	--p-width	Int	1500	Summarize	Plot width in pixels.
height	--p-height	Int	1500	Summarize	Plot height in pixels.
label_size	--p-label-size	Str	5pt	Single Graphical Lasso	A bokeh font-size string, e.g. 25pt. Raise it for small networks; the default is sized for hundreds of nodes.
n_cov	--p-n-cov	Int	None	Summarize	Number of trailing variables that are covariates rather than taxa. When set, the heatmaps cluster the taxon block and the covariate block separately instead of mixing them. Set this if you used --p-add-metadata True.

String parameters have no validation

Neither plugin declares Choices() on any string parameter. QIIME 2 therefore accepts any string, and the check happens inside the function — if it happens at all. In q2-gglasso this affects:

Flag	Accepted values	Behaviour on a typo
--p-transformation	clr, mclr	ValueError inside transform-features
--p-method	scaled, unscaled	ValueError inside calculate-covariance
--p-path-scale	log, linear	ValueError inside grid construction — but only if at least one of the lambda1/lambda2/mu1 bounds is set; with every grid unbounded (or driven entirely by an explicit --p-lambda1-path/--p-mu1-path) the misspelling is silently ignored
--p-reg	GGL, FGL	Reaches the solver; behaviour depends on the GGLasso build
--p-label-size	any CSS size string	No validation; a bad value degrades the plot silently

A typo therefore costs you a whole run rather than being caught at argument-parsing time. On a 13-ASV problem that is a minor annoyance. On the 300-ASV Atacama problem of tier 2 it is the entire solve. Check the spelling before you submit the job.

See also

• q2-classo Parameter Reference

• Troubleshooting & Known Failure Modes

• Command Coverage Matrix