Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Statscraft 0.7.0, release v0.7.0

Command line help

The output of statscraft --help and of --help on every subcommand. The command line explains them with examples.

Statistics workbench

Usage: statscraft <COMMAND>

Commands:
  describe  Show the dictionary and basic counts of a data file or of a session
  run       Run syntax. With --session the dataset, settings and macros are kept between runs
  check     Validate syntax against the session's dataset without saving or writing anything
  help      Show the syntax of a command, or list all commands
  plan      Lower bounded syntax to an OpenStatSpec transformation plan (JSON)
  db        Store datasets in an OpenStatSpec SQLite database and read them back
  update    Update this installation to the latest published release

Options:
  -h, --help     Print help
  -V, --version  Print version

statscraft describe

Show the dictionary and basic counts of a data file or of a session

Usage: statscraft describe [OPTIONS] [FILE]

Arguments:
  [FILE]  A .sav or .zsav file

Options:
  -s, --session <SESSION>  Describe this session (dataset, settings, macros) instead of a file; gui is the window
      --json               Print the result as JSON
  -h, --help               Print help

statscraft run

Run syntax. With --session the dataset, settings and macros are kept between runs

Usage: statscraft run [OPTIONS] [FILE]

Arguments:
  [FILE]  Syntax file, or - for standard input

Options:
  -e, --execute <TEXT>      Syntax text given directly
  -s, --session <SESSION>   Session name: the dataset, settings and macros are loaded from and saved to .statscraft/sessions/<name>. The name gui sends the syntax to the running statscraft-gui window instead
      --lines <FIRST-LAST>  Run only the commands inside this inclusive line range, for example 40-55
      --json                Print tables, changes, warnings and errors as JSON
      --encoding <NAME>     Encoding of the syntax file, such as windows-1257 or 1252. Default: UTF-8 when the file is valid UTF-8 (with or without a byte order mark), else the system's legacy code page
      --xlsx <FILE>         Also write every table of the run to this Excel workbook, one sheet per table
      --xlsx-one-sheet      With --xlsx, put all tables on one sheet, one below the other
  -h, --help                Print help

statscraft check

Validate syntax against the session's dataset without saving or writing anything

Usage: statscraft check [OPTIONS] [FILE]

Arguments:
  [FILE]  Syntax file, or - for standard input

Options:
  -e, --execute <TEXT>      Syntax text given directly
  -s, --session <SESSION>   Session name: the dataset, settings and macros are loaded from and saved to .statscraft/sessions/<name>. The name gui sends the syntax to the running statscraft-gui window instead
      --lines <FIRST-LAST>  Run only the commands inside this inclusive line range, for example 40-55
      --json                Print tables, changes, warnings and errors as JSON
      --encoding <NAME>     Encoding of the syntax file, such as windows-1257 or 1252. Default: UTF-8 when the file is valid UTF-8 (with or without a byte order mark), else the system's legacy code page
  -h, --help                Print help

statscraft plan

Lower bounded syntax to an OpenStatSpec transformation plan (JSON)

Usage: statscraft plan [OPTIONS] [FILE]

Arguments:
  [FILE]  Syntax file, or - for standard input

Options:
  -e, --execute <TEXT>            Syntax text given directly
      --input-schema <FILE>       Input schema: a JSON file with {"variables": [{"name", "storage_kind", ...}]}
  -s, --session <SESSION>         Take the input schema from the dataset of this session
      --sqlite <DB>               OpenStatSpec SQLite database file
      --postgres <URL>            PostgreSQL: postgres://user@host:port/database[?schema=NAME], schema default openstatspec; TLS with &sslmode=verify-full|verify-ca|require and &sslrootcert=CA.pem
      --mysql <URL>               MySQL or MariaDB: mysql://user@host:port/database, a database dedicated to the catalog; TLS with ?ssl-mode=VERIFY_IDENTITY|VERIFY_CA|REQUIRED and &ssl-ca=CA.pem
      --dolt <URL>                Dolt sql-server: mysql://user@host:port/database, a database dedicated to the catalog; TLS as for --mysql
      --name <DATASET>            Dataset name in the database
      --apply                     Apply the plan to the dataset in place
      --expected-branch <BRANCH>  Dolt: the branch the apply must run on
      --expected-head <COMMIT>    Dolt: the commit HEAD must be at
      --actor <ACTOR>             Who applies the plan, for the audit row; defaults to $USER
      --profile <PROFILE>         Frontend profile version [default: 0.3] [possible values: 0.1, 0.2, 0.3]
      --alias <ALIAS>             Symbolic name of the input dataset in the plan [default: input]
  -h, --help                      Print help

Prints one line of canonical JSON: {"ok":true,"plan":...,"plan_hash":...,"source_hash":...}, or {"ok":false,"error":{"code":...,"message":...,"line":...,"column":...},...}. The plan hash is SHA-256 of the canonical plan; the source hash is SHA-256 of the source with line ends converted to LF.

Profile 0.1: RECODE, VARIABLE LABELS, VALUE LABELS.
Profile 0.2 adds COMPUTE target = operand, IF (predicate) target = operand, FORMATS (F only), VARIABLE LEVEL and EXECUTE.
Profile 0.3 adds comments, TO lists, NE <> ~= and NOT, LOWEST/HIGHEST ranges and ADD VALUE LABELS.
Anything else is rejected: this is OpenStatSpec's bounded frontend, not the full language of `statscraft run`.

With --sqlite DB, --postgres URL, --mysql URL or --dolt URL and --name DATASET the input schema comes from that OpenStatSpec dataset, and --apply applies the plan to it in place, in one transaction with one audit row; the output then has "applied":{"apply_id":...,"dataset_id":...,"operation_count":...}. On Dolt, --apply needs --expected-branch and --expected-head: the session must be on that branch at that commit with a clean working set, and the changes stay uncommitted.

statscraft db

Store datasets in an OpenStatSpec SQLite database and read them back

Usage: statscraft db <COMMAND>

Commands:
  export        Store a .sav/.zsav file, or the dataset of a session, as a dataset in the database
  import        Read a dataset from the database into a .sav/.zsav file or a session
  capabilities  Print the adapter's capability declaration: versions, limits and atomicity per profile

Options:
  -h, --help  Print help

Prints one line of canonical JSON: {"ok":true,...} or {"ok":false,"error":{"code":...,"message":...}}.

The database is dedicated to OpenStatSpec: a SQLite file, a PostgreSQL schema, or a MySQL, MariaDB or Dolt database. On Dolt, `db export` leaves its changes in the working set and never commits, and `db import` writes nothing at all. Export creates the catalog in a new or empty one and refuses one holding anything else. Each dataset is one table data_<name> with __case_ordinal and one column per variable; the dictionary lives in the catalog tables. A URL without a password takes it from the STATSCRAFT_DB_PASSWORD environment variable; passwords are never printed. Connections are plain TCP unless the URL asks for TLS; TLS always verifies the server certificate against the CA file or the bundled Mozilla roots, and the host name unless the mode is verify-ca.

statscraft db export

Store a .sav/.zsav file, or the dataset of a session, as a dataset in the database

Usage: statscraft db export [OPTIONS] [FILE]

Arguments:
  [FILE]  A .sav or .zsav file

Options:
  -s, --session <SESSION>  Export the dataset of this session instead of a file
      --sqlite <DB>        OpenStatSpec SQLite database file
      --postgres <URL>     PostgreSQL: postgres://user@host:port/database[?schema=NAME], schema default openstatspec; TLS with &sslmode=verify-full|verify-ca|require and &sslrootcert=CA.pem
      --mysql <URL>        MySQL or MariaDB: mysql://user@host:port/database, a database dedicated to the catalog; TLS with ?ssl-mode=VERIFY_IDENTITY|VERIFY_CA|REQUIRED and &ssl-ca=CA.pem
      --dolt <URL>         Dolt sql-server: mysql://user@host:port/database, a database dedicated to the catalog; TLS as for --mysql
      --name <NAME>        Dataset name: ASCII letters, digits and _; defaults to the file or session name
  -h, --help               Print help

statscraft db import

Read a dataset from the database into a .sav/.zsav file or a session

Usage: statscraft db import [OPTIONS] --name <NAME>

Options:
      --sqlite <DB>        OpenStatSpec SQLite database file
      --postgres <URL>     PostgreSQL: postgres://user@host:port/database[?schema=NAME], schema default openstatspec; TLS with &sslmode=verify-full|verify-ca|require and &sslrootcert=CA.pem
      --mysql <URL>        MySQL or MariaDB: mysql://user@host:port/database, a database dedicated to the catalog; TLS with ?ssl-mode=VERIFY_IDENTITY|VERIFY_CA|REQUIRED and &ssl-ca=CA.pem
      --dolt <URL>         Dolt sql-server: mysql://user@host:port/database, a database dedicated to the catalog; TLS as for --mysql
      --name <NAME>        Dataset name
      --out <FILE>         Write this .sav or .zsav file
  -s, --session <SESSION>  Make the dataset the one of this session instead
      --allow-loss         Go on when the catalog holds items the dataset cannot keep, and record each loss
  -h, --help               Print help

statscraft db capabilities

Print the adapter's capability declaration: versions, limits and atomicity per profile

Usage: statscraft db capabilities

Options:
  -h, --help  Print help

statscraft update

Update this installation to the latest published release

Usage: statscraft update [OPTIONS]

Options:
      --check  Only check: exit code 0 when up to date, 10 when a newer release exists
      --json   With --check, print the result as JSON
  -h, --help   Print help