CLI Reference

The metasignal command-line tool gives access to the pure-Python backend without writing any Python code. The optional bayes sub-group requires the sdtbayes extra:

pip install "metasignal[sdtbayes] @ git+https://github.com/saurabhr/metasignal.git"  # from GitHub
pip install ".[sdtbayes]"       # from a local clone

Commands

metasignal

Signal Detection Theory and metacognitive measures (pure Python).

Usage:

metasignal [OPTIONS] COMMAND [ARGS]...

Options:

  -v, --version  Show the version and exit.
  -h, --help     Show this message and exit.

bayes

Bayesian hierarchical meta-d' models (requires metasignal[sdtbayes]).

Usage:

metasignal bayes [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

compare

Two-stage Bayesian comparison of M-ratio between two groups.

The CSV must have a group column with exactly two unique values. Groups are sorted alphabetically — the first is group A, the second is group B. Key parameter in the output:

b_group1 — posterior difference in log M-ratio (group B − group A) exp(b_group1) > 1 means group B has higher M-ratio

CSV must have one trial per row with columns for group, participant ID, stimulus (0/1), response (0/1), and confidence rating.

Usage:

metasignal bayes compare [OPTIONS]

Options:

  --csv FILE              Long-format CSV with one trial per row and a group
                          column.  [required]
  --n-ratings INTEGER     Number of confidence rating categories.  [required]
  --group-col TEXT        Column name for group labels (must have exactly 2
                          unique values).  [default: group]
  --participant-col TEXT  Column name for participant IDs.  [default:
                          participant]
  --stim-col TEXT         Column name for stimulus values (0/1).  [default:
                          stim]
  --resp-col TEXT         Column name for response values (0/1).  [default:
                          resp]
  --conf-col TEXT         Column name for confidence ratings.  [default: conf]
  --chains INTEGER        Number of MCMC chains.  [default: 4]
  --iter INTEGER          Total iterations per chain (including warmup).
                          [default: 2000]
  --seed INTEGER          Random seed.  [default: 42]
  --var-names TEXT        Comma-separated parameter names to show (default:
                          all).
  -h, --help              Show this message and exit.

two-stage

Two-stage Bayesian group-level M-ratio from a CSV of trial data.

Stage 1 fits per-participant MLE meta-d'. Stage 2 fits a Bayesian hierarchical model over log M-ratio. Key parameters in the output:

b_Intercept — group mean log M-ratio (exp → M-ratio) sigma — between-subject SD on the log scale

CSV must have one trial per row with columns for participant ID, stimulus (0/1), response (0/1), and confidence rating.

Usage:

metasignal bayes two-stage [OPTIONS]

Options:

  --csv FILE              Long-format CSV with one trial per row.  [required]
  --n-ratings INTEGER     Number of confidence rating categories.  [required]
  --participant-col TEXT  Column name for participant IDs.  [default:
                          participant]
  --stim-col TEXT         Column name for stimulus values (0/1).  [default:
                          stim]
  --resp-col TEXT         Column name for response values (0/1).  [default:
                          resp]
  --conf-col TEXT         Column name for confidence ratings.  [default: conf]
  --chains INTEGER        Number of MCMC chains.  [default: 4]
  --iter INTEGER          Total iterations per chain (including warmup).
                          [default: 2000]
  --seed INTEGER          Random seed.  [default: 42]
  --var-names TEXT        Comma-separated parameter names to show (default:
                          all).
  -h, --help              Show this message and exit.

compute

Compute all 26 SDT and metacognitive measures from trial-level data.

Trial data can be given inline (--stim/--resp/--conf) or from a CSV with one trial per row (--csv), but not both.

Usage:

metasignal compute [OPTIONS]

Options:

  --stim TEXT          Comma-separated stimulus values (0/1).
  --resp TEXT          Comma-separated response values (0/1).
  --conf TEXT          Comma-separated confidence ratings (1 to n-ratings).
  --csv FILE           CSV with one trial per row, as an alternative to
                       --stim/--resp/--conf.
  --stim-col TEXT      Stimulus column name (CSV mode).  [default: stim]
  --resp-col TEXT      Response column name (CSV mode).  [default: resp]
  --conf-col TEXT      Confidence column name (CSV mode).  [default: conf]
  --n-ratings INTEGER  Number of confidence rating categories.  [required]
  -h, --help           Show this message and exit.

`compute` — all 26 measures

Compute all 26 SDT and metacognitive measures from a single participant's trial-level data.

metasignal compute \
  --stim  "0,1,0,1,1,0,1,0,0,1" \
  --resp  "0,1,1,1,1,0,0,0,0,1" \
  --conf  "2,3,1,4,4,3,2,1,3,4" \
  --n-ratings 4

Output:

Measure                   Value
--------------------------------
meta_d                   1.6571
AUC2                     0.8750
gamma                    0.8571
phi                      0.5455
deltaConf                1.5000
M_ratio                  1.2284
AUC2_ratio               1.2755
gamma_ratio              1.7820
phi_ratio                1.8885
deltaConf_ratio          2.0248
M_diff                   0.3082
AUC2_diff                0.1890
gamma_diff               0.3761
phi_diff                 0.2566
deltaConf_diff           0.7592
metaNoise                0.1115
metaUncertainty          0.0100
dprime                   1.6832
c                       -0.0000
mean_conf                2.7000
logL                   -13.0667
AIC                     40.1334
BIC                     43.5278
AICc                    68.1334
k                        7.0000
n                       12.0000

Input format

Option	Format	Example
`--stim`	Comma-separated 0/1 integers	`"0,1,0,1"`
`--resp`	Comma-separated 0/1 integers	`"0,1,1,0"`
`--conf`	Comma-separated integers (1 to n-ratings)	`"1,3,2,4"`
`--n-ratings`	Integer — number of confidence categories	`4`

--n-ratings is always required. Provide either all three of --stim/--resp/--conf, or --csv — not both. Arrays (or CSV columns) must be the same length.

Reading trial data from a CSV

As an alternative to typing values inline, --csv reads one trial per row:

metasignal compute --csv trials.csv --n-ratings 4

Column names default to stim, resp, conf and can be overridden with --stim-col, --resp-col, --conf-col for CSVs with different headers.

`bayes` — Bayesian hierarchical meta-d'

Requires pip install "metasignal[sdtbayes] @ git+https://github.com/saurabhr/metasignal.git" and a one-time Stan runtime setup (see SDT Bayes for installation instructions).

Both sub-commands take a long-format CSV — one trial per row — with columns for participant ID, stimulus, response, and confidence rating.

CSV format

participant,stim,resp,conf
P001,0,0,2
P001,1,1,4
P001,0,1,1
...
P002,0,0,3
P002,1,1,4
...

Column names default to participant, stim, resp, conf and can be overridden with --participant-col, --stim-col, --resp-col, --conf-col.

`bayes two-stage` — group-level M-ratio

Fits a two-stage Bayesian model: MLE per participant (Stage 1) then a hierarchical Bayesian model over log M-ratio (Stage 2).

metasignal bayes two-stage \
  --csv participants.csv \
  --n-ratings 4

Key output parameters:

Parameter	Interpretation
`b_Intercept`	Group mean log M-ratio; `exp(b_Intercept)` gives the M-ratio
`sigma`	Between-subject SD on the log scale

Use --var-names "b_Intercept,sigma" to restrict the summary to these two parameters.

`bayes compare` — two-group M-ratio comparison

Adds a group column to the CSV (exactly two unique values). Groups are sorted alphabetically — the first becomes group A, the second group B.

participant,group,stim,resp,conf
P001,control,0,0,2
P001,control,1,1,4
...
P020,patient,0,1,1
...

metasignal bayes compare \
  --csv study.csv \
  --n-ratings 4 \
  --group-col group

Key output parameter:

Parameter	Interpretation
`b_group1`	Posterior difference in log M-ratio (group B − group A). `exp(b_group1) > 1` means group B has higher metacognitive efficiency.

To compute the posterior probability that group B has lower M-ratio than group A, extract the posterior in Python:

import arviz as az
post = az.extract(fit.idata)["b_group1"].values
print(f"P(B < A): {(post < 0).mean():.3f}")

CLI Reference

Commands

metasignal

bayes

compare

two-stage

compute

compute — all 26 measures

Input format

Reading trial data from a CSV

bayes — Bayesian hierarchical meta-d'

CSV format

bayes two-stage — group-level M-ratio

bayes compare — two-group M-ratio comparison

`compute` — all 26 measures

`bayes` — Bayesian hierarchical meta-d'

`bayes two-stage` — group-level M-ratio

`bayes compare` — two-group M-ratio comparison