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

The window

statscraft-gui survey.sav job.sps     open a data file and a syntax file

statscraft-gui is a desktop window over the same engine, in four tabs. Files dropped on the window from the file manager open too: a .sav or .zsav file as data, a workbook or text file (.xlsx, .xlsm, .xls, .csv, .txt, .tab, .dat) in the Open Data dialog, a .sps file in the syntax editor (one data file and one syntax file at a time; the status bar names the files left out). On macOS a .sav, .zsav or .sps file opened from Finder (a double-click or Open With) is meant to open the same way; this is not yet tested on a Mac.

  • Data: the cases in a grid that draws only the visible cells, with value labels on or off (Show value labels, over the grid). Each column draws its values and labels with the variable’s alignment (numbers to the right and strings to the left when the file sets none); a value or label too wide for its column is cut short with an ellipsis and keeps that alignment. A system-missing value shows as a small grey dot, an empty string as nothing. While FILTER BY is in force, the row number of every case the filter leaves out has a diagonal stroke through it; the case stays in the grid. Double-click a cell or press Enter to change it; Enter commits, Escape cancels. Arrows, Page Up and Down, Home and End move the selection, Ctrl with an arrow goes to the first or last row or column, Ctrl+Home and Ctrl+End to the first and last cell, and Tab and Shift+Tab move to the next and previous cell, committing an edit on the way. Shift with those keys, or Shift+click, extends the selection to a block; a click on a row number or a column name selects the whole case or variable (Shift+click a range, Ctrl+click one more or one less). Dragging across cells selects the block, across column names or row numbers the variables or cases in between. Ctrl+C copies the selection as tab-separated text with the variable names as the first line, for a spreadsheet or a text editor; one cell copies as its text alone, and more than two million cells are not copied. Delete asks to delete the variables whose columns are selected; with cells selected it clears them (IF (RANGE($CASENUM, 2, 4)) age = $SYSMIS., a blank for a string), and Ctrl+Z brings them back. A column is as wide as the variable’s display width (the width a .sav file keeps for each variable); drag the border at the right of its name to change it, which runs VARIABLE WIDTH var (n)., so the width is saved with the data.
  • Variables: one row per variable with name, type, format, width, decimals, label, value labels, missing values, columns (the display width, as wide as the Data View shows it), alignment, measure and role. Double-click to change a field. The type (Numeric, Date or String) and the format open a small dialog that offers only formats there are, numbers (plain, comma, dot, dollar, percent, scientific, leading zeros), dates and times, and strings, with the width and decimals as numbers within that format’s limits; it runs FORMATS, or ALTER TYPE for a new type or string width (a new type drops value labels and missing values, and the dialog says so). Value labels open an editor with one row per code and label to change, add and remove, which runs VALUE LABELS with the whole set; or Paste many, a text area for many lines of a code and a label with a tab, semicolon, equals sign or comma between (the first of these the text holds), which either updates (ADD VALUE LABELS: new codes added, the labels of codes there are changed) or replaces the whole set (VALUE LABELS). Missing values open an editor for up to three values, or for numbers a range (LO and HI for the lowest and highest value) and one value more, which runs MISSING VALUES. When the variable’s row is one of several selected rows, both editors can give the same labels or missing values to the other selected variables of its type. Columns runs VARIABLE WIDTH, alignment VARIABLE ALIGNMENT and role VARIABLE ROLE, chosen from a list like the measure. A variable without an alignment or role in the file shows numbers to the right, strings to the left and the role Input. The keys, mouse selection and Ctrl+C work as in the Data View, Enter changes the cell at the cursor; Delete deletes the variables whose row numbers are selected, with DELETE VARIABLES, after a question (Edit, Undo last change brings them back). Drag a column border to resize it; these widths are a window setting.

Ctrl+F in the Data View or the Variable View opens a find bar: typing goes to the first variable whose name or label holds the text (any case), Enter or F3 to the next one, Escape closes the bar. The Variable View goes to the variable’s row, the Data View to its column.

A right click opens a menu over what it lands on. On a column name (or the selected columns, when it lands inside them) the menu is short: it sorts the cases ascending or descending by them (SORT CASES), runs Frequencies or Descriptives (numeric variables only) at once, renames the variable, inserts a numeric variable new_1 before it (NUMERIC and MATCH FILES /KEEP, with WEIGHT BY again when a weight is on), copies, or deletes. On a cell it copies, edits or clears the value, keeps only the cases with the same value with a filter (COMPUTE filter_$ = (age = 49)., VARIABLE LABELS and FILTER BY, on the stored value rather than the rounded one shown, VALUE(x) = 99 for a user-missing value, SYSMIS(x) for an empty cell; a variable filter_$ of other data is never overwritten, the next free filter_$_2 is used), stops filtering, opens Select Cases to delete the other cases, or sorts by the variable. On a row number it copies or deletes the case (COMPUTE #row = #row + 1. and SELECT IF #row <> 12.). In the Variable View the menu on row numbers is the one of the columns, and on a cell it starts with Edit for that field. The top of a menu names what it acts on. Items that run syntax wait while a run is going on, and the analyses and sorting are off without cases. Every item runs syntax like any other run, so it shows in the log and Ctrl+Z takes a change back. Deleting variables or a case, sorting while a split is on (sorting ends the split) and Frequencies of more than 100 variables first show the question and the syntax; only a click on the button runs it, Escape cancels.

  • Syntax: an editor with line numbers and colours for command names, subcommands, keywords, strings, numbers, comments, macro words (!name and the words of the macro language) and the period that ends a command. A macro defined with DEFINE in the editor text or in an earlier run of the session is coloured as a macro where it is called, also where a command would stand. Run all, or Run selection (Ctrl+Enter) for the commands on the selected lines; on a line with no command (the empty line under a command just typed) it runs the command above. Errors show at their line and column. While typing, a list offers what fits at the cursor: command names at the start of a command (abbreviations such as FRE or VAL LAB find the full name), subcommands after /, keywords of the command, the variables of the open data with their labels, function names where an expression goes, the macros defined with DEFINE in the text or the session (where a command goes and inside commands), and after ! the words of the macro language. Ctrl+Space opens the list at any point; arrows choose, Enter or Tab puts the choice in, Escape closes it. A command in the list, or a command name under the mouse, shows its summary and syntax; F1 opens the full help of the command at the cursor in a small window.
  • Output: every result table with its multi-level header, beside a navigator that groups the tables by run and command (a run folds away with a click on it). Columns are as wide as their numbers, which align right; long row labels and column headers wrap between words, and a row label repeated under the same outer labels is shown once beside all its rows. The caption and notes follow each table. A run selects nothing, so its tables show without a frame; click a table, or its name in the navigator, to select it (Ctrl+click for more, Ctrl+A for all), and click it again, press Escape or click beside the tables to clear the selection; the syntax of its command shows under the navigator, exactly as it ran, with Copy, Paste (into the syntax editor) and Run again, and pointing at a command in the navigator shows it too; then Copy (Ctrl+C) puts it on the clipboard with its layout for a word processor or spreadsheet and as plain text beside it, Copy as text gives tab-separated text, Delete removes it, and Export selection saves only the selected tables as a web page or an Excel workbook. Right-click a table for the same. Each table is measured once and only the tables in view are drawn, so hundreds of tables scroll smoothly.

File, Open data opens a .sav or .zsav file at once. An Excel workbook (.xlsx, .xlsm, .xls) or a text file (.csv, .txt, .tab, .dat) opens the Open Data dialog first, which writes GET DATA: for a workbook the sheet, whether the first row holds the variable names, and a range such as A1:F200 (empty reads the whole sheet); for a text file the delimiter (comma, semicolon or tab, the one the first line uses most is chosen), whether the first line holds the names, with that line shown, and every variable read as AUTO. After it runs, File, Save data asks for a new .sav file. File, Export data writes SAVE TRANSLATE to an Excel workbook (.xlsx), a CSV file (.csv) or tab-delimited text (.txt), by the name chosen: a first row of variable names, variable labels or none, value labels instead of values, user-missing values as empty, and the variables to export (none: all, in the order of the dataset). An existing file is replaced once the file dialog has asked.

File, Export output as HTML saves the whole output as one web page; File, Export output as Excel saves it as a workbook, with One sheet per table or All tables on one sheet, laid out as --xlsx does. From syntax, OUTPUT EXPORT writes the tables of an output document to a workbook, web page, text or CSV file; OUTPUT NEW, NAME, ACTIVATE and CLOSE group the tables into documents, which the Output view shows together, and the window keeps them from run to run.

The menus have dialogs that build syntax:

  • Data: Define Multiple Response Sets (dichotomy or category sets, counted value, labels, deleting sets), Sort Cases, Split File (groups compared in the same tables or in tables of their own, sorting the cases first, or off), Select Cases (a filter that leaves the other cases out of analyses: COMPUTE filter_$ = (condition). and FILTER BY filter_$.; SELECT IF, which deletes them; or all cases again with FILTER OFF. and USE ALL.), Weight Cases, Aggregate (into every case, a new dataset of one case per group, or a file), Merge Files with Add Cases and Add Variables (with keys, or a lookup table), Sort Variables (SORT VARIABLES by name, type, format, label, value labels, missing values, measure, role, columns or alignment, ascending or descending) and Restructure: variables to cases (VARSTOCASES with one or more new variables each made from a list of variables, an index variable, a case number variable and the variables to copy), cases to variables (CASESTOVARS with identifier and index variables, the new variables in order of the variable or of the index, sorting the cases first) or transposing cases and variables (FLIP of chosen or all variables, the new variables named by the values of a variable).
  • Analyze: Descriptive Statistics (Frequencies with statistics, the order of the rows, a limit on the values of a table, quartiles, cut points for equal groups and any percentiles, Descriptives, Explore with descriptives, M-estimators, extreme values, percentiles and tests of normality by factor, and Crosstabs), Custom Tables (rows, columns and layers of variables and multiple response sets, means, percentages, totals, significance tests with their letters in a separate table or in the main table, hiding small counts, an effective base weight with the effective count, and per variable the order of the categories, sorted by value, label, count or a mean, the total with its label and position, subtotals over chosen categories that can hide them, and missing and other categories), Compare Means (Means with every cell statistic including the grouped median and percentages within a control variable, the one-sample, independent-samples and paired-samples t tests, One-Way ANOVA with every post hoc test the engine has, Dunnett’s against the first or last group on either side), General Linear Model, Univariate (UNIANOVA of one dependent variable by fixed factors with covariates: the full factorial model or a custom one of main effects and interactions picked from the factors and covariates, the type of sums of squares and the intercept; post hoc tests of chosen factors, the same tests as One-Way ANOVA; estimated marginal means overall and for each chosen factor, with main effects compared unadjusted or by Bonferroni or Sidak; saving predicted values, their standard errors, residuals, Cook’s distance and leverage; descriptive statistics, effect sizes, observed power, parameter estimates, homogeneity tests and the significance level), General Linear Model, Repeated Measures (GLM with WSFACTOR: within-subjects factors each with a name and its number of levels, one variable for each combination of levels, between-subjects factors and covariates, the type of sums of squares, descriptive statistics, effect sizes, observed power and the significance level; one measure only, since MEASURE is not supported yet), Correlate, Bivariate (Pearson by CORRELATIONS, Spearman and Kendall by NONPAR CORR, both commands when both kinds are chosen), Correlate, Partial (PARTIAL CORR of the variables controlling for others, a one- or two-tailed test, the coefficients alone marked with stars, means and standard deviations, the zero-order correlations, and cases left out of every correlation or only where they are missing), Regression, Linear (REGRESSION of one dependent variable on blocks of independent variables, each block with its method: Enter, Stepwise, Remove, Backward or Forward; estimates, confidence intervals at any level, model fit, R squared change, descriptives, part and partial correlations and collinearity diagnostics; saving predicted values, residuals, distances and influence statistics; the stepping criteria as probabilities or values of F, the constant, and listwise, pairwise or mean substitution of missing values), Regression, Binary Logistic (LOGISTIC REGRESSION of one dependent variable with two values on blocks of covariates, each block entered or stepped forward or backward by the conditional, likelihood-ratio or Wald statistic; categorical covariates each with its contrast and the first or last category as reference; saving predicted probabilities, group membership, residuals and influence statistics; the Hosmer-Lemeshow test, confidence intervals for exp(B), the iteration history, the classification cutoff, the stepwise entry and removal probabilities, the maximum iterations and the constant), Classify, K-Means Cluster (QUICK CLUSTER into a number of clusters by iterating and classifying or by classifying only, with the maximum iterations and the convergence criterion; saving the cluster membership and the distance from the cluster center; the initial centers, the ANOVA table and the cluster of each case labelled by a variable; and cases left out listwise or pairwise), Classify, Hierarchical Cluster (CLUSTER of the cases by the variables, labelled by a variable: between-groups or within-groups linkage, nearest or furthest neighbor, centroid or median clustering or Ward’s method; the measure for interval data (squared Euclidean, Euclidean, cosine, Pearson correlation, Chebychev, block, Minkowski with its power, or customized with a power and a root), for counts (chi-squared or phi-squared) or for binary data (squared Euclidean, Euclidean, simple matching, Jaccard, Dice, Russell and Rao, Rogers and Tanimoto, Hamann, Ochiai, phi 4-point correlation or Yule’s Q, with the values of presence and absence; the other binary measures are in the syntax); the agglomeration schedule, the proximity matrix and the cluster membership of one solution or a range of them; and saving the membership of one solution or a range), Classify, Discriminant (DISCRIMINANT of a grouping variable with its range of values by independents entered together or stepwise by Wilks’ lambda, the Mahalanobis distance, the smallest F ratio, the unexplained variance or Rao’s V, with values of F or their probabilities to enter and remove; means, univariate ANOVAs, Box’s M, Fisher’s and unstandardized function coefficients, the within-groups correlation and covariance and the separate-groups and total covariance matrices; prior probabilities equal or from the group sizes, classification by the within-groups or separate-groups covariance, the summary table and leave-one-out classification; saving the predicted group, the discriminant scores and the probabilities of group membership; and a selection variable with its value), Classify, Tree (TREE by CHAID or exhaustive CHAID: a nominal or ordinal dependent, predictors each with its own level or the measure of the dictionary, the maximum depth and the fewest cases in a parent and a child node, target categories for the gain tables, and saving the terminal node, the predicted category and the predicted probabilities), Dimension Reduction, Factor (FACTOR: univariate descriptives, the initial solution, the correlation coefficients with their significance, the determinant, KMO and Bartlett’s test, the inverse, reproduced and anti-image matrices; extraction by principal components, unweighted or generalized least squares, maximum likelihood, principal axis, alpha or image factoring, of the factors with eigenvalues over a value or a fixed number of them, with the maximum iterations; rotation by varimax, direct oblimin with its delta, quartimax, equamax or promax with its kappa, or none; factor scores saved by the regression, Bartlett or Anderson-Rubin method and the score coefficient matrix; listwise, pairwise or mean substitution of missing values, and loadings sorted by size with small ones left blank), Scale, Reliability Analysis (RELIABILITY of one scale of all the items: the Alpha, Split-half, Guttman, Parallel or Strict parallel model, a scale label, descriptives for each item, the scale and the scale if an item is deleted, inter-item correlations and covariances, their summaries, an ANOVA table with the F test, Friedman’s or Cochran’s chi-square, Hotelling’s T-squared, Tukey’s test of additivity, and the intraclass correlation with its model, type, confidence level and test value), Nonparametric Tests (NPAR TESTS from the dialogs analysts know: Chi-square with the categories from the data or a range and equal or given expected values, Binomial with a test proportion and the two values of the data or a cut point, Runs at the median, mode, mean or a custom cut point, 1-Sample K-S against the normal, uniform, Poisson or exponential distribution, 2 Independent Samples with Mann-Whitney, Kolmogorov-Smirnov, Moses and Wald-Wolfowitz, K Independent Samples with Kruskal-Wallis, the median test and Jonckheere-Terpstra, 2 Related Samples with Wilcoxon, sign, McNemar and marginal homogeneity on pairs, and K Related Samples with Friedman, Kendall’s W and Cochran’s Q; each with descriptives, quartiles and cases left out test by test or listwise) and Multiple Response, Frequencies and Crosstabs (MULT RESPONSE: groups defined in the dialog as dichotomies with a counted value or categories with a range, kept from one of the two dialogs to the other while the window is open; frequency tables of every group; crosstabulations of groups and variables in rows, columns and layers, each variable with its range, starting from its lowest and highest labelled value, with row, column and total percentages based on cases or responses; and leaving out cases missing on any variable of a dichotomy or category group).
  • Transform: Compute, Recode, Count Values within Cases, Rank Cases (every RANK function with new names or the default ones, ranks within groups, from the smallest or the largest value, ties, the proportion formula, user-missing values) and Automatic Recode (AUTORECODE into new variables, from the largest value, one scheme for all, blank strings as missing, a table of the values).

Every dialog that builds syntax, the menus’ dialogs and the Variable View’s editors of the type and format, value labels and missing values alike, ends the same way: the syntax it builds (or why it has none yet), then OK, which runs it, Paste, which puts it in the syntax editor, and Cancel; the menus’ dialogs also have Reset. OK and Paste stay off until the syntax is complete, and Escape cancels. Options left at their defaults add nothing to the syntax. Warnings of a run appear under its command in the log, and the status bar says how many there were; a click there shows the log (from the Data or Variable View, in the Syntax view). Errors show in the status bar, whatever the view. At its right the status bar names the split, filter and weight in force, such as Split by region (layered), Filter: filter_$ and Weight: weight; a click on one opens Split File, Select Cases or Weight Cases.

Syntax is the only command layer: every change and every result in the window comes from syntax run by the engine, exactly as statscraft run runs it. Opening a file runs GET FILE, editing a cell runs IF ($CASENUM = n) var = value., editing a label runs VARIABLE LABELS, and so on. The log under the Syntax and Output views (Edit, Settings, Grids and output turns it off; the Data and Variable Views give the grid the whole height) lists every command with what it changed, and Copy syntax there gives a script that repeats the session. Macros defined by one Run (DEFINE, or INCLUDE of a macro library) stay defined for the later ones while the window is open, with the macro settings of SET.

Edit, Settings holds every setting of the window in one dialog, with its sections in a list on the left. A change applies at once and is saved; Close or Escape closes the dialog. Grids and output also chooses how tables show variables (labels, names, or names and labels) and values (labels, values, or values and labels): these belong to the session, not the window, so a choice runs SET TVARS or SET TNUMBERS like any other command, shows in the log and stays for the later runs; a SET in syntax changes the dialog too. The window also keeps the choice (the lines tvars names and tnumbers both in window.txt) and runs the same SET when it starts, so it is set once.

  • Editor: Syntax colours, the colours and background of the syntax editor, from Statscraft Light (the default) and Dark, in the Statscraft colours, and ready-made editor themes: Catppuccin Latte and Mocha, One Dark, Solarized Light and Dark, GitHub Light and Dark. Wrap long lines (on by default) wraps them at the window edge.
  • Grids and output: the paper of the Data and Variable grids and the output tables. Always light (the default) keeps them dark text on a light sheet while menus, panels and dialogs follow the system’s dark or light theme, as a spreadsheet or a document page does; Follow the system theme draws them in the system theme too. Log under Syntax and Output (on by default); a run with warnings shows the log even when it is off.
  • Updates: Check for updates automatically (see Updates below).

Help, Documentation opens these pages online; Help, About shows the version, the license (MIT), links to the source code and the documentation, where the colour themes come from with their licenses, and the licenses of the fonts.

The window remembers its size and position, the folder of the last file dialog, the ten files opened or saved last (File, Recent files), the settings of Edit, Settings and the Variable View’s column widths in statscraft/window.txt in the user’s config folder: %APPDATA% on Windows, $XDG_CONFIG_HOME or ~/.config elsewhere.

Edit, Undo last change (Ctrl+Z outside a text field) puts back the dataset from before the last run that changed it, one step; the log marks that run as undone and Copy syntax leaves it out.

Closing the window (the title bar, Alt+F4, File, Exit, the Windows installer of an update, or Restart now) first checks for unsaved work: data changed since it was last opened or saved, and syntax whose text differs from its file, or new syntax that is not empty. With nothing unsaved the window closes at once. Otherwise one question lists what is unsaved, with Save, Don’t save and Cancel. Save saves the syntax and the data, each to its file, or with a file dialog when there is none yet, and closes the window once both are written; a cancelled file dialog or a failed save keeps the window open. Cancel, Escape or a click beside the question keeps the window open. Data counts as saved after a run that ends with GET, GET DATA or SAVE, whether from a menu, the syntax editor or the command line. New syntax, Open syntax, a syntax file from Recent files or one dropped on the window ask the same question when the syntax in the editor is unsaved: Save saves it first, Don’t save drops it, Cancel keeps it.

Opening a file and every run happen off the drawing thread: the status bar shows what is running and the window stays responsive. One run goes at a time; requests from the command line wait their turn.

Updates

The window asks GitHub at most once a day, in the background and never holding up the start, whether a newer release is published. Checks are on by default and say nothing unless a newer version is out. Edit, Settings, Updates turns them on and off (the line updates on or updates off in window.txt), and Help, Check for updates checks at once and also says when there is nothing new.

When a newer release is out, a small bar under the menu says so, with a link to the release notes, Update now and Later. Later hides the bar until the next check. Update now downloads the package for this installation, checks it against the release’s SHA256SUMS and then:

  • installed with the Windows installer: closes the window, runs the new installer silently for the same per-user installation (same folder, file types and Start menu entry) and the installer opens the window again. Unsaved work is asked about first, as for any close.
  • installed from the tarball: replaces statscraft and statscraft-gui in its bin folder (each written next to the old one, then renamed over it) and offers Restart now, which closes the window (asking about unsaved work first) and then starts the new one; Cancel keeps this window and starts none.
  • unpacked from the portable Windows .zip (the folder with LICENSE.txt next to the programs): replaces statscraft.exe and statscraft-gui.exe in that folder the same way and offers Restart now. Windows cannot replace a running program, so the old one is renamed aside first and deleted the next time Statscraft starts.
  • Statscraft.app on macOS: there is no Update now but a Download link to the new macOS package; replace Statscraft.app with the one in it. The updater does not change files inside the app, which a signed app would not allow.
  • installed from the .deb: saves the package in ~/Downloads and shows the one command that installs it, sudo apt install ~/Downloads/statscraft_X_amd64.deb, with a button that copies it. The window never runs sudo.
  • built from source or copied elsewhere: there is no Update now; the bar says to install the new version the way this copy was installed.

The check is one request to the GitHub API with the User-Agent statscraft/VERSION; nothing about you or your data is sent. statscraft update does the same from the command line.

Driving the window from the command line or an AI agent

While the window is open it is a live session named gui:

statscraft run -s gui -e "GET FILE='survey.sav'."         the window opens the file
statscraft run -s gui --json job.sps                      runs job.sps in the window
statscraft check -s gui -e "COMPUTE x = age / 10."       validates against the window's data
statscraft describe -s gui --json                        dictionary of the window's dataset

The window runs the syntax exactly as its own Run button does: the tables appear in Output, the commands in the log, and the data grid shows the result. The command line prints what it prints for a file session, with "session": "gui"; saved is true when the run changed the window’s dataset (nothing is written to disk unless the syntax says SAVE). Relative paths in the syntax are read from the folder where statscraft was started, and the window stays in that folder.

So an AI agent with a shell can work in the open window: start statscraft-gui, then tell the agent to use statscraft run -s gui --json for every step and statscraft help COMMAND for the syntax. The person watching sees each table appear and can keep working in the window between the agent’s runs.

How it connects: on start the window listens on a random TCP port of 127.0.0.1 and writes the address and a random token to statscraft/gui.json in $XDG_RUNTIME_DIR on Linux or %LOCALAPPDATA% on Windows (~/.config otherwise), readable only by the user. A request without the token is refused, and the command line sends the token only to a local address. When no window is open, -s gui fails with “no Statscraft window is running”. With several windows open, the one started last answers.

The window brings its own fonts: Schibsted Grotesk for menus, dialogs, grids and output, with digits of equal width so numbers line up in columns, and JetBrains Mono for syntax. Both are under the SIL Open Font License. Characters they lack, such as Cyrillic in Schibsted Grotesk, come from system fonts (Segoe UI and Consolas on Windows, DejaVu, Noto or Liberation on Linux). Set STATSCRAFT_FONT or STATSCRAFT_MONO_FONT to a .ttf file to use another font first.