q2-classo Parameter Reference

Every parameter of every registered q2-classo 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.

regress and classify carry most of the surface area — 36 and 34 registered parameters respectively — and almost none of them describe the model itself. They describe the four model-selection procedures c-lasso can run on the same fitted path: PATH, CV, StabSel and LAMfixed. Each procedure has its own prefix, its own on/off switch, and its own numerical method.

Use Troubleshooting when a flag misbehaves, and Command Coverage Matrix for which actions the tutorial covers.

Important

These tables are maintained by hand and can drift away from the plugin. The intended end state is to capture qiime classo <action> --help into docs/_data/help/classo-<action>.txt at build time, render it with {literalinclude}, and add a CI check that asserts the documented parameter set equals the set registered in q2_classo/plugin_setup.py and q2_classo/_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 where this page disagrees with it.

Note

Every name, type and default below was read from q2_classo/plugin_setup.py, q2_classo/_dict.py and the function signatures in q2_classo/_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.

Flag spelling and table conventions

QIIME 2 derives every CLI flag mechanically: a parameter foo_bar becomes --p-foo-bar, an input --i-foo-bar, an output --o-foo-bar, a Metadata parameter --m-foo-bar-file, and a MetadataColumn parameter the pair --m-foo-bar-file plus --m-foo-bar-column. Underscores are not collapsed, which is why the deprecated cv__nlam surfaces as --p-cv--nlam with two dashes.

Conventions in the Notes column:

• deprecated — still accepted, emits a DeprecationWarning, will be removed.

• no Choices() — the plugin does not constrain the accepted strings; 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 the parameter is never passed in a runnable command in this tutorial — it may still be discussed in prose or listed in a chapter’s own parameter table. It says nothing about whether the parameter works.

generate-data

Builds a synthetic log-contrast problem with a known ground-truth support. Use it to check that your invocation works before you point it at real data.

Name	CLI flag	Type	Default	Demonstrated in	Notes
taxa	--i-taxa	FeatureData[Taxonomy]	None	Generate Data	If given, feature labels are drawn from the taxonomy and a tree matrix is built.
n	--p-n	Int	100	Generate Data	Number of samples.
d	--p-d	Int	80	Generate Data	Number of features.
d_nonzero	--p-d-nonzero	Int	5	Generate Data	Size of the true support.
classification	--p-classification	Bool	False	Generate Data	When True, the response is binary.
x	--o-x	FeatureTable[Design]	required	Generate Data
c	--o-c	ConstraintMatrix	required	Generate Data	Zero-sum constraint.

Important

Known bug: generate-data writes randomy.tsv into your current working directory. The generated response vector is not returned as an artifact. The action writes it to a fixed relative path as a side effect. Run this action from a directory you do not mind writing into, and expect the file to be overwritten on every call. The response you then pass to regress comes from that file.

transform-features

Name	CLI flag	Type	Default	Demonstrated in	Notes
features	--i-features	FeatureTable[Composition | Frequency | Design]	required	Data Preparation
transformation	--p-transformation	Str	clr	Data Preparation	clr is the only accepted value. Anything else raises ValueError. No Choices().
coef	--p-coef	Float	0.5	Data Preparation	Pseudocount substituted for non-positive entries before the log.
x	--o-x	FeatureTable[Design]	required	Data Preparation

This is a different CLR implementation from qiime gglasso transform-features: it takes a coef rather than a pseudo_count, has no mclr option, has no metadata handling, and preserves the orientation it is given, centring along rows — it assumes samples in rows, which is what the QIIME 2 FeatureTable view supplies and what regress expects. It does not transpose, so a feature-major input is silently CLR-ed along the wrong axis. The two are not interchangeable.

add-taxa

Replaces the feature matrix log(X) with log(X)A, where A encodes the taxonomic tree — the change of basis that turns a plain log-contrast model into trac.

Name	CLI flag	Type	Notes
features	--i-features	FeatureTable[Design | Frequency]
weights	--i-weights	Weights	Optional; defaults to the all-ones vector.
taxa	--i-taxa	FeatureData[Taxonomy]	Converted to a tree internally.
x	--o-x	FeatureTable[Design]	Columns are now internal nodes plus leaves.
aweights	--o-aweights	Weights	Each node’s weight divided by its number of leaves.

The action has no parameters. The leaf-count rescaling of the weights makes coarse taxonomic ranks comparable with fine ones, and it is not optional.

add-covariates

Appends metadata columns to the feature matrix and extends the constraint matrix and weight vector to match. A covariate added this way enters the model without being subject to the zero-sum constraint.

Name	CLI flag	Type	Default	Demonstrated in	Notes
features	--i-features	FeatureTable[Design | Frequency]	None (optional)	Data Preparation	Registered as optional, but required in practice — see the note below.
c	--i-c	ConstraintMatrix	None (optional)	Data Preparation	Genuinely optional; falls back to an all-ones constraint row.
weights	--i-weights	Weights	None	Data Preparation	Defaults to all ones, length = number of features.
covariates	--m-covariates-file	Metadata	required	Data Preparation	The metadata file the columns come from.
to_add	--p-to-add	List[Str]	required	Data Preparation	Column names to append; repeat the flag once per column.
rescale	--p-rescale	List[Bool]	None	Cross-Validation	One value per entry of to_add, or a length mismatch raises ValueError. Defaults to all False.
w_to_add	--p-w-to-add	List[Float]	None	Data Preparation	Penalty weight per added covariate; same length rule. Defaults to all 1.0.
new_features	--o-new-features	FeatureTable[Design]	required	Data Preparation
new_c	--o-new-c	ConstraintMatrix	required	Data Preparation	Zeros in the new columns, i.e. the added covariates are exempt from the constraint.
new_w	--o-new-w	Weights	required	Data Preparation

Note

--i-features and --i-c are both registered as optional inputs (--help prints [optional] for both), but only --i-c is genuinely optional: omitting it falls back to an all-ones constraint row. Omitting --i-features fails with AttributeError: 'NoneType' object has no attribute 'columns' rather than a CLI usage error, so treat it as required. Only --m-covariates-file and --p-to-add are marked [required].

Two behaviours affect the design matrix this action produces:

Categorical columns. These are one-hot expanded, and the generated column labels have the form <name> = <value> — with spaces around the equals sign. Those labels appear in the summarize coefficient plots, so a categorical covariate contributes several rows to the output, not one.

Rescaling. rescale applies to numeric columns only, where it centres the column and divides by its norm. The log-contrast features are CLR values of order one, so an unrescaled covariate measured in metres or in cells per gram will dominate or vanish relative to them under a shared penalty. Setting the corresponding w_to_add entry is the other lever on the same problem.

regress

Constrained sparse log-contrast regression. 36 registered parameters: 35 current plus one deprecated alias.

Inputs and outputs

Name	CLI flag	Type	Notes
features	--i-features	FeatureTable[Design | Frequency]	Samples in rows.
c	--i-c	ConstraintMatrix	Defaults to the zero-sum constraint when omitted.
weights	--i-weights	Weights	Per-feature penalty weights. Shorter than the feature count is padded with ones; longer is truncated.
result	--o-result	CLASSOProblem	Zarr store with every model selection that was run.

Response and formulation

These six choose the loss and the constraint structure — the statistical model itself. The parameters that follow affect only how lambda is chosen.

Parameter	CLI flag	Type	Default	Demonstrated in	Notes
y	--m-y-file / --m-y-column	MetadataColumn[Numeric]	required	Log-contrast Regression	Samples missing from y are dropped after an inner join and reported.
do_yshift	--p-do-yshift	Bool	False	Cross-Validation	Centres y before fitting. Not present on classify.
concomitant	--p-concomitant	Bool	True	Concomitant Formulation	Joint M-estimation of the noise level sigma. Not present on classify.
huber	--p-huber	Bool	False	Concomitant Formulation	Robust loss; combine with concomitant for the Huber-concomitant formulation.
rho	--p-rho	Float	1.345	Concomitant Formulation	Huber transition point. Only meaningful when huber is True. classify defaults this to 0.0.
intercept	--p-intercept	Bool	True	Cross-Validation	Adds an unpenalised intercept, which appears in the output as a coefficient labelled intercept.

Set concomitant deliberately rather than inheriting its default of True. It estimates sigma jointly with beta, which makes the selected lambda scale-free with respect to the noise level — desirable, but it also changes which numerical methods are available and therefore what *_numerical_method can legally be.

PATH parameters

Computes the full regularization path. On by default.

Parameter	CLI flag	Type	Default	Demonstrated in	Notes
path	--p-path	Bool	True	Model Selection	Registered default is True despite the parameter description saying False.
path_numerical_method	--p-path-numerical-method	Str	not specified	not demonstrated	Path-Alg, P-PDS, PF-PDS or DR. The default string means “let c-lasso choose”. No Choices() — and because the default is itself an unrecognised literal, a typo is silently accepted.
path_n_active	--p-path-n-active	Int	0	Model Selection	Stop once this many variables are active. 0 means no early stop.
path_nlam_log	--p-path-nlam-log	Int	40	Model Selection	Number of lambdas on the log-spaced path.
path_lamin_log	--p-path-lamin-log	Float	1e-2	Model Selection	Smallest lambda as a fraction of lambda_max.

CV parameters

K-fold cross-validation over the path. On by default.

Parameter	CLI flag	Type	Default	Demonstrated in	Notes
cv	--p-cv	Bool	True	Cross-Validation
cv_numerical_method	--p-cv-numerical-method	Str	not specified	not demonstrated	As path_numerical_method. No Choices().
cv_seed	--p-cv-seed	Int	1	Cross-Validation	Fold assignment seed. Fixed by default, so repeated runs agree — change it to check fold stability.
cv_one_se	--p-cv-one-se	Bool	True	Cross-Validation	Select lambda by the one-standard-error rule rather than the CV minimum.
cv_subsets	--p-cv-subsets	Int	5	Cross-Validation	Number of folds.
cv_nlam	--p-cv-nlam	Int	100	Model Selection	Lambdas on the CV path. Current spelling.
cv__nlam	--p-cv--nlam	Int	None	Cross-Validation	Deprecated alias of cv_nlam — note the double underscore and the double dash. Still works, emits a DeprecationWarning. Passing both raises only when cv_nlam was changed from its default of 100 and the two values differ; --p-cv-nlam 100 --p-cv--nlam 50 does not raise — it silently uses 50.
cv_lamin	--p-cv-lamin	Float	1e-3	Cross-Validation	Smallest lambda on the CV path.
cv_logscale	--p-cv-logscale	Bool	True	Cross-Validation	Log-spaced CV path.

Note

--p-cv-nlam and --p-cv-lamin define a separate grid from --p-path-nlam-log and --p-path-lamin-log. Changing the PATH grid does not change what CV searches over, so the CV-selected lambda can be absent from the plotted path.

Important

Open docs issue. The only runnable commands that pass this grid’s size use the deprecated spelling: Cross-Validation invokes --p-cv--nlam, not --p-cv-nlam. Rule 5 of Command Coverage Matrix says --p-cv--nlam must not appear in a runnable command outside the quarantined chapters. Migrate those two commands to --p-cv-nlam.

StabSel parameters

Stability selection: refit on many subsamples and keep the features selected often enough. On by default, and generally the most trustworthy of the four procedures for microbiome data.

Parameter	CLI flag	Type	Default	Demonstrated in	Notes
stabsel	--p-stabsel	Bool	True	Model Selection
stabsel_numerical_method	--p-stabsel-numerical-method	Str	not specified	not demonstrated	As above. No Choices().
stabsel_seed	--p-stabsel-seed	Int	None	Model Selection	Unlike cv_seed, this defaults to unset, so subsampling is not reproducible unless you set it. Set it for anything you intend to report.
stabsel_method	--p-stabsel-method	Str	first	Model Selection	first, lam or max. Decides what is recorded per subsample. No Choices().
stabsel_lam	--p-stabsel-lam	Float	-1.0	not demonstrated	Only used when stabsel_method is lam. A negative value means “use the theoretical lambda”.
stabsel_true_lam	--p-stabsel-true-lam	Bool	True	not demonstrated	Only used when stabsel_method is lam. True = the value given is a real lambda; False = it is lambda/lambda_max in [0, 1].
stabsel_b	--p-stabsel-b	Int	50	Model Selection	Number of subsamples. The main runtime knob of the whole action.
stabsel_q	--p-stabsel-q	Int	10	Model Selection	Variables selected per subsample.
stabsel_percent_ns	--p-stabsel-percent-ns	Float	0.5	Model Selection	Subsample size as a fraction of n.
stabsel_lamin	--p-stabsel-lamin	Float	1e-2	not demonstrated	Only used when stabsel_method is max.
stabsel_threshold	--p-stabsel-threshold	Float	0.7	Model Selection	Selection frequency above which a feature is reported as selected.
stabsel_threshold_label	--p-stabsel-threshold-label	Float	0.4	Model Selection	Frequency above which a feature is labelled in c-lasso’s own matplotlib plot. Recorded in the artifact; not used by the QIIME 2 visualization.

stabsel_b, stabsel_q and stabsel_threshold interact. Raising q makes each subsample select more variables, which raises every feature’s selection frequency, so a threshold that was strict at q=10 becomes permissive at q=30. Change one at a time, and report all three alongside any selected feature set.

LAMfixed parameters

A single fit at one fixed lambda. On by default.

Parameter	CLI flag	Type	Default	Demonstrated in	Notes
lamfixed	--p-lamfixed	Bool	True	Model Selection
lamfixed_numerical_method	--p-lamfixed-numerical-method	Str	not specified	not demonstrated	As above. No Choices().
lamfixed_lam	--p-lamfixed-lam	Float	-1.0	Model Selection	Negative means “use the theoretical lambda once it is computed”.
lamfixed_true_lam	--p-lamfixed-true-lam	Bool	True	Model Selection	True = the value is a real lambda; False = it is lambda/lambda_max in [0, 1]. With True and lam = -1, the value becomes n * theoretical_lam.

Tip

All four procedures default to on, so a bare qiime classo regress runs PATH, CV, StabSel and LAMfixed in one call. StabSel refits the model stabsel_b times (50 by default) and usually dominates the cost. Turn off what you are not going to read: --p-cv False, --p-stabsel False, --p-lamfixed False.

Note

--help misreports several of these defaults. QIIME 2 renders the registered description text verbatim, so --help contradicts its own [default: ...] marker wherever the description in q2_classo/_dict.py has drifted from the function signature. In every case below the marker is right and the description is wrong. The tables above follow the signatures.

Parameter	--help prose says	Signature default
path	Default Value = False	True
cv	Default Value = False	True
lamfixed	Default Value = False	True
cv_seed	Default value : None	1
path_numerical_method	Default value : 'choose'	not specified
cv_numerical_method	Default value : 'choose'	not specified
stabsel_numerical_method	Default value : 'choose'	not specified
lamfixed_numerical_method	Default value : 'choose'	not specified
path_n_active	Dafault value : False	0

classify

Constrained sparse classification. 34 registered parameters: 33 current plus the same deprecated cv__nlam alias.

The PATH, CV, StabSel and LAMfixed blocks are identical to regress: same names, same types, same defaults. Read the four tables above and substitute classify for regress.

Inputs and outputs

Identical to regress: --i-features, --i-c, --i-weights, --o-result.

Differences from regress

Parameter	CLI flag	Type	Default	Demonstrated in	Notes
y	--m-y-file / --m-y-column	MetadataColumn[Categorical]	required	Log-contrast Classification	Categorical, not numeric. Must be binary; a non-binary column is rejected.
huber	--p-huber	Bool	False	Log-contrast Classification	Huber hinge loss.
rho	--p-rho	Float	0.0	Concomitant Formulation	Different default from regress (1.345).
intercept	--p-intercept	Bool	True	Cross-Validation
do_yshift	—	—	—	—	Does not exist on classify. Centring a categorical response is meaningless.
concomitant	—	—	—	—	Does not exist on classify. See the explanation below.

Important

qiime classo classify --p-concomitant does not exist. The concomitant formulation is unavailable for classification: the parameter is not registered, and the solver forces formulation.concomitant = False for classification problems regardless. Passing the flag is a CLI error, not a silently ignored option.

If you want the robustness that motivated concomitant, use the Huber hinge loss instead — --p-huber True, tuned via --p-rho. rho defaults to 0.0 here rather than 1.345 — it is wired to c-lasso’s formulation.rho_classification, a different field from regress’s formulation.rho, and 0.0 is a legal value for it (c-lasso requires only that it be strictly less than 1). The --help text for classify reports 1.345 (_dict.py:286) and is wrong. The registered default is 0.0, which is what every worked classify command in this book runs with. See Concomitant Formulation.

predict

Name	CLI flag	Type	Notes
features	--i-features	FeatureTable[Design | Frequency]	Columns are matched to the fitted model by label; an intercept column is synthesised.
problem	--i-problem	CLASSOProblem	Output of regress or classify.
predictions	--o-predictions	CLASSOProblem	One prediction set per model selection that was computed.

The action has no parameters. It emits a prediction for every model selection present in problem, so if you turned off CV and StabSel at fit time you get correspondingly fewer prediction sets here.

summarize (visualizer)

Name	CLI flag	Type	Default	Demonstrated in	Notes
problem	--i-problem	CLASSOProblem	required	Predict and Summarize
taxa	--i-taxa	FeatureData[Taxonomy]	None	Predict and Summarize	Used to label coefficients taxonomically.
predictions	--i-predictions	CLASSOProblem	None	Predict and Summarize	Output of predict. Omit it and the prediction panes are absent.
maxplot	--p-maxplot	Int	200	Predict and Summarize	Maximum number of coefficients drawn in a StabSel profile or beta bar plot. Raise it on wide problems or the plot silently truncates.

String parameters have no validation

q2_classo/plugin_setup.py imports Choices but never applies it. QIIME 2 therefore accepts any string for the parameters below, and the check — if there is one — happens inside the function:

Flag	Accepted values	Behaviour on a typo
--p-transformation	clr only	ValueError: Unknown transformation name, use clr and not '...'
--p-path-numerical-method	Path-Alg, P-PDS, PF-PDS, DR	Silently accepted — the default is itself the unrecognised literal not specified, which means “choose automatically”
--p-cv-numerical-method	same set	Silently accepted
--p-stabsel-numerical-method	same set	Silently accepted
--p-lamfixed-numerical-method	same set	Silently accepted
--p-stabsel-method	first, lam, max	Reaches c-lasso; behaviour depends on the solver

The *_numerical_method family is the dangerous one. Because the sentinel default is not a valid method name, there is no way for the code to distinguish “user asked for automatic selection” from “user misspelled Path-Alg” — both are strings outside the recognised set, and both fall through to automatic selection. You will get an answer, and it will not be the method you asked for.

See also

• q2-gglasso Parameter Reference

• Troubleshooting & Known Failure Modes

• Command Coverage Matrix