ChakataStat
Download

Working with Data

Everything in ChakataStat starts with a dataset. This page covers getting data in and out, the two ways you look at a dataset (Data View and Variable View), the native .ckd document, and the tools for tidying a dataset up.

The shape of a dataset

A dataset is a rectangle: rows are cases, columns are variables. Behind the scenes a variable holds one of just two storage types:

  • Numeric — numbers; a blank or non-number is missing.
  • String — text (and dates are entered as text in ISO YYYY-MM-DD form).

On top of storage sits each variable's definition (label, value labels, measurement level, missing rules) — that lives in the Variable View and travels with the data inside an .ckd file.

Importing data

File → Import Data… reads:

  • CSV / TSV — the delimiter and header row are detected; each column's type is inferred (all-numeric → numeric, otherwise string). An import-options dialog lets you confirm before loading.
  • Excel (.xlsx) — the first worksheet, read in pure Dart.
  • Parquet — typed columns read directly by the native engine.
  • JSON — either an array of records ([{"age": 30, …}, …], one object per case) or a columnar object ({"age": [30, 31, …], …}). The column names come from the JSON, so there is no header prompt; each column's type is inferred like CSV.

A progress dialog shows while large files load, and the import runs without freezing the window.

Tip. After importing a CSV, visit the Variable View and set measurement levels and labels. Type inference gets storage right but cannot know that a numeric 1/2 column means Male/Female — that is a value-label job (below).

Exporting data

File → Export Data… writes the current dataset (honouring any active case filter) to CSV/TSV, Excel, Parquet or JSON (an array of records) — the format is chosen from the file extension you give.

To export results rather than data, see the output log export.

The Data View

The Data View (Ctrl+1) is the spreadsheet you type into:

  • Click a cell and type to edit; Tab/Enter move the active cell.
  • Paste (Ctrl+V) a block from another spreadsheet; rows and columns grow to fit. Typing into the empty grid creates the first variables automatically.
  • Find & Replace (Ctrl+F) opens a search bar with match case, entire cell and wrap-around options; Replace All is a single undoable edit.
  • Hover any column header to see that variable's label, type and measurement level as a tooltip — the editor documents itself.
  • When the dataset is empty, the view shows an empty state with Open and Import buttons instead of a blank grid.
  • Hide a column you don't need right now: right-click its header and choose Hide column (selecting several headers first hides them all together). A thin double line marks where columns are hidden — click it, or right-click the header on either side and choose Unhide, to bring them back. View → Unhide All Columns is the escape hatch if you lose track. Hiding is a display preference, not a data change: the variable still exists, still appears in every dialog's variable list, and stays valid in .cks syntax — it just isn't shown in the grid.

Edits are undoable (Ctrl+Z / Ctrl+Y).

The Variable View

The Variable View (Ctrl+2) shows one row per variable. The columns are the variable's metadata; click a cell to edit it:

Column Meaning
Name The variable's identifier (used in commands and expressions).
Type Numeric or String.
Width / Decimals Display width and decimal places (numeric).
Label A human-readable description shown in output instead of the name.
Values Value labels — map stored codes to text (e.g. 1 → Male).
Missing User-missing values — codes that mean "no answer" and are excluded from analysis (e.g. 99 → declined).
Measure Measurement level: Scale, Ordinal or Nominal.

Why the measurement level matters

The Measure tells procedures how to treat a variable:

  • Scale — a true number (age, blood pressure): means, correlations, the numeric axis of a histogram.
  • Ordinal — ordered categories (education level): ranks and ordered tests.
  • Nominal — unordered categories (region, sex): counts, crosstabs, grouping.

Charts and dialogs use the level to offer sensible defaults and to label output, so setting it correctly is worth the minute it takes.

Value labels and missing values

Both are edited in a small dialog from the relevant Variable View cell:

  • Value labels make output readable — a crosstab shows Male/Female instead of 1/2, and the underlying codes stay numeric for analysis.
  • User-missing values mark specific codes as "not a real value". They reach the engine as nulls and are dropped from every statistic, while still being visible (and editable) in the Data View.

Saving: the .ckd document

File → Save (Ctrl+S) writes an .ckd file — ChakataStat's native document. Unlike a CSV, it stores both the data and every variable definition (labels, value labels, missing rules, measurement levels), plus document provenance. Reopening an .ckd restores the dataset exactly.

Internally .ckd is a versioned ZIP of a meta.json (all metadata) and a typed data.parquet (the columns). You never need to look inside, but the format is documented for the curious in docs/file_format.md.

Your wider session — the open document, the results log, the AI conversation and the syntax — is also remembered between launches, and the unsaved working dataset is autosaved for crash recovery.

Tidying a dataset

A few tools under the Data menu help with messy or wide datasets:

  • Define Variable Properties… — scan the data and set value labels, measurement levels and missing rules for several variables at once, guided by the values actually present.
  • Bulk Rename Variables… — rename many variables with a regular expression (with $1 group references), a live preview and collision-safe de-duplication. Ideal for stripping a common prefix or renaming q1, q2, ….
  • Define Variable Sets… — group related variables under a name; the Variable View's set filter then focuses on just that group. Sets are a view convenience — they never change the data — and persist with the session.

The data dictionary (.ckdict)

File → Export Data Dictionary… writes all variable metadata to a standalone, versioned JSON .ckdict file — names, labels, types, value labels and missing rules, without the data. Import Data Dictionary… applies one to the current dataset: it matches by variable name, writes only the fields each (even hand-edited, partial) entry carries, leaves your data untouched, and reports the fit (applied / unmatched / not in dictionary).

This is how you reuse one carefully-defined codebook across many data files.

Where to go next