Skip to content

Cumba Data Browser - User Manual

Manual v0.5 - last reviewed against Cumba Data Browser 0.5.7 on 27 October 2026

⚠️ Disclaimer: All sample data shown in this manual is provided by CDISC and PHUSE as freely available CDISC-pilot examples. No real clinical or patient data is used.

💡 This manual describes what each feature is. If you would rather be walked through a real task from start to finish, the User Guide does that - one everyday review workflow, step by step, with the shortcuts along the way.


1. Introduction

The Cumba Data Browser is a generic tool for exploring tabular data - supporting a wide range of file formats and giving you a fast, modern way to inspect, filter, sort, transform, and visualize any dataset.

Cumba was developed by people who have spent 25+ years in clinical and preclinical data analysis, so the tool is specifically optimized for CDISC-aligned workflows (SDTM, ADaM, SEND). But the core engine is fully generic: most features work on any tabular data, regardless of domain.

What works on any dataset

  • Loading, viewing, navigation
  • Filtering, searching, sorting, grouping
  • Column management (hide, pin, reorder, find)
  • Statistics (frequencies, descriptive)
  • Charts and visualizations
  • Format conversion (read/write any supported format)
  • Dataset comparison
  • SQL queries
  • Smart Number Display, tooltips, column markers
  • Multi-pane workspace, split layouts
  • AI Agent

Clinical/preclinical-specific features

These only become meaningful with CDISC-aligned data: - Quick Merges with standard CDISC domains (DM, ADSL, SUPP, SUPPDM, RELREC) - Optimized Transpose for ADaM BDS structures - Validation findings overlay - from the built-in coreJ check, the Define-XML check, or a loaded validation report (Pinnacle 21, CDISC CORE / coreJ) - Define-XML integration (display, validation, metadata) - CDISC metadata store as a library - browse the seeded CDISC standards and controlled terminology as tables, offline and without an API key - CDISC Library API access - browse CDISC Library content as a library (requires your own API key) - SEND-IG support for nonclinical/animal study data

Designed for

  • Non-technical users who need a quick look at their data
  • Data managers, statisticians, and analysts who inspect, transform, validate, or compare datasets
  • Clinical and preclinical programmers working with CDISC standards
  • Anyone who wants a modern, fast, intuitive data browser without the overhead of larger systems

Key principles

  • Intuitive - no scripting required for everyday tasks
  • Minimal visual noise - the UI only highlights what matters (outlier marking, on-demand tooltips)
  • Fast - optimized for large datasets
  • Multiple datasets and formats can be open in parallel
  • SQL-native - every action that changes which rows you see or their order (filter, sort, …) translates to SQL under the hood. Column visibility is a display setting, not part of the query: hiding a column does not change the view's SQL, so re-running the shown SQL elsewhere returns all columns
  • Fully scalable interface - seamless zoom in/out, crisp at any zoom level

Installing Cumba

Cumba is a desktop application. It is installed locally and runs on your own machine - there is no cloud requirement and no account. Download the current release for your platform from cumba.net:

Platform Package
Windows x64, ZIP
macOS Apple Silicon, DMG
Linux x64, TAR.GZ
Any platform with a JVM Cross-platform Java, ZIP

The Windows, macOS and Linux packages bring their own Java runtime - nothing else needs to be installed. The cross-platform ZIP needs Java 25 or later on the machine and is started with databrowser.sh.

On Windows, unpack the ZIP and start databrowser.exe. In 0.5.7 that launcher is not code-signed; if your organisation blocks unsigned programs, use databrowser.cmd instead (README-windows.txt in the installation folder explains the alternatives).

Memory: 8 GB of RAM is the minimum, 16 GB is recommended. That is a laptop, not a server - and it is enough for production-sized data:

A 5 GB SAS file opens in under 500 MB of memory
5 million rows sorted in under a second
50 million rows loaded and browsed without paging

For files, Cumba reads whole datasets rather than paging through them, so scrolling, sorting and filtering stay immediate once a file is open.

Cumba starts with a maximum Java heap of 4 GB. On Windows and Linux, and with the cross-platform ZIP, change -Xmx4g (e.g. to -Xmx8g) in databrowser.jvmargs in the installation folder and restart. The macOS app carries its own JVM options.


2. Data Access & Formats

2.1 Supported File Formats

Cumba can both read and write the following formats:

  • SAS7BDAT - SAS dataset
  • XPT - SAS transport file
  • Parquet - columnar storage format
  • Dataset-JSON - CDISC's JSON-based dataset standard, in all three of its shapes: .json, line-delimited .ndjson, and compressed .dsjc
  • RData / RDS - R data formats. .RData (also written .rda) holds one or more named objects saved with save(); .rds holds a single object written with saveRDS(). A data frame reads as it does in R: a matrix column becomes one column per matrix column (m.1, m.2, or m.<name>), a packed data-frame column one per inner column (outer.inner), and a list column shows each cell's values joined by ,. A column no table can show - an R expression, function, environment, S4 object or an array of three or more dimensions - is dropped with a warning naming it (in the log and the table's tooltip). A single .rds file always opens this way. To have an .RData / .rda library fail to open such a table instead, choose Unusable columns → Refuse the load in the advanced options of Open With Properties… (or later Library Properties…, which reopens the library with the new choice; a dataset's own Open With Properties… can override it). An R environment has the same option in its Library Properties…; applying it reopens the environment, which restarts it.
  • XLSX - Microsoft Excel workbooks (read and write, including export of multiple datasets to multiple sheets in a single file). An Excel column is read as numeric when its first 10 240 rows hold at least one number and no text; a column with no value there (and every column of a sheet with only a header row) is read as text, as in CSV. A number in a text column, and a numeric column header, read as the plain number (5, not 5.0; a header 2026, not 2026.0); if a numeric header's name is already taken, the column is named 2026_1.
  • CSV - comma-separated values
  • CDT - Cumba's own data table format (.cdt)

Cumba also reads SAS format catalogs (.sas7bcat, see Where Formats Come From), Define-XML files, and validation reports (Pinnacle 21 Excel, CDISC CORE / coreJ JSON or Excel). Libraries can also come from Open Study Builder, the CDISC Library, Databricks or a SQL database (see 2.3 and 2.6).

2.2 Data Conversion

Two ways to save data in another format:

  • File → Export - quick save of the currently active dataset, optionally in a different format
  • Tools → Convert Data… - full-featured converter; supports single files, entire libraries, and dataset expansion for performance testing

2.2.1 Convert Data Dialog

Convert Data dialog - Source (dataset or library), Target, Format, the define.xml options and Expand Convert Data dialog - Source (dataset or library), Target, Format, the define.xml options and Expand

The Convert Data dialog has two modes:

Mode Use
Dataset Convert one dataset file to another format
Library (multiple datasets) Convert all datasets of a library, written either as a Folder (one file per dataset) or as a Single file (for formats that hold several datasets in one file)

Optional: Expand generates large synthetic datasets from real ones by replicating rows with new unique IDs.

Field Description
Expand (checkbox) Enable expansion mode
Factor Multiplication factor (e.g. 12 → 12× the original size)
ID variable Subject identifier to be uniquified across copies (e.g. USUBJID)

💡 Expand datasets use cases: performance testing, large-scale demos, workshop datasets, stress-testing pipelines. Because the expanded data is based on real source data, distributions and structures stay realistic - unlike random synthetic generation.

Define-XML alongside the data. When a library is converted into a folder, Create define.xml (on by default) writes a define.xml describing the converted datasets, so the metadata travels with the data instead of being rebuilt by hand at the other end. A library converted into a single file gets its define.xml next to that file, each dataset referenced as <file>#<dataset> (e.g. lib.xpt#DM), and such a define.xml opens back as a library. If a define.xml already exists there, Cumba asks for the name to write (overwriting it is confirmed). The single-file option is offered only where the connection supports it (a remote server older than this release does not). Value-level metadata from data adds value-level metadata and data-derived codelists - a starting point; Origin and Method stay yours. The variables' lengths (in characters) and digits are always measured from the converted data. CT packages and Implementation guide set what the generated file declares; both offer only what the metadata store holds. To check an existing Define-XML, use Tools → Validate Define-XML (see Section 10.8).

⚠️ One thing to know before you convert: a loaded dataset has its proposed order applied, and it is that sorted view which gets exported. The output can therefore be ordered differently from the source file. If byte-for-byte row order matters - for a submission, or for a diff against the original - check the order after converting. (The CDISC rule engine deliberately undoes this, because rules must evaluate in source row order.)

During library conversion, Cumba shows a live counter of the dataset being processed and its position in the library (e.g. Converting LB (6/22)…), so you always see real progress on long-running jobs. An Abort button lets you cancel at any time. When the conversion finishes, the status bar shows a confirmation with count and target path (e.g. Converted 22 of 22 datasets to C:\test data.). If there is more to report - skipped or failed datasets, renamed members, a define.xml or formats catalog written - a summary dialog lists it.

💡 Convert Data is a data conversion from one location or storage format to another. Accompanying formats are now included in the conversion - variable formats are carried along with the data, for target formats that have a concept for them. Other format-specific considerations: - Parquet has no standard concept for formats/codelists, so carrying format information into Parquet is not straightforward. - A library can be exported into one file - an Excel workbook with a sheet per dataset, a single XPT with one member per dataset, or an R workspace (.RData / .rda) with one object per dataset. Excel and XPT cap member names (31 characters for Excel, 8 for XPT); where two dataset names would collide after truncation, Cumba renames them apart and reports the renames rather than silently merging them. Appending a colliding member to an existing XPT is refused. A single XPT is written in one charset: the members' common charset when they all report the same ASCII-compatible one (UTF-8, ISO-8859-1, windows-1252, …), otherwise UTF-8. An XPT stores no charset, so open a non-ASCII one with that charset set.

2.3 Support for CDISC standards

This section describes Cumba's CDISC-specific capabilities. For non-CDISC data (any other tabular dataset), all the generic features described elsewhere in this manual still apply.

Cumba supports the major CDISC standards out of the box:

  • SDTM - Study Data Tabulation Model (clinical patient data)
  • ADaM - Analysis Data Model (clinical analysis datasets)
  • SEND - Standard for Exchange of Nonclinical Data (preclinical/animal studies; structurally based on SDTM)
  • Define-XML - read, display, and use for validation and metadata
  • CDISC metadata store - File → Open Library → Metadata Store opens the metadata store (seeded below) as the library CDISC Store: # PRODUCTS (what the store holds, side by side with what it lists as declarable), # CT PACKAGES, # CODETABLES (when seeded), # PROVENANCE (how it was seeded), one member per product - the foundational models (SDTM, CDASH, ADaM) too - and one per CT package, plus the aggregates # METADATA (every product's variables and fields, about 25 000 rows) and # CODELISTS (every CT package's terms, about 1.75 million rows; opening it takes a few seconds and about 60 MB of memory). No API key and no network are needed; on a remote connection the library shows the server's store. The tables carry the columns of the CDISC Library API library below wherever the store holds them; the CT package's name, label, description, source, effective date, registration status and version are not held, and a few values may differ where the store carries corrected text. A product the store holds without content (the ADaM v2.1 model, in a store seeded from the rules engine repository) opens with no rows. After a re-seed, refresh the library (or open it again) before opening a member: a member opened from a library that was not refreshed still shows the old content. The library needs the CDISC Library licence feature, like the API library.
  • CDISC Library API - open the CDISC Library as a library (File → Open Library → From URL, https://api.library.cdisc.org/api/…) to browse standards and controlled terminology, using your own API key. Validation does not need the key; it reads the metadata store below. It stays available in this release beside the metadata store library above.
  • CDISC metadata store - Edit → Settings… → Validation → Metadata Store seeds the metadata store that validation reads (CDISC standards and controlled terminology), from the public CDISC rules engine repository (a download of about 82 MB) or a local copy - no API key is needed - or, if you have a CDISC Library account, directly from the CDISC Library API with your own key. Cumba itself ships none of it. See Section 10.7.
  • External dictionaries - Edit → Settings… → Validation → CDISC Dictionaries installs MedDRA, WHODrug, SNOMED CT, LOINC, UNII, MED-RT, neoplasm and HGNC. Not shipped either.
  • Open Study Builder - open an OSB instance as a library via its API URL (File → Open Library → From URL), inspect its metadata like any other Cumba library

💡 To use the CDISC Library API, register at www.cdisc.org/cdisc-library/api for an API key. Then either set the environment variable CDISC_API_KEY, or add the key to your user settings file ~/.cumbaDataBrowser/databrowser.conf (Windows: %USERPROFILE%\.cumbaDataBrowser\databrowser.conf):

[properties]
cdisc.library.api.key = <your-key>
Optional entries: cdisc.library.api.url (default https://api.library.cdisc.org/api/) and cdisc.library.api.cache (where the library browser caches responses; a metadata store seed never uses a cache). The comments in the installation's databrowser.conf explain the file.

2.4 Encoding & Internationalization

Cumba works in UTF-8 / Unicode throughout, including CJK scripts (Chinese, Japanese, Korean), accented Latin characters and other scripts. This matters for global clinical trials where reported terms (e.g. AETERM, MHTERM) may contain text in local languages.

XPT and CSV files do not record their encoding, so Cumba reads them as UTF-8 unless you choose another Charset when opening: for a single file, reopen it and choose its charset in the Charset option; for a library member, right-click it → Open With Properties…. SAS7BDAT files record their encoding; the Charset field can override it. If a value cannot be decoded with the charset in use, the load stops and names the column and row, so choose the file's real charset. A single-byte charset accepts every byte (Latin-1) or almost every byte (Windows-1252), so a wrong choice there shows wrong characters instead of an error. A dataset of an XPT library uses the library's Charset; reopen the library to change it. For a CSV file the message also names the line of the file; the Charset is chosen per file when you open it.

2.5 Remote Data Access

Clinical data often may not leave the server it lives on. For such setups Cumba can work with a Cumba backend running on that server: the backend reads the files there and sends the view to your screen.

The backend and the matching remote access in the data browser are available on request - they are not part of the standard download. Contact us if you need them.

Transport Use
SSH Cumba connects over an ordinary SSH login, starts a backend session on the server and talks to it through that connection. The remote file system is browsed over SFTP.
HTTP(S) For a backend that runs as a service and is reachable over HTTP.

Most features work on remote data as on local data. Machine-level maintenance such as seeding the metadata store (Edit → Settings… → Validation → Metadata Store) applies to the machine it runs on: on a remote setup, the server's metadata store is used.

Connecting over SSH. An installation with the remote access connects at start-up when your user databrowser.conf holds, under [properties],

dataviewer.connection = ssh

Cumba then asks you to sign in: server, port, user, and a password, a key file (with its passphrase, if it has one) or your SSH agent. The backend command is the path of databrowser-backend on the server (the default works when the server's login finds it). You can save the sign-in as a profile; a profile never holds the password. The first connection to a server shows its key fingerprint: accept it once, or accept and remember it in ~/.ssh/known_hosts. A server whose key has changed is refused. If the sign-in is cancelled or fails, Cumba does not start - it never falls back to your local files silently.

A cut connection. When the network drops (a laptop moving from LAN to WLAN, a VPN reconnecting), the open views show Connection lost and Cumba reconnects by itself, again and again - after 1, 2, 4 … seconds, at most every 30 seconds - without asking for your password again (it is kept in memory only, never on disk). The status line says how long the server keeps your session without a client (the server's administrator sets this; 30 minutes by default). Once reconnected, the views work on as before. Tools → Reconnect Now tries at once; Tools → Disconnect… ends the session and stops reconnecting. If the server refuses the password (it was changed meanwhile), Cumba asks once for the new one.

An expired session. If the connection stayed lost longer than the server keeps a session, the server has closed it, with every data set it had open. Cumba then closes those views, starts a new session and asks whether to reopen the data sets and libraries that were open or close them. Edits that were not exported are named in that question. If the file on the server is unchanged since you started editing it, they are applied again when you reopen it, and the data set opens in an editor with your edits. If the file changed, is gone, or cannot be checked (for example a Databricks table), the question says the edits are lost and why; the data set then reopens without them. A data set of a library - edited or only viewed - reopens through its library, with the options the library was opened with (Define-XML, Standard, CT packages, standard catalog), so its labels and display formats are back; if it is no longer in its library, its edits are named lost. For the edits, unchanged is strict: a file whose permissions or owner were changed on the server also counts as changed, and its edits are named lost. The server's backend must be updated together with Cumba; an older backend cannot say whether a file changed, so every edit is named lost.

2.6 Databases and Databricks

Besides files, Cumba can open tables that live in Databricks or in a SQL database. Both are read-only.

Databricks (Unity Catalog). File → Open Library → Databricks Catalog … signs in to a Databricks workspace - in your browser (OAuth) or with a personal access token - and opens a catalog schema as a library, next to your file libraries. Its tables open like any other dataset. A table Cumba cannot show faithfully (a view, a table with a row filter or column mask, a non-Delta table) is listed with the reason instead of being opened.

SQL databases (Oracle, MySQL / MariaDB, Databricks SQL). File → Open Library → Connect to Database … connects with a saved connection profile and opens the chosen schemas as libraries. Nothing is copied on open: Cumba queries the database page by page, and filters, sorts and statistics run in the database. Cumba ships no JDBC driver - install the one you need under Edit → Settings… → Connections → Database Drivers, from the built-in list or from your own jar files; each driver comes under its own licence.

In 0.5.7 a database session is a separate start of Cumba: add the line

dataviewer.connection.manager = net.cumba.datatable.manager.jdbc.JdbcDataTableManager

under [properties] in your user databrowser.conf (see the CDISC Library tip for where it lives). Local files are not available in such a session.

An administrator can switch either extension off for all users (see ADMIN.md in the installation folder).


3. Interface Overview

The application is divided into three main areas:

Area Name Purpose
A Top Menu & Toolbar File · Edit · Display · Columns · Sort · Filter · Tools · Window · Help - plus the toolbar below (Window → Appearance → Show Toolbar hides it)
B Libraries (left) Lists all loaded libraries, datasets, and formats
C Workspace (right) Tabs for opened datasets and formats

Cumba main window - Top Menu & Toolbar (A), Libraries (B), Workspace (C) with an opened ADSL dataset, the Tools → Merge menu, and a variable tooltip Cumba main window - Top Menu & Toolbar (A), Libraries (B), Workspace (C) with an opened ADSL dataset, the Tools → Merge menu, and a variable tooltip

Libraries (B) and Workspace (C) - an ADaM library on the left, the opened ADLBC dataset on the right with column markers, native-and-formatted values and the collapsed SQL bar Libraries (B) and Workspace (C) - an ADaM library on the left, the opened ADLBC dataset on the right with column markers, native-and-formatted values and the collapsed SQL bar

A lot of this manual is visible in that one shot: the FORMATS node at the top of the library, ⚠️ markers on the datasets that carry validation findings, F and N markers in the column headers, treatment codes shown as 0 - Placebo (native in black, decode in blue), row numbers that are not consecutive because the view is sorted, and the collapsed SQL bar above the table.

💡 Right-click menus matter. Many of Cumba's most useful functions live only in the right-click context menus - on cells, columns, datasets, and libraries. The top menu bar shows the global functions; the context menus expose the targeted ones. If you only use the top menus, you will miss important features. Whenever you wonder "is there a way to do X here?", right-click first.

3.1 Workspace Layout (Split Panes)

The Workspace can be divided into multiple panes for side-by-side viewing of datasets, formats, statistics outputs, or the AI Agent. There are four ways to manage the layout - pick whichever feels most natural:

  1. Drag tabs to side or bottom edges → splits the pane in that direction (most intuitive)
  2. Drag a tab out of the window → it opens in a window of its own, e.g. for a second monitor
  3. Window → Perspective ▶ → preset layouts: Reset to Default (Ctrl+Shift+D); with the AI Agent installed also Classic (no AI) / Chat Right / Chat Bottom
  4. Right-click on a tab → tab context menu (see below)

Window → Appearance → Tab Placement ▶ (Top / Bottom / Left / Right Placement) sets where the tab strip sits, for all panes.

Tab context menu - right-click on any tab in the Workspace:

Tab context menu - Select in Libraries, Store Table Settings, Split Right / Left / Above / Below, Maximize Region, Minimize Region, Show View List…, Close Region Tab context menu - Select in Libraries, Store Table Settings, Split Right / Left / Above / Below, Maximize Region, Minimize Region, Show View List…, Close Region

Action Effect
Split Right / Left / Above / Below Move the tab into a new pane in that direction (a pane's only tab cannot move: you get an empty new pane)
Maximize Region (Ctrl+Shift+M) Give the current pane the whole window: the other panes move to the trim bars at the window's edges (see below); Restore Regions brings them back. Double-clicking the tab strip does the same - the fastest way to give one dataset the whole window and hand it back.
Minimize Region / Restore Move the pane to a trim bar at the window's edge; its views stay open. On a minimized pane the entry reads Restore. The last pane of a window cannot be minimized.
Show View List… (Ctrl+E) Every view of the pane in a list with a filter; pick one to show it
Close Region Close the current pane; its tabs move into a neighbouring pane (only available when multiple panes exist)
Store Table Settings… / Remove Stored Settings for this Table (dataset tabs) See 7.5.10

Minimized panes and the trim bars. A minimized pane is an icon group on a trim bar at the window's edge, one icon per view. Click an icon to show the pane as an overlay above the others; it hides again when you work elsewhere in the window or press Esc, unless you Pin it. The minimize and maximize / restore buttons at the end of every tab strip do the same as the menu entries; Window → Perspective ▶ has Maximize Region, Minimize Region, Restore Regions and Show View List… too. Saved layouts keep minimized panes.

Many tabs. When a pane has more tabs than fit, its strip shows the most recently used ones and a view-list button with the number of hidden views (the same list as Show View List…). A tab never changes its width: an unsaved view is marked with *, a view with new data in bold, and a long title is cropped at Edit → Settings… → Appearance Maximum tab width (default 240; 0 = unlimited) with the full title in the tooltip.

To undo a split: drag a tab back into another pane. When a pane has no tabs left, the split collapses (the Libraries view and the main dataset area stay, as empty placeholders).

💡 Typical use cases: - Compare two datasets side-by-side (e.g. SDTM AE vs. ADaM ADAE) - Keep raw data visible while inspecting Frequency or Descriptive results - View source and target of a Merge or Transpose simultaneously - Data on the left, AI Agent on the right

3.2 The Window Menu

The Window menu (between Tools and Help) gathers what concerns the window rather than the data:

Entry Contents
Show View ▶ Libraries - shows the Libraries view: opens it when it is closed, brings it to the front when it is open. Settings - opens the settings (also Edit → Settings…). With the AI Agent installed also AI Chat (Ctrl+Alt+A, see Section 12.1). A view listed here exists only once: the entry opens it or brings it to the front, it never hides it - close a view with its tab or File → Close View.
Perspective ▶ Reset to Default (Ctrl+Shift+D); Maximize Region / Minimize Region / Restore Regions / Show View List…; with the AI Agent also Classic (no AI) / Chat Right / Chat Bottom - see Section 3.1
Appearance ▶ Show Toolbar (shows or hides the toolbar under the menu bar; also Edit → Settings… → Appearance), Tab Placement ▶ (Top / Bottom / Left / Right), Theme ▶ (Light / Dark / Auto, see Section 6.6), Zoom In / Zoom Out / Reset Zoom (see Section 6.5)

📝 If you keep your own menubar.json (a customised menu layout), Cumba keeps using it: your layout gets no Window menu until you add it there yourself.

3.3 Settings

Edit → Settings… (Ctrl+,, also Window → Show View → Settings) opens the settings as a view with a tree of pages on the left. The pages keep their explanations out of the way:

  • Tooltips. Hover a setting's label or control to read what it does and when to change it. The buttons, fields, lists and check boxes of Cumba carry such a tooltip - in the settings and in the dialogs alike (plain OK, Cancel and Close buttons aside).
  • The (i) beside a page title. Its tooltip says what the whole page is about.
  • Marker icons after a setting. A lock marks a value your administrator has locked (greyed, it cannot be changed). An information icon marks a value set elsewhere - by an environment variable or a JVM system property, which then wins over the saved value - or one that takes effect only after the next start. The marker's tooltip gives the reason.
  • A line under a setting appears only when the setting is blocked right now, with the reason and, where there is one, a button that resolves it (for example New conversation on the AI pages while a conversation runs).

Changes are pending until you click Save; Reset → Reset changes drops them. When a saved change takes effect only after the next start, Cumba tells you so in a dialog listing those settings ("These changes take effect after the next start: …") - restart Cumba to apply them. Closing the settings, or Cumba, with unsaved changes asks whether to save them; saving on exit shows no restart dialog, as the next start follows anyway.

Some pages run an action rather than store a value - Seed… on the Metadata Store page, Import… on the Licence page, the driver buttons on Database Drivers. Such an action is greyed while its page has unsaved changes (its tooltip says Save first), so it never works on values the page shows but has not stored.

The pages, and what is worth knowing beyond their tooltips:

Page Notes
General → Startup With Single instance on, a data set opened from the file manager or the command line goes to the running data browser instead of starting a second one. Written to your user databrowser.conf.
General → Recent Files / History Clear empties a list when you Save; entries added meanwhile are kept. History also holds the remembered coreJ check values (Section 10.7).
General → Licence A licence file elsewhere than ~/.cumbaDataBrowser/license.json; Import… copies a file to the default location instead.
Appearance, Charts, Data Display See Section 6.6, Section 9.2 and Section 6.
Data Display → Loading & Columns Applies to tables and libraries opened afterwards: page size, error tolerance, column sizing. A library opened from a folder always reads the formats and define.xml in that folder.
Filters → Memorized Filters / Stored Table Settings The memorized filters (7.5.7) and the stored table settings (7.5.10); a rename, change or deletion is pending until you Save.
Validation → Metadata Store / CDISC Dictionaries / Finding Review / coreJ Check See Section 10.7, Section 11.4 and Section 10.9.
Connections → Trusted Certificates The certificates you trusted; a removal is pending until you Save (Reset changes brings the row back). Database Drivers and Databricks Workspaces: Section 2.6 - a Databricks workspace is remembered for the connect dialog, its token never stored.
Extensions The optional modules: their version and status, and a switch per module.
AI Assistant See Section 12.1.3.

4. Libraries, Datasets & Formats

4.1 Libraries

A Library is a container holding one or more datasets and (optionally) formats.

  • Open Library - File → Open Library:
  • From File - open a single file as a library
  • From Folder - open all datasets in a directory as one library (typical for an SDTM study folder)
  • From URL - open an Open Study Builder (OSB) instance (its API URL, e.g. https://osb.cumba.net/api, see 12.2) or the CDISC Library (https://api.library.cdisc.org/api/…, see 2.3) as a library.
  • Metadata Store - open the CDISC metadata store as the library CDISC Store, see 2.3. Shown only when the data manager serves it.
  • Databricks Catalog … / Connect to Database … - see 2.6.

When opening a library, Cumba uses the selected folder name (or file name) as the default library name. The Open dialog only asks for the name. To add or change a descriptive label (e.g. "CDISC SDTM 3.1.2"), use Rename Library… from the library's right-click menu - the rename dialog lets you edit both name and label. A label is optional. If set, the library is shown as <Name> - <Label> in the explorer, with the name in dark and the label in blue (yellow in the dark theme) - the same visual convention used for datasets and variables. Without a label, only the name is shown.

  • Open Data Set - File → Open Data Set
  • Recent Files - File → Recent Files
  • Remove Library - File → Remove Library. Files on disk are not affected.
  • A Library may contain a FORMATS node, always shown at the top.

4.1.1 Library Context Menu

Right-click a library in the Libraries view for library-level actions:

Action Shortcut
Open Library ▶ –
Rename Library… –
Remove Library –
Reload - list the library's tables again, each at its latest version (refused while a validation report view of it is open) F5
Library Properties… - show the library's open options and reopen it with changed ones (see Open options below) –
Lock In Memory / Unlock From Memory (when the library type supports it) –
SQL Query… Ctrl+Alt+Q
Add Validation Report –
Show Validation Report –
Check Using coreJ … –
Validate Define-XML (libraries opened from a Define-XML) –

Show Validation Report opens the report attached to the selected library in a report view (Overview / Rules / Data sets / Findings, see Section 10.5) - also for a clean run with no findings; without an attached report it only says so.

Open options. A folder, a single-file library or a .dblib can be opened with Open With Properties…, and changed later with Library Properties… (OK reloads the library):

  • Define-XML - the define whose labels, formats and code lists are shown. It is pre-set to the define.xml beside the data (whatever its case) or the one a .dblib links; blank means none, and the folder's own define.xml is then not read for formats either.
  • Standard and CT Packages - the standard and controlled terminology of the data, offered from what the metadata store holds and pre-selected from the define. A guide whose download failed during a seed is not offered.
  • Use Standard Catalog - where neither the dataset nor the define gives a label or format, the selected standard's is shown (its code lists decoded with the selected CT). Such values show in italics, with their source in the tooltip; when the catalog cannot be built, a message says why.

Opening a library that is already in the tree with other options reloads it with them (refused while a validation report view of it is open). The checks (coreJ, Define-XML) always read the data as delivered. Exports, Convert Data and generated defines include the catalog's values unless Write labels and formats from a standard catalog into exports (Edit → Settings… → Loading & Columns, formats.exportCatalogMetadata) is switched off.

💡 "Lock In Memory" keeps all datasets of the library loaded in RAM, so subsequent access is fast - at the cost of memory. Useful for libraries you switch between often.

4.1.2 Dataset Icons (Color-Coded by Format)

Datasets share a common barrel ("can") shape as their icon - both in the Libraries view and in the Workspace tab header. The color identifies the file format; no letter labels are used:

Color Format(s)
🟦 Light blue SAS (.sas7bdat, .xpt)
🟧 Light orange JSON (.json, .ndjson, compressed Dataset-JSON .dsjc)
🟩 Green Parquet
⬜ Grey all other formats (CSV, XLSX, RData/RDS, .cdt) and database tables

A dataset icon can carry small emblems: a yellow warning bottom-right when the dataset has validation findings, and an "i" bottom-left when table settings are stored for it. A locked library shows a padlock.

Formats use the same barrel shape but always in grey, regardless of source - so a format tab is visually distinct from a dataset tab at a glance. See Section 4.3.

4.2 Datasets

  • Open a dataset: double-click in the Library → opens as a tab in the Workspace. Double-clicking a dataset that is already open brings its tab to the front. Enter opens the selected dataset; Ctrl+Enter or Ctrl+double-click opens it with the property dialog.
  • Close a tab: hover over the tab to reveal an ✗ icon, or use Ctrl+W (Close View).
  • Multiple datasets and formats can be open at the same time.

4.2.1 Dataset Context Menu

Right-click on a dataset in the Libraries view:

Action Description
Open Library ▶ Open another library (From File, From Folder, From URL, Metadata Store; plus Databricks Catalog … and, in a database session, Connect to Database …)
Open Open the dataset (default)
Open With Properties… Open in a new tab and prompt for provider properties (e.g. CSV delimiter, Excel sheet, JSON path) - useful when auto-detection picks the wrong settings
Edit Open the dataset in the data editor. Edits stay in memory; they can only be saved by exporting (see note below)
Check Using coreJ … Run the coreJ check on the library this dataset belongs to (see Section 10.7)
Show Validation Report Open the validation report attached to the library

📝 On Edit: changes cannot be saved back to the original file - modified data can only be exported under a new name. Edit is intentionally not a central function of Cumba; it's available for occasional ad-hoc adjustments only.

4.2.2 Variable List in the Libraries View

Expand a dataset in the Library to see its variables. Each entry shows: - Variable name (e.g. AGE) - Label (e.g. "Age") - Type icon: 12 for Numeric, AB for Character

💡 Note: The Libraries view shows the type icon for every variable (both numeric and character) - useful when scanning a long variable list. In the dataset's column headers, by contrast, only the less common case is marked (the N marker; see Section 5.1). Both are intentional - full information in the variable list, minimal noise in the data view.

Code completion via Ctrl+Space: in the variable fields of the Merge, Compare, Transpose and Chart dialogs, and in the SQL editor, Ctrl+Space opens a completion list of the dataset's variables with their labels - type to narrow it down, like code completion in an IDE.

Right-click a variable for context actions: - Open Library ▶ - open another library (the same submenu as on every node) - Open Attached Format - open the format attached to this variable directly from the Libraries view, without opening the dataset first

Double-click a variable to open its dataset (or bring its tab to the front) with that column selected; variables selected together in the tree are selected together in the table.

4.2.3 Dataset View in the Workspace

Each dataset opens as a table. Column headers display: - Variable name (top) - Label (below the name) - Column markers (see chapter 5)

A collapsible SQL bar sits above the data view - see Section 6.4.

When the files change on disk. When the member's own file is rewritten or removed, or - for a library opened from a single file (a define.xml, a .dblib) - that file changes, the tab shows a banner when you return to it: "Library changed on disk – Reload"; reloading a library (F5) marks nothing. Reload reopens the dataset in place with the same options, filter and sort. If the dataset is no longer in the library, the banner says so. In a dataset opened for editing, Reload is not offered - export your edits first, or close and reopen the dataset. A change of the file's permissions or owner alone shows no banner. After a file was rewritten with its modification time put back (a copy that preserves times), Reload (F5) reads the new content, even when no banner shows (macOS and Linux).

Findings from a validation report older than the dataset file are not shown; when the library opens (or is reloaded), a warning names the dataset and both dates - re-run the check or attach a current report.

4.2.4 Rich Dataset Tooltip

Hovering over a dataset tab shows a comprehensive metadata tooltip. The dataset's entry in the Libraries view shows the same without the Columns / Rows / Condition / Order lines:

Identity: - Name, Label

Size & state: - Columns - number of variables - Rows - number of records (when filters are active, shows filtered of total, e.g. 874 of 59 580) - Condition - active filter as a condition expression (e.g. LBTEST EQ "Specific Gravity") - Order - current sort order. Variables in parentheses define the By-Group keys; variables outside the parentheses are sub-sorts within each group. Each variable is followed by asc (ascending) or desc (descending), plus ignoring case for a case-insensitive sort. Example: (USUBJID desc, LBTESTCD asc), VISITNUM asc. The status line uses the same words when the order changes ("Order is now: …").

Source: - URI - file path or URL where the dataset was loaded from - Size, Last Modified - for local files

CDISC / Dataset-JSON metadata (when available): - Structure, Repeating, Purpose (Tabulation / Analysis) - Created, Modified timestamps - datasetJSONVersion, fileOID, originator - studyOID, metaDataVersionOID, itemGroupOID, metaDataRef

Validation findings (when validation reports are loaded): - Validation Findings - total count - on Rows, on Variable - counts of affected rows / variables - Up to 10 dataset-level findings (not tied to a row or a variable), each as Finding: <Rule-Id> (<Kind> - <Severity>) - <source> with its Message

💡 Press F2 to focus the tooltip - this allows you to select and copy text from it. The same F2 pattern works on all tooltips throughout the application.

4.3 Formats

If a Library contains formats, they appear under a FORMATS node at the top of the Library.

Naming convention: - $NAME - character format - NAME (no $) - numeric format

Format type indicators (icon-based):

Icon Type Description
📜 ✅ (with green check) Real Mapping Code differs from Decode - values are translated for display. e.g. $ARMCD: 1 → ACTIVE TREATMENT, 2 → PLACEBO.
📜 (without check) Identity Format Code equals Decode - no translation, only validation of permitted values. e.g. $COLOR: green → green, yellow → yellow, red → red.

💡 The visual distinction lets reviewers know at a glance whether a column with this format will show transformed values (Real Mapping) or pass-through values (Identity).

Hover tooltip on a format shows: - Values: number of entries - From a Define-XML or dictionary, when present: Display Name, Label, NCI Code, Standard, Dictionary, Level, Status - Real Mapping: Yes / No

Open a format: double-click → opens as a tab in the Workspace, displaying: - FMTNAME - format name - TYPE - Char or Num - START - the code value - LABEL - the decoded value

Format tabs use the grey barrel icon in the tab header - visually distinct from the colored barrel icons of dataset tabs (see Section 4.1.2).

Format tab in the Workspace - grey barrel icon distinguishes formats from datasets Format tab in the Workspace - grey barrel icon distinguishes formats from datasets

4.4 Where Formats Come From

This is the part that surprises people, so it is worth being precise. A formatted column needs two pieces of information, and they usually live in two different files:

  1. Which format does this column use? - just a name, such as $SEX or AGEGR1F. This travels in the dataset's own column metadata.
  2. What does that name mean? - the actual code → decode entries, e.g. F → Female, M → Male. This comes from a format catalog, which is a separate file.

A sas7bdat or an xpt therefore does not contain its own decodes. It says "this column is formatted with $SEX" and nothing more. Without a catalog, Cumba knows the column is formatted but not what the codes stand for: the values are shown unformatted, the header shows the F marker with a small red ✕, and the column tooltip's Format line says that the format is not available.

Where the format name comes from:

File type Carries a format name?
SAS (sas7bdat, xpt) Yes - the format attached to the variable in SAS, exactly as SAS stores it
Parquet Only in files written by Cumba. Parquet has no slot for a format name, so Cumba writes its own key-value block into the file. A Parquet from another tool carries none.
Define-XML Yes - the variable's CodeList reference
Dataset-JSON Yes - the column's displayFormat
CSV · XLSX No - values are shown as stored (XLSX date columns get a date display format, not a codelist)

Where the mapping comes from - the two catalogs:

Catalog What it is
sas7bcat A SAS format catalog. Put it in the dataset's folder and its code → decode entries apply to every column whose format name it defines. A ranged format (e.g. low-<0 = 'negative', 'A'-'M' = 'first half') is not loaded: Cumba maps single values only, so it leaves that format out - the log names it - rather than apply it halfway. The same holds for a format table in PROC FORMAT CNTLOUT= layout (a formats.* dataset next to the data).
Define-XML The codelists in a Define carry their own entries, so a Define is data description and format catalog in one.

📝 Nothing else supplies decodes. R factors are the apparent exception and are not one: .RData and .rds store factor levels inside the file, and Cumba resolves them while loading - the cell already contains Female, not a code plus a lookup. So there is no format, no F marker and no Native/Formatted pair on an R factor column.

Catalogs stack. When Cumba opens a dataset it collects the catalogs in the dataset's folder, in this order: every *.sas7bcat (by file name; if there is none, the formats.* tables), then define.xml, then Cumba's built-ins. When several define the same format name, the first in that order wins; the later ones still serve every format name the earlier ones do not mention. You do not load a catalog by hand - Cumba picks them up from the folder.

A second meaning of the word "format". SAS format strings such as BEST12.2, $CHAR20. or DATE9. describe how a value is printed - width, decimals, date layout - not what a code stands for. Cumba reads and applies those too, but they are display instructions rather than codelists, and they never turn an F marker red: there is no list of permitted values to be missing from.


5. Column Markers, Tooltips & Smart Number Display

5.1 Column Markers

To minimize visual noise, Cumba shows markers only when relevant. The principle is outlier marking: only the less common property is shown as a marker. Columns without a marker are the default case.

Marker Meaning
N (square) Numeric column. Columns without this marker are Character.
F (round) Formatted column - a code list / format is applied.
F with a red ✕ The column names a format that no loaded catalog defines - values are shown unformatted (see Section 4.4).
F (pink-red) Formatted column with unmapped values - the column contains values that are not defined in the attached format. Use Filter ▶ With Unmapped Values in the column's right-click menu to show the affected rows, or List Unmapped Values … to list them. The cause is for the reviewer to decide. For Controlled Terminology codelists (non-extensible) the unmatched value is most likely a data quality issue (wrong, mis-cased, or typo'd). For extensible codelists, a sponsor-added value is also possible - but extensibility doesn't eliminate data quality issues (typos, case inconsistencies, mojibake can all occur in extended values too). Cumba flags the symptom; the interpretation is yours.
Filter icon - the funnel An active filter is applied to this column.
▲ / ▼ (with optional priority number, optional "ball") Sort direction. Number = priority in multi-sort. Ball indicates By-Group sorting.
⚠️ Yellow exclamation Column has validation findings (when "Show Validation Findings" is enabled). Findings can come from any validation source - Define-XML, Cumba's built-in checks, or a loaded CDISC CORE / coreJ or Pinnacle 21 report.

Markers can combine - e.g. a formatted numeric column shows both F and N; a filtered formatted numeric column shows F, N, and the filter icon.

💡 The funnel icon is the visual signature of Cumba: it appears in the application logo, in the toolbar, and on filtered columns.

💡 When the dataset opens, Cumba checks every column with an attached format and compares the actual values against the format's defined codes. If any value isn't in the format, the F marker turns red - a quick visual cue for codelist compliance issues.

📝 Planned: Hovering the F marker will preview the format values inline. Not yet available.

5.2 Cell & Column Tooltips

Hovering over a cell shows a rich tooltip with three levels of information:

Cell value: - Value - the displayed value (with ≈ prefix if rounded; see Smart Number Display) - Exact - the full underlying value (when the displayed value is rounded) - Formatted - the decoded value (when a format is applied)

Column metadata: - Name, Label, Type, Length, Format

Define-XML metadata (when a Define-XML is loaded): - Origin (Derived, Collected, Assigned, CRF Page reference, etc.) - Role (Identifier, Topic, Variable Qualifier, Timing, etc.) - Comment - derivation logic or notes - OrderNumber, KeySequence, Mandatory - dataType, targetDataType, itemOID

Validation findings (when present on the column): - Validation Findings - count - Per-finding details: Source · Rule-Id · Severity · Kind · Message · affected Rows

💡 Press F2 to focus the tooltip and copy text from it.

Tooltips can be globally toggled via Display → Show Tooltips.

💡 Variable tooltips work everywhere a variable appears - not only in the data view, but also in every variable-picker dialog (Find Column, Transpose, Frequency By, Merge data set, etc.). Hover and pause anywhere you see a variable name, and Cumba shows its full metadata.

5.3 Smart Number Display

Numeric values are rendered with extra visual cues to make data quality and floating-point behavior immediately visible.

5.3.1 Rounded Values

When a number cannot be displayed exactly (typical for floating-point arithmetic results), Cumba shows it with an ≈ prefix to indicate that the displayed value is rounded.

Cell shows Meaning
8.55 Exact value
≈8.55 Rounded - the actual stored value differs slightly

5.3.2 Display vs. Exact in Tooltips

The cell tooltip shows both: - Value - what the cell displays (e.g. ≈8.55) - Exact - the full underlying value (e.g. 8.549999999999999)

💡 Why this matters: floating-point arithmetic is everywhere in clinical data, but other tools hide it. A filter AVAL > 8.55 can include or exclude apparently identical "8.55" rows depending on the hidden floating-point reality. Cumba's ≈ prefix and exact-value tooltip let reviewers write filters that mean what they intend.

5.3.3 Right-Aligned Numbers

Numeric columns are right-aligned, so frequencies, percentages and measured values can be compared at a glance; a numeric column with a code-list format is left-aligned like text.

💡 Example: in a Filter IN dialog, the columns # (count) and % (share) are aligned so that even a one-row difference between groups is visually apparent (e.g. 595 F / 596 M).

5.3.4 Repeating Decimals

A value such as 0.3333333333333333 is shown as 0.3 with a line over the repeating 3. The tooltip's Exact line keeps the full value. Turn it off in Edit → Settings… → Data Display (Shorten repeating decimals).

5.4 Value Display Modes

When a format is applied to a column (F marker), values can be displayed in three modes:

  • Native - show only the raw stored value (e.g. 0, 1, 54). Traditionally called Value or Code in clinical data work.
  • Formatted - show only the decoded label (e.g. Placebo, <65). Traditionally called Decode.
  • Native and Formatted (default) - show both as native - decode (e.g. 1 - Placebo), with the native value in black and the formatted decode in blue (yellow in the dark theme)

The mode applies globally and is set via Display → Table Values - see Section 6.1 for the menu structure - or from the column header's Table Display ▶ submenu (the same setting).

💡 Display detail: When a value's decode equals the value itself (as in an Identity format), it is shown once, in black, to avoid a redundant X - X display. The F marker is still shown to indicate that a format is applied.

5.5 Column Context Menu

Right-clicking on a column header opens a context menu with column-scoped actions. Many of these functions are also available in the top menu bar (Display, Columns, Sort, Filter, Tools), but the two are not identical: some actions are only in the top menu, some are only in the context menu, and most are in both. The advantage of the context menu is that it applies the action directly to the column you right-clicked on, without an extra column-selection step.

Column context menu - overview Column context menu - overview

Submenu Purpose
Table Display ▶ Display modes for headers, row numbers, and values (see below)
Filter ▶ Filter IN, ≡, ≠ (plus <, ≤, ≥, > on a single numeric cell), Filter Value, Contains, Matches, Edit Filter, Filter Condition, With Unmapped Values, List Unmapped Values …, Remove From Column, Remove Filter ▶, Memorized Filters ▶, Store Table Settings… - see Section 7.5
Sort ▶ Change Sort Order, Sort Ascending / Descending, Append Ascending / Descending, By Group End, Remove from Sort Order, Reset Sort Order, Clear Sort Order - see Section 7.4
Columns ▶ Find Column, Hide / Unhide, Pin / Unpin, Move Column, Reset Column Order, Open Attached Format (greyed when the column has no format) - see Section 7.3
Tools ▶ Statistics ▶ (Create Frequency, Frequency By, Descriptive, Descriptive By), Create Chart…, Merge ▶, Transpose, Compare data sets… - see Section 9
Select in Libraries Select the dataset in the Libraries view (at the bottom of the menu)

Table Display submenu

The Table Display submenu offers the same settings as Display → Table Header / Row Numbers / Table Values - changing it there changes it for all open datasets. The currently active option in each group is marked with a blue dot.

Column context menu - Table Display submenu Column context menu - Table Display submenu

Group Options
Header Show Names · Show Labels · Show Names and Labels (default)
Row Numbers Show Real Row Numbers (default) · Show Display Row Numbers · Show Both Row Numbers
Values Show Native · Show Formatted · Show Native and Formatted (default)

See Section 6.1 for the meaning of each option.

💡 Why both a global menu and a context menu? The Table Display submenu in the column context menu is a quick path to the same options without leaving the data view - useful when you want to flip a display mode without navigating the menu bar.

Open Attached Format

For columns with an F marker (a format applied), Columns ▶ Open Attached Format opens the underlying format as its own tab in the workspace, so you can inspect or compare its code → decode mappings without leaving the dataset.

💡 The same action is also available by right-clicking a variable in the Libraries view - you can inspect the format without opening the dataset first.

Open Attached Format - format opened as a tab next to the dataset Open Attached Format - format opened as a tab next to the dataset

The format tab shows one row per code value, with the standard format columns:

Column Meaning
FMTNAME Format name (prefixed with $ for character formats, in SAS convention)
TYPE Char or Num
START The native (stored) value - e.g. DEVTYPE, SERIAL
LABEL The formatted decode - e.g. "Device Type", "Serial Number"

💡 Use case: when a column shows a code you don't recognize, Open Attached Format reveals the full code list. Comparing the format with the actual data values lets you spot controlled-terminology gaps in either direction - codes defined in the format but not used in the data, or values present in the data but not defined in the format.


6. Display Options

The Display menu controls how data is rendered. Most options are global and apply to all open datasets. The layout, zoom and theme entries are in the Window menu (Section 3.2); they are described here with the other display options.

Group Entries Section
Header & Values Display → Table Header ▶ · Row Numbers ▶ · Table Values ▶ 6.1
Layout Window → Perspective ▶ · Window → Appearance → Tab Placement ▶ 6.2
Toggles Display → Show By Groups · Show Tooltips · Show Validation Findings · Show SQL Pane 6.3
Zoom Window → Appearance → Zoom In · Zoom Out · Reset Zoom 6.5
Theme Window → Appearance → Theme ▶ 6.6

Edit → Settings… → Data Display holds the same header, value and row-number choices and the toggles: the Display and Edit menus and the settings page change the same values. The SQL pane default applies to tables opened later.

6.1 Header & Values

Option Choices
Display → Table Header Show Names · Show Labels · Show Names and Labels (default)
Display → Table Values Show Native · Show Formatted · Show Native and Formatted (default)
Display → Row Numbers Show Real Row Numbers (default) · Show Display Row Numbers · Show Both Row Numbers

Table Header - what to show in the column header: - Name - the variable name as stored in the dataset (often cryptic, e.g. AESEV, RFXSTDTC, BMIBLGR1 - especially in CDISC/SAS data) - Label - the human-readable description (e.g. "Adverse Event Severity", "Date/Time of First Study Treatment") - Names and Labels (default) - show both stacked

Table Values - how to render values in formatted columns (those with an F marker): - Native - the raw stored value (e.g. 0, 1, 54). In clinical data terminology this is also called the Value or Code. - Formatted - the decoded label produced by the applied format (e.g. Placebo, <65). Also called the Decode. - Native and Formatted (default) - show both, with the native value in black and the formatted decode in blue (yellow in the dark theme)

💡 Terminology: Cumba's UI uses "Native / Formatted". The clinical data community traditionally calls the same thing "Value / Decode" or "Code / Decode". They mean the same - see Section 5.4 and the Glossary.

Row numbers explained: - Real Row Numbers - physical position in the stored dataset - Display Row Numbers - position in the current view (renumbered after sort/filter) - Both Row Numbers - shows both side by side

💡 "Real" row numbers can appear non-sequential (e.g. 1, 2, 3, 6, 7, ...) when the displayed order differs from the stored order. This is intentional - for traceability with the underlying file.

6.2 Layout

  • Window → Appearance → Tab Placement ▶ - where the tab strip sits, for all panes (Top / Bottom / Left / Right Placement)
  • Window → Perspective ▶ - preset layouts (Reset to Default; with the AI Agent also Classic (no AI) / Chat Right / Chat Bottom), and Maximize Region / Minimize Region / Restore Regions / Show View List…

See Section 3.1 for full details.

6.3 Toggles

  • Show By Groups - show horizontal separator lines between By-Group groups (also has a toolbar icon)
  • Show Tooltips - globally enable/disable cell and column tooltips
  • Show Validation Findings ⚠️ - highlight validation findings in yellow (errors and warnings from Define-XML, Cumba's built-in checks, or a loaded CDISC CORE / coreJ or Pinnacle 21 report). Also accessible as the yellow triangle in the toolbar.
  • Show SQL Pane (Alt+Shift+Q) - toggle the SQL bar above the dataset table

6.4 The SQL Bar

Every open dataset has a collapsed SQL bar above the data table. It is a key concept of Cumba.

Open the SQL bar (3 ways): - Click the small triangle handle - Drag the bar downwards - the more you pull, the taller it gets - Alt+Shift+Q (Display → Show SQL Pane)

Close the SQL bar (2 ways): - Click the small triangle handle - Alt+Shift+Q again

To have the SQL bar open on every new dataset tab, enable Edit → Settings… → Data Display → Show the SQL pane on new tables.

The SQL editor lets you view and edit the SQL query underlying the current view of the dataset, with syntax highlighting and autocomplete.

SQL bar expanded with the Execute button, the status label and the small triangle handle SQL bar expanded with the Execute button, the status label and the small triangle handle

The Execute button (or Ctrl+Enter) runs the edited SQL and updates the data view. The label next to it shows the editor's state: OK, Edited, Parse error, Not convertible, Not expressible or Execution error.

💡 Architectural note: Cumba uses an integrated SQL engine. Every action that changes the rows or their order (filter, sort) translates to SQL behind the scenes. Column visibility (hide / unhide, pin, reorder) is a display setting and is not part of the query: with columns hidden, the SQL bar still shows SELECT *. When the view uses something standard SQL cannot express (e.g. a case-insensitive sort or a Filter Matches regular expression), the SQL bar is locked and its status reads "Not expressible - …" with the reason, instead of generating misleading SQL. By-Group keys are kept: they appear as the leading ORDER BY columns.

6.5 Zoom - Fully Scalable Interface

Cumba's entire interface scales seamlessly (Window → Appearance):

  • Zoom In - Ctrl+Plus
  • Zoom Out - Ctrl+Minus
  • Reset Zoom - Ctrl+0

All icons and text remain crisp at any zoom level - no pixel artifacts, no blurry icons.

💡 Useful for high-DPI displays, accessibility, presentations, and audit reviews where larger text is preferred.

6.6 Theme

Window → Appearance → Theme ▶ provides the light / dark choice:

Option Icon Meaning
Light ☀️ Bright theme
Dark 🌙 Dark theme
Auto ◐ Follows the operating system's light/dark setting (default); greyed when the system setting cannot be detected

An administrator can lock the mode; the entries are then greyed. The toolbar's Toggle Light / Dark button switches with one click.

Edit → Settings… → Appearance chooses which light and which dark theme are used (default macOS Light / macOS Dark; also Flat, IntelliJ, Darcula, the IntelliJ themes bundled with FlatLaf and the P-300 house themes), an accent colour, the font size, and the placement and layout of the tabs. Picking a theme proposes its partner for the other mode where the names pair (Arc → Arc Dark); the mode chooses which of the two is shown. An accent colour (#RRGGBB) recolours the FlatLaf themes; most IntelliJ themes bring their own colours and ignore it (empty = the theme's own). The font size applies to the screen the window is on; other screens keep their own. Show the toolbar there does the same as Window → Appearance → Show Toolbar. Your own theme files in the folder .cumbaDataBrowser/themes of your home folder are listed last (Your themes); such a file may hold plain values only (colours, numbers, booleans, …), and a file that names a Java class or style is refused.


7. Data Exploration

7.1 Find Text in Data

Ctrl+F (Edit → Find Text) searches the values of the visible columns of the active dataset, raw and decoded. Options: Forward / Backward, All or only the selection, Case Sensitive, Regular Expression, Whole Words. Find jumps to the next match.

📝 Planned: search will also include column labels. Currently values only.

7.2 Find Column

Ctrl+Shift+F (Columns → Find Column, also in the toolbar) - search and jump to a column by typing a fragment of either its name or its label.

CDISC datasets often use cryptic 8-character variable names (AESEV, RFXSTDTC, BMIBLGR1), while the human-readable label is what users actually remember. Find Column lets you search by either. The result list shows matching columns with both name and label; selecting a result jumps directly to that column.

💡 Tip: combine with Ctrl+Shift+P (Pin Selected Columns) to keep a found column visible while scrolling horizontally.

7.3 Column Management

The Columns menu provides full control over which columns are visible and in what order.

Action Shortcut
Find Column Ctrl+Shift+F
Hide / Unhide Columns (manager dialog) Ctrl+Shift+C
Hide Selected Columns Ctrl+Shift+H
Hide Not Selected Columns Ctrl+Shift+K
Show All Columns Ctrl+Shift+A
Pin Selected Columns (freeze) Ctrl+Shift+P
Unpin Selected Columns Ctrl+Shift+U
Unpin All Columns –
Move Column Left / Right (right-click → Columns) Ctrl+Alt+Left / Ctrl+Alt+Right
Move Column to Start / to End (right-click → Columns) Ctrl+Alt+Shift+Left / Ctrl+Alt+Shift+Right
Reset Column Order Ctrl+Shift+O

Drag & drop column headers to reorder columns visually. The Move Column commands do the same from the keyboard - useful when the target position is far off screen. A scattered selection is first gathered into one block, then moved as a block; at the pinned/scrollable boundary, Move Left pins the block and Move Right unpins it.

Pinning keeps columns fixed (typically on the left) while you scroll horizontally through the rest of the dataset. A vertical separator marks the boundary between pinned and scrollable columns; dragging a column header across it pins or unpins the column. Sorting and selection work normally on pinned columns.

📝 Known limitation: dragging a multi-column selection currently moves only the first of the selected columns. Use the Move Column commands for a whole block until this is fixed.

7.3.1 Hide / Unhide Columns Dialog (Ctrl+Shift+C)

A two-list dialog (Select Visible Columns) to manage column visibility and order in one place:

  • Left list: hidden columns (with a search field for long lists)
  • Right list: visible columns, in display order

Move buttons (between lists): - « / » - move all to hidden / all to visible - < / > - move selection to hidden / to visible

Order buttons (right side): - ⤒ / ⤓ - move selection to top / bottom of visible list - ↑ / ↓ - move selection up / down by one - 🔄 - restore the original (dataset) order of the visible list (Ctrl+O)

7.4 Sorting

Sort context menu - Sort Ascending/Descending, Append, Change Sort Order, Reset and Clear Sort Order Sort context menu - Sort Ascending/Descending, Append, Change Sort Order, Reset and Clear Sort Order

Action Shortcut
Sort Ascending Ctrl+Alt+Up
Sort Descending Ctrl+Alt+Down
Append Ascending (multi-sort) Ctrl+Alt+Shift+Up
Append Descending (multi-sort) Ctrl+Alt+Shift+Down
Change Sort Order (dialog) Ctrl+Alt+S
By Group End Ctrl+Shift+G
Reset Sort Order Ctrl+Shift+R
Clear Sort Order Ctrl+Shift+E
Remove from Sort Order (right-click → Sort) –

Sort indicators in the column header: - 🟢 Green arrow → sorted (number = sort priority for multi-sort) - 🟢 Green arrow with circle (ball) → By-Group sorted

When By-Group is active and Display → Show By Groups is on, horizontal lines visually separate the groups.

Reset vs. Clear: - Reset Sort Order (Ctrl+Shift+R) - restore the stored sort order defined per dataset (CDISC datasets often carry a canonical sort like USUBJID + AESEQ) - Clear Sort Order (Ctrl+Shift+E) - remove all sorting

7.4.1 Change Sort Order Dialog (Ctrl+Alt+S)

Full control over multi-column sorting. Each entry has three options:

Option Description
Ascending Sort direction (✓ = ascending, ✗ = descending)
Case Sensitive Whether character sorting respects upper/lower case
By Group Treat this column as a By-Group level

Reorder/manage: ⬆️ / ⬇️ to change priority, ➕ / ➖ to add/remove, 🔄 to revert to the stored sort order.

💡 Typical pattern: set the outer column (e.g. USUBJID) as By Group, and use the remaining columns for sub-sorting within each group.

7.5 Filtering

Filtering is a core activity. Filters are accessed via the Filter menu, the right-click context menu, the toolbar, or keyboard shortcuts.

Memorize Filter dialog - save the active filter under a name for reuse Memorize Filter dialog - save the active filter under a name for reuse

7.5.1 Quick Filtering by Cell Value

The three most-used filters work directly on the selected cell(s) - no dialog, no menu navigation:

Shortcut Effect
Ctrl+Alt+E Keep only rows where the column equals the selected value
Ctrl+Alt+N Remove all rows where the column equals the selected value
Ctrl+Alt+I Open a pick list to choose multiple values

💡 Click a cell, press the shortcut, done. With these three memorized, most everyday filtering is one keypress away.

7.5.2 All Filter Types

Filter Shortcut Description
Filter IN Ctrl+Alt+I Pick list - select multiple values to keep
Filter ≡ Ctrl+Alt+E Equal to selected cell value(s) - select multiple cells first to filter for all of them at once
Filter ≠ Ctrl+Alt+N Not equal to selected cell value(s) - works with multi-selection as well
Filter Value Ctrl+Alt+V Filter by a specific single value (dialog)
Filter Contains Ctrl+Alt+C Substring match (case-insensitive), character columns
Filter Matches Ctrl+Alt+M Regex pattern match (with Case insensitive and Dot matches newline options), character columns
Filter Condition – Type a condition as text (comparisons, IN, AND/OR with parentheses); it is checked as you type, Ctrl+Enter applies

💡 Filter on multiple values at once: select several cells in a column (Ctrl-click or Shift-click), then apply Filter ≡ - Cumba keeps all rows matching any of the selected values. The same works with Filter ≠ to exclude all of them in one step. The selection may span at most 10 rows; if it covers several columns, each row contributes the combination of its values (A = a AND B = b), and the rows are combined with OR.

7.5.3 Context-Sensitive Filters on Numeric Cells

The right-click filter menu adapts to the column type. On a single numeric cell (of a column without a code list), four additional comparison filters appear with the current cell value pre-filled:

  • < value, ≤ value, ≥ value, > value

Example: right-clicking 69 in AGE offers AGE < 69, AGE ≤ 69, AGE ≥ 69, AGE > 69 as one-click filters.

With two numeric cells of the same row selected, the menu also offers column-to-column comparisons (<, ≤, ≡, ≠, ≥, >), e.g. ADY ≥ TRTSDY.

7.5.4 Filter IN - Pick List Dialog

The Filter IN dialog (Ctrl+Alt+I) shows all unique values of the selected column with: - A search field for long lists - A value table with columns: Value (with decoded label if applicable) · # (count) · % (share) - Sortable by any column - A Negated checkbox to invert the selection - A status bar showing total unique values and total rows

7.5.5 Filter Matches - Regex Dialog

The Filter Matches dialog (Ctrl+Alt+M) takes a regular expression with options: - Case insensitive - ignore upper/lower case - Dot matches newline - allow . to match line breaks

Example patterns: ^Placebo, dose$, \d{3}.

7.5.6 Edit Filter - Filter Builder

The Edit Filter dialog opens a tree-based filter builder: - Add Condition - enter a condition as text (AND / OR, parentheses for nesting) - Edit Condition - pick values for =, ≠, IN conditions, otherwise edit the text - Edit as Text / Remove Condition - drag conditions from the list on the left - the filters of the other open datasets and your memorized filters - into the filter

When you edit a condition by picking values, the list shows the values that occur under the conditions that always apply together with it - its AND siblings, not its OR siblings. A negated group is shown as NOT AND / NOT OR and is saved with its NOT.

7.5.7 Memorized Filters

Filter sets can be saved and reused later. Useful for recurring filter patterns (e.g. "only Subject A", "only treatment-emergent AEs", "only baseline visits").

Access via the right-click context menu → Filter → Memorized Filters ▶:

  • Memorize Current Filter… - save the active filter under a name
  • [saved filter names] - click a saved filter to apply it
  • Delete Memorized Filter ▶ - submenu to remove saved filters

Memorize Current Filter… is offered only while the dataset has an active filter.

Memorized filters are not tied to a dataset: every memorized filter is offered in every dataset, and they are persistent across sessions - they remain saved after you close and restart Cumba. Rename, edit or delete them under Edit → Settings… → Filters → Memorized Filters. Edit… opens the filter's condition in the condition editor against an open dataset that has every variable the filter names (with several such datasets, you pick one); without one the button is greyed.

Applying a memorized filter adapts it to the current dataset: - the parts whose variables exist in the dataset (and whose comparisons fit the variables' types) are applied, combined (AND) with the dataset's existing filter; - the parts that do not fit - e.g. a variable the dataset does not have - are dropped, and a notification names what was dropped; - when no part fits, the filter is not applied and the status bar says why.

This makes patient-centric review very efficient - define "Patient 1111" (USUBJID = "1111") once in AE, then one-click apply it in EG, LB, VS, and every other domain that has the subject identifier.

💡 Memorized filters are particularly useful for repetitive review workflows - define your standard filter once, recall it with a click in every dataset that has its variables.

📝 Planned: apply a memorized filter to all open datasets in a Library at once - currently it has to be applied per dataset.

7.5.8 Managing Filters

  • Edit Filter - open the Filter Builder for the active filter set
  • Remove Filter ▶ - submenu listing active filters individually
  • Remove From Column - remove all filters on the currently selected column
  • Clear Filter (Ctrl+Alt+R) - reset all filters

7.5.9 Special Filter Menu Entries

  • With Issues - keep only rows containing validation findings (yellow-highlighted). Requires loaded validation findings (Define-XML, the coreJ check, or a loaded validation report). See Quality & Validation.
  • With Unmapped Values (right-click → Filter) - on a column with an attached format, keep only rows whose value the format does not map (blank and missing values are not shown). Quick way to drill into codelist gaps after a pink-red F marker draws your attention. List Unmapped Values … lists the distinct unmapped values instead.
  • Go To Row - jump directly to a specific row number (navigation, not a filter), counted in display rows or in the dataset's real row numbers. Useful when a colleague or validator references a specific row by number.

7.5.10 Stored Table Settings

Filter → Store Table Settings… saves the dataset's filter, sort order and column layout (order, hidden, pinned) and applies them whenever the dataset is opened again. Store them for this dataset, for every dataset of its library, or globally (beyond a single dataset only the filter); optionally ask before applying. Remove them from the tab's context menu (Remove Stored Settings for this Table) or under Edit → Settings… → Filters → Stored Table Settings.


8. Data Transformation

8.1 Merge

Tools → Merge submenu open over a Japanese AE - generic Merge data set plus the CDISC quick merges (Merge DM highlighted) Tools → Merge submenu open over a Japanese AE - generic Merge data set plus the CDISC quick merges (Merge DM highlighted)

The Tools → Merge submenu provides both generic and CDISC-specific merge operations (also reachable via the right-click context menu on a dataset):

Generic: - Merge data set… - open a merge dialog to combine the active dataset with any other by user-defined key variables.

CDISC quick merges: - Merge DM - join with the Demographics dataset - Merge ADSL - join with the Subject-Level Analysis Dataset - Merge SUPP - join with Supplemental Qualifiers - Merge SUPPDM - join with Supplemental Qualifiers for Demographics - Merge RELREC… - choose relationships from the study's RELREC dataset, which links records across domains (e.g. an adverse event to the concomitant medication given for it), and merge the related domains' columns

💡 The quick merges look up DM / ADSL / SUPP-- / SUPPDM / RELREC in the same library. DM, ADSL and SUPPDM join on STUDYID + USUBJID, SUPP-- also on DOMAIN. RELREC needs STUDYID, DOMAIN and a subject identifier (USUBJID, APID, POOLID or SPDEVID) and links the records through the relationships you choose. An entry is greyed when the active dataset lacks these columns. The merged columns are added to the current tab.

💡 RELREC is the one that is hard to do by hand: it describes relationships between records in different domains rather than adding columns from one known dataset, so the join keys differ from row to row. The quick merge resolves them for you.

After a merge, the merged-in columns are shown with a blue-tinted column header so you can visually distinguish them from columns that are native to the dataset.

8.2 Compare Datasets

Tools → Compare data sets… - compare the active dataset against another, by structure and content.

⚠️ Known limitation: when the two datasets come from different storage formats, numeric columns may be falsely reported as a length change, because formats store numeric width differently. This is a comparison artefact, not a real difference - disregard numeric length-only diffs across formats.

Select the dataset to compare with from one of four sources (tabs):

Source Description
Open Tables Any dataset currently open in the workspace. An asterisk (e.g. ADAE *) marks a dataset opened in the editor, so you can compare an edited version against its original.
Library Tables A dataset from an attached library.
Local File A dataset file from disk.
URI A dataset referenced by URI.

Options:

Option Description
Match rows by key columns When on, rows are paired up by their key values before comparing (so a reordered or partially overlapping dataset still compares correctly). When off, rows are compared position by position.
Key columns The variable(s) used to match rows (e.g. USUBJID, AESEQ). Only used when Match rows by key columns is on.
Numeric tolerance Empty (default): values are compared after rounding to 12 significant digits, so tiny floating-point noise is ignored. 0: the raw values must match exactly. A positive number: values count as equal when their absolute difference is within it.

The comparison reports differences in structure (columns, types, attributes) and in values.

A column whose type changed is still compared value by value, and its header is highlighted in the result, so the type change stays visible while you read the values.

A column whose source (native) type changed while its internal type did not - e.g. integer in one Dataset-JSON file and float in the other, both read as numbers - is tinted, and its tooltip says Native type changed: integer → float (old → new). Native types are compared only when both datasets come from the same source format: a Dataset-JSON file against an XPT file never shows this mark, nor does a database table or a hand-written .cdt.

Direction: the active dataset (the one you start from) is treated as the new version; you compare it against an older one. Reported changes therefore show what changed from the old to the new.

Viewing changes: differences are shown in a tooltip, in old → new form. For example:

Length: -1 → 8
Label: "Actual Treatment (NNN…" → "Actual Treatment (N)"

The result opens as its own tab (Compare: A vs B) with a summary and navigation:

Element Description
Summary Row counts shown top-right, labelled Rows: equal (unchanged), modified (changed), only in A and only in B (rows present in just one dataset). Columns present in only one dataset are marked in the column headers, not counted here.
Show differences only Toggle to hide all equal rows and show only the differences.
Previous / Next difference Jump between the differing rows.

Like other result tabs, the compare result behaves as a regular dataset (filter, sort, SQL).

💡 Compare against an edited version: open a dataset, make changes (it shows as name *), then compare it against the original to see exactly what changed before exporting.

8.3 Transpose

Tools → Transpose opens the Transpose dialog to convert long-format data to wide-format. Optimized for ADaM BDS workflows.

Field Description
By Columns Identifying variables that remain as keys (e.g. USUBJID, STUDYID). Multi-select. Optional: with none, the whole dataset becomes one row (as SAS PROC TRANSPOSE without BY).
Transpose Key The variable whose values become new column names (e.g. LBTESTCD)
Label Variable providing the labels for the new columns (e.g. LBTEST)
Primary Value The main value to populate the new columns (e.g. LBSTRESN)
Secondary Values Optional additional values (e.g. unit, flag) carried alongside

Type icons in each field show whether the selected variable is numeric (12) or character (AB).

💡 Why transpose? BDS is the standard ADaM structure for many endpoints, but its long-format layout is not usable for graphs - charting tools expect each parameter as its own column. In BDS, parameters are stacked vertically (PARAM + AVAL); to plot Albumin vs. ALT, you need each as a separate column. Cumba's transpose bridges this gap.

8.4 SQL Query

Tools → SQL Query… (Ctrl+Alt+Q) - open the integrated SQL editor for free-form queries against loaded datasets.

Library-level SQL is also available via right-click on a Library → SQL Query….

The editor sees every open library at once. A query is not confined to one dataset or even one study - you can join ADSL from one library against a lab dataset from another, across file formats, in a single statement. Unqualified names refer to the workbench's own library; other open libraries are addressed as library.dataset. Code completion (Ctrl+Space) proposes the datasets, columns and values that are actually loaded; Ctrl+Enter runs the query.

💡 Columns are decoded with their own library's formats. In a cross-library query, a column taken directly from a sibling study is decoded through that study's code lists, not the primary study's. For computed columns (expressions, aggregates, UNION and some sub-queries) Cumba cannot always tell which library a value came from; such a column is matched by name, primary library first, so check its decode before relying on it.

See also the SQL Bar for inline SQL editing per dataset.

8.5 Editing & Export

Cumba is a browser - datasets are read, not changed in place. There is no in-place save; edits are written out via Export to a new file, leaving the original untouched.

Workflow: 1. Open a dataset for editing: right-click it in the Libraries view → Edit. 2. Change values / rows as needed. A dataset opened for editing shows an asterisk in its tab (name *). Editing commands: Add Row (Shift+Insert), Mark Row(s) as Deleted / Undelete (Shift+Delete; deleted rows are left out of the export), Add Column… and, on a column header, Edit column…. Ctrl+Z / Ctrl+Y undo and redo. 3. Export the edited dataset to a new file (File → Export). The original file is never modified.

Closing a dataset whose edits were not exported - its tab, its window or the application - asks Export… / Discard / Cancel, once per dataset; Cancel keeps it open and stops the exit. Edits undone back to none ask nothing; an export that left out hidden columns does not count as exported.

Export writes CSV, Excel (XLSX), SAS XPT, SAS7BDAT, Dataset-JSON (.json, .ndjson, .dsjc), Parquet, R (.rds, .rda / .RData) and CDT.

Export Properties dialog - shown when the chosen format has options; the fields depend on the format. For Dataset-JSON:

Field Description
Pretty Print Indented, human-readable output (.json only).
Source System Name The originating system recorded in the exported file's metadata. Default: CumbaDataBrowser.
Source System Version The version recorded alongside the source system name. Default: 1.0.

📝 Other formats have their own fields (e.g. CSV delimiters and quoting, XLSX Freeze Header Row, Parquet Batch Size, a File Label for XPT and SAS7BDAT). XPT and SAS7BDAT exports have a Charset field, and they refuse - before writing anything - a value, a name, a label or a display format the chosen charset cannot hold, and say which (for a value: its column and row). With Charset blank, an XPT export uses the dataset's own charset when it is ASCII-compatible, else US-ASCII; appending to an existing XPT uses US-ASCII unless a charset is set. A SAS7BDAT export defaults to UTF-8, and its Compression field offers None / Char / Binary: Char suits character-heavy data, Binary numeric-heavy data, and SAS reads both (verified with SAS 9.4); the default (None) writes an uncompressed file. A CSV export also refuses, naming row, column and character, a value its Charset cannot encode.

💡 Because export always writes a new file, the source data stays intact - consistent with Cumba's principle that your data is read, never changed.


9. Analytics

9.1 Statistics

Tools → Statistics ▶ provides the four most common statistical operations in clinical data work:

Action Shortcut Description
Create Frequency Ctrl+Alt+F Frequency table (counts and percentages) for the selected variable(s) - several columns give the frequency of their combinations
Create Frequency By – Frequency table per BY group (you choose one or more BY variables, e.g. AESEV by TRTA)
Create Descriptive Ctrl+Alt+D Descriptive statistics for the selected numeric variable(s), one row per variable
Create Descriptive By – Descriptive statistics per BY group (e.g. AGE by SEX)

9.1.1 Descriptive Statistics Output

Tools → Statistics → Create Descriptive (Ctrl+Alt+D) computes a comprehensive table of measures per variable:

Counts: COUNT, COUNT_MISSING, COUNT_NOT_MISSING Range: MIN, MAX, RANGE, SUM Centrality: MEAN_ARITHMETIC, MEAN_GEOMETRIC, MEAN_HARMONIC, MEDIAN Quantiles: PERCENTIL_5, Q1 (25%), Q3 (75%), PERCENTIL_95 Spread: STD_DEVIATION (arithmetic/geometric × sample/population), VARIANCE (sample/population)

💡 The output is intentionally complete. Most clinical use cases only need a subset (typically N, Mean, SD, Min, Median, Max). Use Ctrl+Shift+H to hide unwanted columns, or the Hide/Unhide dialog (Ctrl+Shift+C) to build a custom view of the metrics you need.

9.1.2 Statistics Output as Datasets

Statistics output as tabs - Frequency and Descriptive results open as their own datasets (e.g. Freq(DM[…]), Descr(ADAE[…])) Statistics output as tabs - Frequency and Descriptive results open as their own datasets (e.g. Freq(DM[…]), Descr(ADAE[…]))

Statistics output (Frequency / Descriptive) opens as its own tab in the Workspace, named with the source dataset and selected variables (e.g. Freq(AE[AESEV])).

💡 The result tab behaves like a regular dataset - you can filter, sort, hide columns, or even transpose it further. Statistics outputs are first-class data in Cumba.

9.2 Charts

Tools → Create Chart… opens the Select Chart Type dialog - a visual picker showing all available chart types with previews and descriptions.

Select Chart Type dialog - visual gallery of the available chart types Select Chart Type dialog - visual gallery of the available chart types

Available chart types (17):

Distribution & Comparison: - Box Plot - distribution of one or more numeric columns; "By Group" splits into subgroups - Heat Map - color-coded matrix - Frequency Bar Chart - counts per category - Pie Chart - proportions - Radar Chart - multi-dimensional comparison - Waterfall Chart - cumulative effect of sequential positive and negative changes (one label column, one change column)

Statistical Summary: - Dot Plot (Mean ± CI) - means with confidence intervals - Forest Plot - pre-computed effect estimates (e.g. hazard ratios) with confidence intervals per subgroup

Relationships & Correlations: - Scatter Plot - two-variable correlation - Bubble Chart - three-variable relationship (x, y, size)

Time-Course & Profiles: - Line Plot - trends over time - Spaghetti Plot - individual subject profiles over time - Shift Plot - baseline vs. post-baseline, with a y = x reference line - Stick Chart - values as vertical sticks (lollipop chart) - OHLC Chart - Open/High/Low/Close-style range display

Clinical Specific: - Kaplan-Meier Plot - survival curves (time column such as AVAL, censor indicator such as CNSR) - Swimmer Plot - patient timelines (oncology)

Data Set / Filter: The chart view shows the Data Set it draws (<library>.<member> or the file's URI; the tooltip always shows the URI) and its Filter. Change… on the data set opens the same table picker as Merge and Compare: selected variables the new data set has are kept, the others are dropped and named, and the parts of the filter the new data set can evaluate are carried over. Change… on the filter opens the condition editor. The chart keeps its own copy: later filter changes in the table do not move it.

Theme: Default (follows UI) uses Settings ▸ Charts ▸ Chart theme (light / dark UI) and switches with the UI; picking a theme pins it. Right-click the chart for Export Chart… (PNG/JPG/BMP/GIF, size, theme; default Settings ▸ Charts ▸ Export theme), Export Data… (XY charts: one CSV per series) and Print….

Your own chart themes go into .cumbaDataBrowser/chart-themes in your home folder; they are listed after the shipped and the administrator's chart themes.

💡 Cumba's chart library is heavily clinical-focused - Spaghetti, Shift, Swimmer, Kaplan-Meier and Forest plots are all included as built-in chart types, reducing the need for custom R/SAS scripting.


10. Quality & Validation

Cumba integrates dataset validation directly into the data exploration view. Findings are integrated into the data view and visible at every level - Library, dataset, column, row, and cell.

Supported validation sources: - coreJ - the built-in validation engine (see Section 10.7 for datasets, Section 10.8 for a Define-XML document, and Section 11.2) - Validation reports - Pinnacle 21 Excel and CDISC CORE / coreJ JSON or Excel reports, loaded with Add Validation Report (see Section 10.6) - Define-XML - findings carried in the Define are read directly when the Define is loaded

10.1 Multi-Level Validation Visibility

When a Define-XML carrying findings is loaded, or an external validation report is added, findings are made visible at four levels:

Level Indicator
Library tree ⚠️ next to dataset icons that have findings
Column headers ⚠️ next to other column markers (N, F, sort arrow, funnel)
Row numbers ⚠️ next to row numbers for affected rows
Cells Yellow background highlight on affected values

💡 This consistent multi-level marking lets you spot issues at any zoom level - from "which datasets have issues" (Library) down to "which exact cell has an issue" (cell highlighting).

10.2 Toggling Validation Highlights

The yellow highlights and column markers can be turned on/off: - Toolbar: ⚠️ Yellow Triangle - Menu: Display → Show Validation Findings

💡 Yellow = a finding (Warning or Error). Toggle off when you want to work without the highlights.

10.3 Validation Information in Tooltips

Hovering on a column or cell shows finding details in the tooltip:

  • Finding: the rule id (e.g. SD1201), then in brackets the kind and severity (e.g. RuleViolation - Error; NA when the report states no severity, e.g. an empty Severity cell in a Pinnacle 21 report, and every finding imported from a CDISC CORE or coreJ report), followed by the executability and the validator name (e.g. pinnacle21) when the report carries them
  • Message: human-readable description
  • Row: for a single affected row, the row number and the values of the variables the finding names
  • Rows: for several rows, the affected row numbers, a run of consecutive rows as one range (e.g. 7-9), ten entries per line and at most 20 - then "… and N more rows"; the Findings tab lists them all

💡 The Rows list lets you see at a glance how widespread an issue is - 1 row vs. 30 rows vs. all rows.

10.4 Filtering to Findings Only

Filter → With Issues - keep only rows that have validation findings. Useful for systematic review.

Show Validation Report and Add Validation Report are also in the Tools menu; Show Validation Report is on a dataset's context menu too.

10.5 Validation Report as a Dataset

Right-click on a Library → Show Validation Report opens the library's attached validation report as a report view in the Workspace. It opens whenever a report is attached - a clean run with 0 findings opens too (its Rules and Data sets tabs still show what was checked). If a report view of the library is already open, it is focused instead.

A link above the tabs names the library (click it to jump to the library). The view has four tabs; Findings is selected when it opens:

Tab Shows
Overview The run information the report carries - engine and version, run date, runtime, standard / version, CT packages, Define-XML version, use case, issue limits - then every other run property as written, the reader's notes, and one line per part the format does not report (e.g. "This format does not report skipped rules.")
Rules One row per rule: Rule Id, Status (FINDINGS, NO_FINDINGS, SKIPPED, ERROR, UNKNOWN), the status as the report wrote it, severity, category, message, description, CDISC / FDA / PMDA / other ids, finding count, the data sets with findings, executed / skipped / errored counts, skip reasons, error, runtime, version
Data sets One row per data set: name, file, label, class, path, modified, records, columns, size, findings, rules executed / total, errors, rejects, runtime
Findings The flattened findings, one row per finding and affected record (columns below)

A tab whose part the report does not carry is disabled; its tooltip gives the reason. Connected to a remote server of an older release, only the Findings tab is available.

Findings columns: - domain - CDISC domain (e.g. AE, TV, QS) - fileName - affected file - source - validator name (e.g. pinnacle21, core) - ruleId - exact rule identifier (e.g. SD1082, CT2002) - severity - Warning, Error, etc.; NA when the report states no severity - kind - finding type (e.g. RuleViolation) - rule_type - additional categorization - scope - Variable or Record level - executability - whether the rule could be executed - message - human-readable description - row_index - the affected record; variables / values - the variables the finding names and their values

Moving between the tabs: - Double-click a rule on the Rules tab → the Findings tab opens, filtered to that rule. The rule filter replaces any filter you had set on the Findings tab (with the finding review on, it combines with the review bar's filters, see Section 10.9); the yellow highlights in the library's open data sets follow it. - Double-click a data set on the Data sets tab → the data set opens (or its open tab is focused). - Both work from a report view torn off into its own window too; the data set opens in the main window.

Re-running a check: when a new report is attached to the library - a re-run coreJ or Define-XML check, or Add Validation Report - an open report view of the previous run is closed, and the status bar says so. Show the report again to see the new run.

Report formats (✔ = the format carries the part; a file without that section leaves its tab disabled):

Format Overview Rules Data sets Findings
Internal coreJ / Define-XML check ✔ ✔ ✔ ✔
coreJ / CDISC CORE JSON (v1) and coreJ v2 JSON ✔ ✔ ✔ ✔
CORE / coreJ Excel (.xlsx) ✔ ✔ ✔ ✔ (capped, see below)
Pinnacle 21 Excel (.xlsx) ✔ ✔ (without a Rules sheet: only the rules with findings) ✔ ✔ (capped per issue)

Pinnacle 21 CSV reports are not supported. The two Excel formats are told apart by their sheet names.

Truncated findings: the engines cap the number of rows written to an Excel report's issue details (and a v1 JSON report may be capped the same way). The finding counts on the Rules and Data sets tabs then come from the report's Issue Summary, which counts every issue, and the Overview says the Findings table is incomplete - e.g. "The findings table is incomplete: the report's Issue Details list 10000 of the 33574 issues its Issue Summary counts …". A coreJ v2 JSON report is never capped: its counts come from its findings.

💡 Every tab except Overview is itself a dataset, so you can apply all of Cumba's data tools to it: filter the Findings to Errors only, sort the Rules by finding count, run Frequencies to see which rules are violated most, build charts of finding distribution, or export as CSV/Parquet/etc.

10.6 Adding a Validation Report

Right-click on a Library → Add Validation Report loads an external validation report (Pinnacle 21 Excel, CDISC CORE / coreJ JSON or Excel - see the formats in Section 10.5) and overlays its findings onto the loaded datasets. An open report view of the library's previous report is closed.

10.7 Check Using coreJ

Check Using coreJ … runs the built-in coreJ validation engine on a library. It is offered in three places:

  • the library context menu in the Libraries view,
  • the dataset context menu in the Libraries view - this runs the check on the library the dataset belongs to,
  • the global Tools menu (Tools → Check Using coreJ …), for the library selected in the Libraries view.

The two checks - Check Using coreJ … and Validate Define-XML - come with the coreJ extension, listed under Edit → Settings… → Extensions. They appear only when the data manager Cumba runs on offers them: the shipped installation runs the coreJ manager, which does. An installation configured for the basic data manager (or connected to a server without the checks) hides both entries, and the coreJ row of the Extensions page says why; everything else - opening data, validation reports, Define-XML generation, the metadata store and the dictionaries - works the same. An administrator can also switch the extension off for every user.

💡 The check always works on a library. Many validation rules are cross-domain (e.g. checking that every USUBJID in AE also exists in DM), which only makes sense on the full set of datasets in a library. To validate only some datasets, narrow Use Data Sets on the Data tab.

Cumba ships no CDISC metadata. Checking against CDISC means comparing your data with the standards and the controlled terminology, and neither is part of the download. You supply them in the local CDISC metadata store, which the check reads (a validation run does not call the CDISC Library API). You seed it - from the public rules-engine repository, a local copy or the CDISC Library API - on one page, Edit → Settings… → Validation → Metadata Store:

  • Store file - the one zip with the CDISC standards and controlled terminology that validation reads, so validation metadata resolves offline without an API key (default ~/.cumbaDataBrowser/metadata-cache.zip; Browse… picks another). It is saved with the settings; a seed writes into it. The line under it says what the store holds: Seeded: file name, size and time, followed by where the latest seed came from - the repository and tag, the local folder or the CDISC Library. Its tooltip lists every seed source the store records.
  • Seed from - where the seed reads the standards and the controlled terminology:
  • GitHub - the public CDISC rules engine repository's resources/cache. Repository offers https://github.com/cdisc-org/cdisc-rules-engine (the default) and a public fork; you may type another one: https only, without a ?… query, a #… fragment or a user name (the seed stays unavailable, with the reason, until the address is usable); a clone address ending in .git is fine. Tag or branch starts with the pin Cumba was tested with; when you open the list it fills with the repository's tags, newest first (rc10 before rc9; a tag whose name cannot be part of a download address is not offered). Type a branch by hand. Changing the repository clears the tag, and the newest tag of the new repository fills in when the list arrives, unless you typed one meanwhile; a repository typed without pressing Enter is taken over when you press Seed…, which then asks for its tag first. If the tags cannot be listed
    • the address is no git repository, or no answer came within 20 seconds - the list's tooltip says why: type a tag that exists in that repository. No key, no account. The download is about 82 MB and needs about 420 MB on disk while it runs. There is no progress display, and a download in progress cannot be stopped: Abort takes effect only after the download, but before the store is replaced. An existing store is only ever replaced whole, never left partial.
  • Local pkl cache - for a machine without internet access: a Folder holding a copy of the repository's resources/cache folder.
  • CDISC Library - seeds the same store from the CDISC Library web API with your own API key. Type or paste the key into API key. The key is used for that one seed only: it is never saved, never logged and never sent by a validation run. If -Dcdisc.library.api.key or the environment variable CDISC_API_KEY is set, the field starts with that key (masked); you can overwrite it. Library URL starts with the configured base URL (default https://api.library.cdisc.org/api/); it must be https. You may change it for one seed, unless -Dcdisc.library.api.url (also the cdisc.library.api.url entry of databrowser.conf) or CDISC_API_URL sets it, or an administrator locked it: then it is read-only and its tooltip says why. Every request goes to the Library (nothing is cached), so a seed always reads the current content: about 860 requests the first time or with Refresh everything, about 50 on a re-seed, which carries the controlled-terminology packages the store already holds. A key the Library refuses is reported as such and leaves the store untouched. A key holding anything but visible ASCII characters - an invisible character copied along with it, say - is refused before anything is sent, naming the character and its position.
  • Refresh everything - without it, content the existing store already holds is carried forward instead of fetched again: re-running never silently rewrites content a run already validated against.
  • Dry run - resolves and reports exactly as a real run, but leaves the store untouched. The download (or the Library requests) still happen.
  • Seed… runs the seed. The seed inputs (source, repository, tag, folder, URL, key) are not settings: they are not saved and do not make the page wait for Save. A changed Store file or Codetables folder must be saved first. Seeding, from any source, needs the CDISC Library licence feature.

An API seed holds the corrected current Library content; a seed from the rules-engine repository holds the corrected content of the tag it was seeded from. The two have not yet been compared on live data, so differences between them are possible. When you switch a store from one source to the other, tick Refresh everything: otherwise the store keeps the other source's controlled-terminology packages and products next to the new ones.

When the page is opened from a coreJ check that used a store other than the saved Store file, it names that store and offers Use this store, which puts it into the field.

Without a seeded store, the rules that need CDISC metadata are skipped.

Codetables folder. Some rules check a test's result or unit against the CDISC Codetable Mapping Files - the spreadsheets in which CDISC states which codelist terms go with which test code (e.g. DD_Codetable_Mapping_2023-06-30.xlsx). CDISC publishes them separately from the standards, so the seed cannot fetch them: download them from CDISC yourself and put them in one folder, keeping the earlier editions (a check uses only the editions dated on or before the controlled terminology it runs with). Then open Edit → Settings… → Validation → Metadata Store, name that folder as the Codetables folder, click Save, then Seed…. Every seed reads the recognised files into the store; a blank folder keeps the store's codetables (Refresh everything drops them). The page's Codetables: line says what the store holds. Until the store is seeded with the codetables, these rules are reported as skipped, with the reason - never as passed. When the configured folder and the store disagree, Cumba says so once at start.

📝 The store is machine-scoped and must sit where the validation engine runs. A library opened through a remote manager uses the store on that server, and Cumba says so rather than seeding the wrong machine - from either source. The server's administrator seeds it there, for example by copying a seeded store to the server's store location.

External dictionaries are a separate matter. MedDRA, WHODrug, SNOMED CT, LOINC, UNII, MED-RT, neoplasm and HGNC (the human gene symbols) are external sources that Cumba does not ship either. Edit → Settings… → Validation → CDISC Dictionaries installs the ones this machine validates against; Section 11.4 lists the files each one expects.

Name each dataset by its CDISC domain code. A rule selects its datasets by domain, and a dataset without a DOMAIN column (common in a CDASH collection export) is known by its name: call it AE, not AE_EXPORT. The coreJ command-line tool declares the domain otherwise with --dataset-domain NAME=DOMAIN.

Quick start: the dialog pre-selects the rule packages that match the standard and version the library's metadata declares - its Define-XML when you opened the Define-XML as the library (Section 11.1). A define.xml that only sits in a data folder is read as a format catalog (Section 4.4) and declares no standard to the check. Check the selection and click OK. When nothing is declared, no package is selected; when a standard and version are declared but the installed rule corpus has no package for them, the dialog says so in one line (e.g. "The attached metadata declares SDTMIG 3.3; the installed rule corpus has no package for it — choose one."). Either way OK stays disabled until you choose a package under Rule Packages. The values you set are remembered per library and offered again the next time.

Defaults: Edit → Settings… → Validation → coreJ Check sets the values a library starts with the first time you check it: the Rules Directory, the Default Rule Families and the three Advanced values. A library you checked before keeps its own remembered values. Clearing the coreJ check history (Edit → Settings… → General → History → coreJ Checks, Clear, then Save) starts every library from the defaults again: it removes the remembered values of all libraries, not of one. The default rule families (CDISC, FDA, PMDA, COREJ) select those families' packages for the standard and version the library's metadata declares - FDA and COREJ on an SDTMIG 3.4 library select the FDA and the coreJ package for SDTMIG 3.4 - and never hide a package from the picker. The default rule families need a declared standard: a library that declares none, or a standard only the coreJ family covers, still needs a hand pick. When the families you chose have no package for the declared standard, Rule Packages opens empty with a note saying so. No family ticked means the built-in selection. On a remote connection the server's rules directory is used: the Rules Directory default is greyed out there and not applied. An administrator can lock these defaults; a lock fixes what a new library starts with, not the values of a run.

The dialog has three tabs and a collapsed Advanced section below them:

Rules - what to run

Field Purpose
Rules Directory The rule corpus to use. Pre-filled with the rule packages installed with the application; point it at another corpus to run that one instead.
Rule Packages The rule packages to run (e.g. CDISC and FDA rules for one SDTMIG version). Each package names the standard and version it validates against, so there is no separate standard / version field. Several packages can be combined.
Extra Rule Files Additional rule package files, always added on top of the selected packages
Use Rules ALL, or a subset of the rules the selected packages contain
Exclude Rules Rules to skip - NONE when empty. Use either Use Rules or Exclude Rules, not both. Unticking every rule clears the exclusion.

Data - what to run it against

Field Purpose
Define-XML File Optional Define-XML used for metadata (codelists, value-level metadata, controlled terminology). Pre-filled when the library has a Define-XML attached.
Define-XML Version Optional; only needed when the version cannot be detected from the document. Enabled once a Define-XML file is set.
Reference Library Optional open library whose datasets the rules may read (e.g. SDTM domains for ADaM checks) but which is not itself validated
Use Data Sets ALL, or a subset of the library's datasets to validate

Metadata - where the standards metadata comes from

Field Purpose
Metadata Products CDISC Library products supplying metadata, highest precedence first. Leave empty (<default>) to derive them from the selected rule packages.
TIG Use Case Therapeutic Implementation Guide use case; enabled only when a TIG rule package is selected. The shipped rule corpus contains no TIG package, so this field stays disabled.
CT Packages Controlled Terminology packages. Leave empty (<default>) to use the CT the Define-XML declares, else the CDISC CT version the Trial Summary (TS) states; with neither, the rules that need CT are skipped. A package the metadata store does not hold stops the check. <recent> picks the newest package the metadata store holds for each terminology the run reads. The list offered follows the Metadata Store field: a store that cannot be read offers no packages (the error is shown), and with the field blank the <recent> row names the store the list comes from.
Metadata Store The CDISC metadata store the run reads. Leave blank to use the one the application maintains (~/.cumbaDataBrowser/metadata-cache.zip); seed it under Edit → Settings… → Validation → Metadata Store.
Dictionaries Directory The external dictionary store (MedDRA, WHODrug, …). Leave blank to use the one the application maintains (Edit → Settings… → Validation → CDISC Dictionaries). A directory named here must exist, or the run fails.
Dictionary Version One field per external dictionary: the installed version to use for this run. Leave blank to use the store's selected version.

Advanced - the values a new library starts with are set under Edit → Settings… → Validation → coreJ Check

Field Purpose
Severity Threshold Lowest severity still reported (Reject, Error, Warning - the default - or Info)
Max Findings per Rule Cap on findings reported per rule and dataset; blank uses the engine default (1000), 0 or a negative value means unlimited
Rule Worker Threads Threads used to evaluate rules within one dataset (default 1)

10.8 Validate Define-XML

Tools → Validate Define-XML (also on the context menu of such a library) checks a library opened from a Define-XML (see Section 11.1) against the Define-XML rules that ship with the application (the rules-define/ folder). A dialog asks:

Field Purpose
CT Packages Controlled Terminology packages to check the codelists against. Leave empty (<default>) to use the CT the Define-XML declares; any package named here replaces that declaration. A package the metadata store does not hold stops the check.
Define-XML Rule Families The rule families to run (the shipped rules: CDISC, PMDA). Leave empty (<all published>) to run every family that has rules for the document's Define-XML version. Tick families to run exactly those; a ticked family with no rules for that version stops the check and says so. The picker shows each family with the document's version (e.g. CDISC — Define-XML 2.1); a family without rules for that version is greyed out with a note (PMDA — no package for Define-XML 2.0) and cannot be ticked (a remembered tick can still be removed).

Values are remembered per library. When the installed rules no longer publish a remembered family, a warning names it as the dialog opens; the check skips it, and stops only when none of the selected families is published. When the check finishes, its report opens as a report view (Section 10.5).


10.9 Reviewing Findings

The report view keeps a status and a comment per finding, carries them to the next run of the same library, and exports them for the conformance section of the reviewer's guide (SDRG / ADRG). It works for coreJ runs, Define-XML checks and attached reports (CDISC CORE JSON, Pinnacle 21 Excel), on a local and on a remote connection. Settings ▸ Validation ▸ Finding Review switches it off.

The review bar sits above the Findings tab. Its first line says where the review lives (the library's location or a study, see below), the rule pack, how many runs are archived and which run you look at. The Findings table gains the review columns - review_status, review_comment (the newest comment; "(+n)" when there are more), who set the status and when, who wrote the comment and when, and review_history:

History Meaning
NEW first seen in this run
CARRIED seen before; its status and comments carried over
REAPPEARED gone in an earlier run, back in this one; its comments are kept
NOT_RECHECKED not in this run, but the run did not check that rule on that data set (Use Rules, Use Data Sets, Max Findings per Rule): it stays open work, shown muted
RESOLVED not in this run although the rule was checked: fixed. Shown greyed; a double-click opens no data set

Resolved findings are hidden by default; the bar says how many ("12 resolved hidden"). The Resolved choice shows them or shows only them. The other filters: a status (or All unresolved / All explained), New, Reappeared, Rule changed, Possible match and Concurrent edit. They combine with a rule chosen on the Rules tab.

Statuses. A new finding is Open. The team sets On hold, Escalated (unresolved) and Accepted, False positive, Not applicable (explained: these need a comment). Resolved is never set by hand. The list is the team's (see Team configuration); a status that is retired keeps its ratings, shown as "Accepted (retired)".

Rating findings. Select rows (one, several, or a whole filtered table), then Rate… (a status and a comment) or Comment…. A confirmation lists what is written: the number of findings, every rule with its count (in bold when the selection spans several rules), the data sets, the current statuses and any rows left out (a resolved finding takes no status). History… shows one finding's events, each with its own user and time; there a comment can be edited (the old text stays in the history) or retracted. Nothing is ever deleted.

Carry-over. A finding is the same finding in the next run when the rule, the data set, the variables with their values and the record agree: the record's key variables when the run resolves them, else USUBJID. --SEQ is never used: it changes between data extracts. A changed value or a changed key is a new finding (the old one resolves). When the number of identical findings changes, the extra ones are offered as a possible match (History… → Accept match / Decline match); nothing is merged without you. When a rule's version changed since a finding was rated, the row is flagged Rule changed: re-review it, then Confirm rating (Define-XML checks report no rule versions, so they are never flagged). A change of rule pack (e.g. SDTMIG 3.3 → 3.4) starts a new history.

Location or study. By default the review belongs to the library's location - the case where new data overwrite the old folder. When each data version is a new folder, Scope… binds the library to a named study: every folder linked to the study continues the same history.

Sharing in a team. The reviews live in the review folder (Settings ▸ Validation ▸ Finding Review; default ~/.cumbaDataBrowser/finding-review), apart from the reports, which stay unchanged in an archive there. Point everyone at one folder on a network drive to share them: several people may rate at the same time. The view refreshes every 30 seconds (a network share may delay another machine's edits by a few seconds more). The team's statuses, the record-key mode and the export options are the team configuration (below); it lives in the review folder too. Over a remote connection the folder is the server's. When the review folder cannot be opened (an offline or read-only share), the bar says review failed with the reason, and Retry tries again.

Team configuration. Settings ▸ Validation ▸ Finding Review holds, under the folder and the switches, the team's shared configuration: the Statuses a reviewer can set (Add status…, Move up / Move down, Retire; OPEN - no rating yet - and RESOLVED - derived - are built in, and a status is never deleted, only retired, so its ratings keep showing), the Key mode of a review run (FULL, DEFINE or OFF), whether an Excel export adds the Review detail sheet, and after how many seconds a lock left by a crashed or disconnected member is taken over. Anyone may change it, and the page says who changed it last. It is saved with the page's Save, together with the other settings; the save waits while another member is writing, and is refused - with the reason, your edits kept - when it cannot get its turn. Cancel on the Saving team configuration… step stops that wait at once and names who holds the lock; your edits stay. While the team configuration is being read (after a folder change, a Reload, or when the page opens) its part of the page is greyed; if it cannot be read, the page says why and the part stays greyed until a Reload succeeds. Changing the key mode asks first: it starts new finding identities - the next run's findings are new, the earlier ones resolve, and ratings do not carry over. Reload team configuration reads it from the review folder again (after a confirmation, it drops your unsaved team edits) - the way out when someone else saved in between. When you change the review folder, the team configuration is read from the new folder; team edits pending at that moment - or whenever it is read again - are dropped and Cumba asks you to apply them again. While the data manager does not serve the review, a new review folder applies at the next start.

Attached from the archive. Opening the report view of a library without a report attaches the newest archived run of the same data (same files, sizes, dates and contents), labelled "attached from archive". Before a coreJ check of data that has an archived run made with the same rule packages, Cumba asks Attach it or Run again; the default is Run again when the archived run was made with another engine or rule corpus version (the dialog says which). A check with Use Rules, Exclude Rules or extra rule files is never offered an archived run. Both are switched in Settings ▸ Validation ▸ Finding Review.

Who. Every rating and comment records your operating-system login and your display name (Settings ▸ Validation ▸ Finding Review). This is attribution, not an electronic signature: the review makes no 21 CFR Part 11 / Annex 11 claim.

Export for the reviewer's guide. Export… writes, on your machine, one row per finding group and status - Rule ID, other rule ids, rule description, severity, data set, variables, message, count, status, explanation (the comments, without their authors), rule version, last reviewed by / at - for the findings of the viewed run and the ones it did not re-check; resolved findings are left out, and so are statuses the team configuration keeps out of the export (in both sheets). As Excel (sheet Conformance issues, plus a Review detail sheet with every comment version when the team configuration asks for it) or CSV (UTF-8; a cell that a spreadsheet would read as a formula, starting with =, +, - or @, gets a leading apostrophe).

11. Standards & Metadata

Cumba was built around the data standards used in clinical research - primarily CDISC (SDTM, ADaM, SEND) - and treats their metadata as first-class citizens rather than as side annotations.

11.1 Define-XML as a Library

A Define-XML is the metadata document that describes the structure, variables, codelists and value-level constraints of a study's submission datasets.

In Cumba a Define-XML is treated like any other library: simply open the .xml file (File → Open Library ▶ From File or drag-and-drop) and it appears as a new entry in the Libraries view (see Section 4.1). The datasets, variables and codelists described inside become visible just like a regular library - once it is open, you would not notice from the data view that the source was a Define.

Lazy loading. When you open a Define-XML, only the definitions from the Define are listed at first (the metadata: datasets, variables, codelists). At this point Cumba does not check whether the referenced data files are actually present. Double-click an entry to open the referenced dataset - the data is loaded on demand, only when you open it. If the referenced dataset is missing, Cumba reports an error when trying to open it (the file could not be opened as a dataset).

💡 This lazy approach means a Define-XML opens instantly as a browsable metadata library, even when the actual data sits elsewhere or isn't available yet - you load each dataset only when you need it.

If the Define-XML links a validation report that cannot be read, the library still opens - without its findings - and a warning names the report.

One caveat to be aware of: codelists in a Define-XML typically contain only the values that actually occur in the corresponding study data (this is part of the Define standard). A Define-derived format will therefore reflect the values present in this submission, not necessarily the full controlled-terminology codelist. If you need the complete codelist for analysis purposes (e.g. to display a 0 count for an unused level in a frequency table), you may want to load the original codelist source in addition to the Define.

💡 Why this matters: in many tools Define-XML is a separate "metadata viewer" disconnected from the data view. In Cumba the Define is part of the data view - a column with a codelist will show its decode whether the codelist came from a SAS catalog, a Define, or a Dataset-JSON.

Cumba also writes a Define-XML. When Tools → Convert Data… converts a library to a folder, Create define.xml (see Section 2.2) writes a basic Define from what Cumba knows about the output: the datasets, the variables with their types and lengths, and the codelists it found. With Value-level metadata from data it also scans the data for value-level metadata per test code, parameter code or qualifier name. CT packages names the controlled terminology the Define declares (blank: taken from the Trial Summary); Implementation guide sets the standard the datasets follow. The study-level descriptions, comments, origins and methods are not invented and have to be added by hand.

11.2 Validation Engine

Cumba ships with a built-in validation engine for clinical data:

  • Validation runs on coreJ, P300's own conformance rule engine, integrated directly into Cumba. Its rules are written from the CDISC, FDA and PMDA specifications.
  • The published rule packages ship with the application (in the rules/ and rules-define/ folders of the installation) and are pre-filled as the Rules Directory of the check. They cover SDTM, ADaM and SEND datasets and Define-XML documents; each package names the standard and version it validates against, and the check pre-selects the packages that match the library (see Section 10.7).
  • The shipped families are CDISC, FDA and PMDA for datasets and CDISC and PMDA for Define-XML. A fourth dataset family, COREJ, is written directly from the CDISC implementation guides - SDTMIG 3.2, 3.3 and 3.4, ADaMIG 1.2 and 1.3, and SENDIG 3.0, 3.1 and 3.1.1. It covers the same standards as the publisher families, so you select one or the other; COREJ is never pre-selected.

The engine evaluates rules at the library level (cross-dataset checks such as referential integrity between DM, AE, EX, …) and produces findings that are surfaced through the standard mechanism described in Chapter 10: tooltips, yellow cell highlights, ⚠️ markers at every level, and the Validation Report as a dataset.

📝 Note on rules: coreJ is not CDISC CORE and does not use its rules. The rule definitions are P300's own, derived from the published CDISC, FDA and PMDA specifications, and they ship with the engine.

11.3 Where Format & Codelist Information Comes From

Format and codelist information is read automatically - there is no separate "apply" step. But the format name and the format's meaning come from different places, and for SAS data they are in different files. Section 4.4 sets that out in full: which file types carry a format name, which two file types can supply the actual code → decode mapping, and how catalogs stack when more than one defines the same name.

11.4 External Dictionaries - Expected Input Files

Edit → Settings… → Validation → CDISC Dictionaries installs a dictionary from a folder holding the supplier's distribution. MED-RT, UNII, the SEND neoplasm subset and HGNC can also be downloaded directly; MedDRA, WHODrug, SNOMED CT and LOINC always come from a folder you supply, under your own licence. This section defines what that folder must contain. The same text ships in the dictionaries/README.txt of every installation.

Rules for every dictionary

  • Choose the folder that holds the files themselves. Unpack a zip first - the installer reads folders, not archives. SNOMED CT is searched in subfolders and LOINC also accepts a LoincTable/ subfolder; every other dictionary needs its files directly in the chosen folder.
  • One release per folder. Do not unpack two releases into the same folder.
  • Text files are read as UTF-8; a leading byte-order mark is fine. A byte that is not valid UTF-8 is replaced and reported as a warning after the install - the term containing it will not match your data.
  • Terms are installed exactly as the supplier spells them; case is kept.
  • The release version is read from the files. A folder whose version cannot be read is not installed.
  • Files not listed below are ignored. Column and field numbers count from 1.
  • Every line is checked. Empty lines are ignored; any other line that does not have the shape described below aborts the install, and the message names the file, the line number and the check that failed. Nothing is installed from such a folder - a dictionary missing some of its rows would report conformant data as invalid.
Dictionary Required files Version taken from
MedDRA (MedAscii) llt.asc pt.asc hlt.asc hlgt.asc soc.asc mdhier.asc meddra_release.asc meddra_release.asc, field 1 (e.g. 27.0)
WHODrug (B3 only) DD.txt INA.txt version.txt version.txt (e.g. SEP_2020)
SNOMED CT (RF2) one sct2_Description*.txt below the folder date in the file name (e.g. 20240901)
LOINC Loinc.csv or LoincTable/Loinc.csv highest VersionLastChanged (e.g. 2.77)
UNII UNII_Records_<date>.txt <date> in the file name
MED-RT MEDRT.txt (+ Core_MEDRT_*_DTS.xml or MEDRT_Release_Notes*.txt) the DTS file's version, else the release notes
Neoplasm SEND Terminology*.txt + SEND Publication Date Stamp*.txt the date stamp file
HGNC one hgnc_complete_set*.txt (tab-separated, with a header row) the newest date_modified in the file

MedDRA

The MedAscii distribution: one record per line, fields separated by $ (a leading and a trailing $ are allowed).

File Fields read
llt.asc, pt.asc, hlt.asc, hlgt.asc, soc.asc 1 = code (8 digits), 2 = name (not empty). A line with fewer than two fields, a code that is not 8 digits or an empty name aborts the install.
llt.asc in addition 3 = the LLT's PT code. A line without it, or whose PT code is not a code in pt.asc, aborts the install.
mdhier.asc 1 = PT code, 2 = HLT code, 3 = HLGT code, 4 = SOC code (each 8 digits), 12 = primary SOC flag (Y or N). A row with fewer than 12 fields, a code that is not 8 digits or another flag aborts the install. Only rows flagged Y (the primary path) are read; each of their four codes must be a code in pt.asc, hlt.asc, hlgt.asc or soc.asc respectively, else the install aborts naming the file, line and code.
meddra_release.asc 1 = the version, from the first non-empty line

Two spellings of one term that differ only in case within one file abort the install.

WHODrug

⚠ Only the B3 format, delivered as fixed-width .txt files, is supported. Since the March 2026 release, UMC delivers WHODrug only as .csv files (B3 and C3 alike); a folder that holds .csv files but no DD.txt is refused with a message naming that change. The C3 format is not supported either: a DD.txt or version.txt that is not B3-shaped is refused. Install a B3 .txt release.

Fixed-width text, one record per line. DDA.txt and the other B3 files are not read.

File Columns
DD.txt (drug names) 1-6 drug record number · 7-8 sequence number 1 · 9-11 sequence number 2 · 31 to end of line: drug name. Every line must be longer than 30 characters, with digits in 1-6, 7-8 and 9-11 and a drug name that is not empty; any other line aborts the install. Columns 12-30 are not checked. A drug record's preferred name is its row with sequence 1 = 01 and sequence 2 = 001.
INA.txt (the full ATC index) 1-7 ATC code · 8 ATC level · 9 to end of line: ATC text. The code must be an ATC code of one of the five levels (e.g. N, N02, N02B, N02BE, N02BE01), the level digit must agree with its length (1 = one character, 2 = three, 3 = four, 4 = five, 5 = seven) and the text must not be empty; any other line aborts the install.
version.txt The first non-empty line. Its last five characters name the release as a three-letter month and a two-digit year: a line ending in Sep20 installs as SEP_2020. A line that does not end in a month and two digits is refused (C3 is not supported).

Two drug names, or two ATC texts, that differ only in case abort the install, as MedDRA's do. A drug name and an ATC text that differ only in case (IBUPROFEN, Ibuprofen) are the normal case and are both installed.

SNOMED CT

An RF2 release - the International Edition, a national edition, or the Global Patient Set.

  • The folder is searched for sct2_Description*.txt. An RF2 release has Snapshot/, Full/ and Delta/ views: when a Snapshot file is present only the Snapshot is read, otherwise Full. If more than one description file remains - a language extension, or two editions unpacked together - the install is refused.
  • Tab-separated with a header row. The columns are found by name: active, conceptId, typeId, term. Only rows with active = 1 are read. An empty file (no header row), a row with too few columns, or an active row with an empty conceptId or term aborts the install.
  • Concept codes: every active concept that has a description.
  • Terms: per concept, its first active synonym (typeId 900000000000013009). The Fully Specified Name, e.g. Headache (finding), is never used as a term.
  • Version: the last 8-digit date in the file name - sct2_Description_Snapshot-en_INT_20240901.txt installs as 20240901.
  • A synonym whose spelling differs from an already-installed term only in case is passed over: the concept takes its next active synonym instead, and a concept left without one is installed as a code only. The install ends with a warning that says how many spellings were passed over; data carrying such a spelling is reported as invalid.

LOINC

Loinc.csv, in the folder itself or in LoincTable/. A standard CSV file with a header row; quoted fields may contain commas, doubled quotes and line breaks. The columns are found by name: LOINC_NUM, LONG_COMMON_NAME, VersionLastChanged. A record too short for the LOINC_NUM and LONG_COMMON_NAME columns, or one with an empty LOINC_NUM, aborts the install; the message names the record number (a quoted field may span lines). A code with an empty name is installed as a code only.

UNII, MED-RT and Neoplasm

These are normally downloaded by the dialog; a folder install expects the files as published.

Dictionary Format
UNII UNII_Records_<date>.txt, tab-separated with a header row; columns UNII and DISPLAY_NAME by name (else columns 1 and 2). A row too short for these columns, or a code that is not 10 characters of digits and upper-case letters, aborts the install; a row with an empty code or name is skipped. If several files match, the first in name order is read - keep one per folder. A display name that differs from an installed one only in case is dropped (the first one read is installed; its UNII code still is) and the install warns.
MED-RT MEDRT.txt, tab-separated, no header: 1 = concept name, 2 = NUI. A line with fewer than two columns, an empty name or a NUI that is not N followed by 10 digits aborts the install. A concept name that differs from an installed one only in case is dropped (the first one read is installed; its NUI still is) and the install warns.
Neoplasm The CDISC SEND controlled terminology, SEND Terminology.txt (or SEND_Terminology.txt; the name may carry a suffix, e.g. SEND Terminology 2026-03-27.txt, and likewise the date stamp file SEND Publication Date Stamp*.txt, with spaces or underscores), tab-separated with a header row; the columns Codelist Code and CDISC Submission Value are found by name. An empty file, a header without either column or a row too short for them aborts the install. Only rows of the Neoplasm Type codelist (C88025) ending in , BENIGN or , MALIGNANT are read. Exactly one terminology file and one date stamp file per folder.

12. Integrations

12.1 AI Agent

Window → Show View → AI Chat (Ctrl+Alt+A) shows the AI Agent pane in the Workspace: it opens the pane when it is closed and brings it to the front when it is open. To hide it, close its tab (or File → Close View).

📝 The feature is called the AI Agent. The menu entry reads AI Chat; the pane and its settings page read AI Assistant - this manual quotes the labels as they appear on screen.

The AI can both answer questions about your data/the tool and execute actions directly (filter, sort, transform, etc.).

12.1.1 What the Agent Can and Cannot Do

The Agent works through a fixed set of tools. The boundary is deliberate and worth stating plainly:

The Agent reads, filters, sorts, analyses and opens. It never writes.

It can It cannot
Inspect schema, dimensions and sample data Convert data (Tools → Convert Data…)
Open and close datasets; list libraries and their members; open the Help ▸ Data Examples Export to a file
Set, remember, re-apply and clear filters Edit values, add rows or columns, mark rows deleted
Sort, hide/show columns, pin columns, set by-group; find text, jump to a row or column Rename or remove libraries
Build frequency and descriptive statistics, charts and SQL results Run Define-XML conformance checks
Transpose, compare and merge datasets (including SUPP-- and SUPPDM) Change the window layout, zoom or split regions
Run coreJ validation, attach a validation report file to a library, and read the findings

Running coreJ and deleting a memorized filter ask for your confirmation first. What the Agent may see of your data is set by the Data access level (see 12.1.3); the chat names the level when it starts.

There is no tool that writes a file or alters source data. An Agent-built result - a frequency table, a chart, a SQL result - is a new view in the Workspace, exactly like the same result built by hand from the menus. Your data on disk is never touched.

12.1.2 Multi-Provider Support

The AI Agent supports multiple AI providers (configurable by clicking the menu icon in the AI pane header). Choose the provider and model that best matches your organization's compliance requirements, performance needs, and cost preferences.

12.1.3 Configuration

Click the menu icon (☰) in the AI Agent pane header, or open Edit → Settings… (Ctrl+,) and choose AI Assistant. The AI settings have four pages; changes take effect with Save.

AI Assistant

Setting Description
Provider CLAUDE (Anthropic API) or OPENAI (OpenAI API)
API URL The endpoint for the chosen provider - any Anthropic- or OpenAI-compatible endpoint, including your preferred AI router
Model Type it, or click Fetch models… to retrieve the list from the endpoint
API key Paste your API key. It is stored in plain text in ~/.cumbaDataBrowser/config.json. Leave it blank to keep the stored key; Clear stored key removes it.

These fields are read-only while a conversation is running; New conversation unlocks them.

Data access - Data access level: ALL (everything), STATISTICS (metadata and the statistics of one variable of an unfiltered dataset) or NONE (metadata only). With STATISTICS, Minimum cell count of a frequency row (0 = off) suppresses small counts. Under Features, groups of agent tools can be switched off (Navigate, Filter, Find in a table, Sample rows, SQL, Statistics, Derived tables, Charts, Validation). An administrator can lock these values.

Voice - speech input through a Whisper-compatible endpoint (URL, model, API key, language, microphone, silence trimming, voice threshold, auto-send). A stored microphone that is not plugged in keeps its setting until you choose another. Hold Ctrl+Shift+Space in the chat to record.

Behaviour - Tool calls per message (cap) (default 25), Output tokens per turn (default 8,192), History window (messages) (default 40), Stream refresh (ms) (default 250), Verbose tool output (parameters and result). While a conversation runs, the tool calls, the tokens and the history window apply from the next conversation; the stream refresh and the verbose output apply at once.

Where the key comes from (first match wins): 1. an administrator's locked value; 2. the JVM system property -Danthropic.api.key=… / -Dopenai.api.key=…; 3. the environment variable ANTHROPIC_API_KEY / OPENAI_API_KEY; 4. the key saved in Settings. A key set by property or environment variable therefore overrides the one saved in Settings.

12.1.4 Tab Integration

The AI Agent lives in a regular Workspace tab, so you can use Cumba's split-pane system to keep your data visible on the left while the AI is on the right (drag the AI tab to the side to split the view).

The bottom line of the AI Agent pane shows the conversation's token usage (in, cached, out), so you can track API costs.

12.2 Open Study Builder

Cumba integrates with the open-source Open Study Builder (OSB) - a system for managing study definitions and standards.

Open an OSB instance with File → Open Library ▶ From URL, entering its API URL (e.g. https://osb.cumba.net/api). The library lists OSB's read-only listings as datasets: the ADaM ASM listings (MDVISIT, MDENDPNT, MDFLOW), the SDTM study-design domains (TA, TE, TV, TI, TDM, TS) across all studies, the CT codelists and terms, the SNOMED, UNII, MED-RT and UCUM dictionaries, and the listings of studies, visits and activities. Each opens as a table and can be filtered, sorted and analysed like any other dataset.

This lets reviewers inspect what's in OSB - how a study is defined, which terminologies are referenced - without leaving the Cumba data browser.


13. Tips & Shortcuts

13.1 Keyboard Reference

File: - Ctrl+O - Open Data Set ▶ From File - Ctrl+L - Select in Libraries - Ctrl+W - Close View - Alt+F4 - Exit

Edit: - Ctrl+Z / Ctrl+Y - Undo / Redo - Ctrl+C - Copy - Ctrl+F - Find Text in data - Ctrl+, - Settings…

Display: - Alt+Shift+Q - Show SQL Pane

Window: - Ctrl+Alt+A - Show View ▶ AI Chat - Ctrl+Plus / Ctrl+Minus / Ctrl+0 - Zoom In / Out / Reset - Ctrl+Shift+D - Perspective ▶ Reset to Default - Ctrl+Shift+M - Maximize Region

Navigation: - Alt+Right / Alt+Left - Next / Previous dataset - Alt+Up - Select Libraries

Columns: - Ctrl+Shift+F - Find Column (by name or label) - Ctrl+Shift+C - Hide / Unhide manager - Ctrl+Shift+H / K / A - Hide Selected / Hide Not Selected / Show All - Ctrl+Shift+P / U - Pin / Unpin Selected - Ctrl+Alt+Left / Right - Move Column Left / Right - Ctrl+Alt+Shift+Left / Right - Move Column to Start / End - Ctrl+Shift+O - Reset Column Order

Sort: - Ctrl+Alt+S - Change Sort Order dialog - Ctrl+Alt+Up / Down - Sort Ascending / Descending - Ctrl+Alt+Shift+Up / Down - Append Ascending / Descending - Ctrl+Shift+G - By Group End - Ctrl+Shift+R / E - Reset / Clear Sort Order

Filter: - Ctrl+Alt+I - Filter IN (pick list) - Ctrl+Alt+E - Filter ≡ (equal to the selected value(s)) - Ctrl+Alt+N - Filter ≠ (not equal to the selected value(s)) - Ctrl+Alt+V - Filter Value - Ctrl+Alt+C - Filter Contains - Ctrl+Alt+M - Filter Matches (regex) - Ctrl+Alt+R - Clear Filter

Tools: - Ctrl+Alt+Q - SQL Query - Ctrl+Alt+F - Create Frequency - Ctrl+Alt+D - Create Descriptive

Editor (a dataset opened with Edit): - Shift+Insert - Add Row - Shift+Delete - Mark Row(s) as Deleted / Undelete

SQL bar and SQL editor: - Ctrl+Enter - Execute - Ctrl+Space - Code completion

AI Agent: - hold Ctrl+Shift+Space - record voice input

Help & tooltips: - F1 - Manual - F2 - Focus the current tooltip (allows text selection / copy)

13.2 Power User Patterns

  • Quick filter on a value: select the cell → Ctrl+Alt+E (keep) or Ctrl+Alt+N (exclude)
  • Find a column you barely remember: Ctrl+Shift+F, type any fragment of name or label
  • Lock subject ID in view while scrolling wide: find USUBJID → Ctrl+Shift+P
  • Get back to the canonical sort: Ctrl+Shift+R
  • Inspect dataset metadata + validation status: hover the dataset tab (or library entry)
  • Edit the underlying SQL: drag the SQL bar down, click the triangle handle, or Alt+Shift+Q
  • Side-by-side compare: drag a dataset tab to the right edge → splits the workspace
  • AI alongside data: Ctrl+Alt+A (Window → Show View → AI Chat) → drag its tab to the side
  • Reopen a dataset the way you left it: Filter → Store Table Settings…
  • Zoom for presentations / accessibility: Ctrl+Plus to enlarge - the interface scales seamlessly

14. Help & Feedback

The Help menu provides:

  • Manual (F1) - opens this manual on manual.cumba.net

Help menu - Data Examples submenu open with sample data sources Help menu - Data Examples submenu open with sample data sources

  • Data Examples ▶ - submenu offering CDISC and PHUSE sample studies to download and load, from the public test-data repository cumba-oss/cdisc-test-data and, for the large studies, from files.cumba.net. Includes:
  • cdisc DataExchange-DatasetJson (ADaM, SDTM, SEND) - in Dataset-JSON (dsjc, json, ndjson) and XPT formats
  • phuse-scripts (ADaM incl. the cdiscpilot-update1 update, SDTM, SEND) - in XPT format
  • cdisc JSON data set with kanji - useful for testing UTF-8 handling
  • … (large, files.cumba.net) - scaled copies of the DataExchange-DatasetJson ADaM, SDTM and SEND studies and of the phuse-scripts SDTM study, in XPT and NDJSON (phuse SDTM: XPT only); each entry shows its approximate size (up to 44 GB). They are transferred gzip-compressed.
  • Feedback - opens the contact page on cumba.net
  • Subscribe to Newsletter - opens the newsletter sign-up on p-300.com
  • About - version, build, hash, timestamp, contact, and license information for embedded libraries; the licence status, and End User License Agreement…, which shows the agreement you accepted at the first start (read only)

15. Troubleshooting

15.1 Data Loading

A file won't load. - Check the file format is one of the supported types (see Section 2.1). - For non-standard CSV/Excel files (uncommon delimiters, multiple sheets, special encodings), use right-click on the dataset → Open With Properties… to specify reader options manually. - For files from URLs, ensure the URL is directly accessible (no redirects, no authentication wall).

A file stops loading with '… cannot be decoded with charset …'. - The file is not in that charset. Reopen it and pick its charset in the Charset option (e.g. Windows-1252 for SAS data written on Windows; for a library member, use Open With Properties…); for a dataset in an XPT library, reopen the library with that Charset. - If the message says the value 'ends inside a multi-byte character', the writing program cut it short. If it says the value 'ends with the first byte of a multi-byte character', either it was cut short or the charset is wrong - try the file's charset first. - For a CSV the message names row, column and line - open the file in a text editor at that line to see the bytes.

Character data shows wrong characters (mojibake / question marks). - The file is likely not UTF-8 encoded. Try Open With Properties… to specify the encoding (e.g. Latin-1, Windows-1252). A single-byte charset never stops the load, so a wrong one shows as wrong characters. - Cumba is fully UTF-8 compatible - once the source encoding is correctly specified, CJK and accented characters display correctly.

A memorized filter on an Excel file no longer finds a column with a numeric header. - Numeric column headers are read as the plain number (2026); earlier releases named the column 2026.0. Re-create the filter with the new name.

Performance is slow with a large library. - Try right-click on the library → Lock In Memory to keep the datasets in RAM. - Hide unused columns (Ctrl+Shift+H) - fewer rendered columns improves scrolling. - Close unused dataset tabs.

15.2 Display

Validation findings (yellow highlights) are not shown. - Make sure the ⚠️ toolbar button is enabled, or Display → Show Validation Findings is checked. - Validation findings only appear when a Define-XML carrying findings is loaded, a coreJ check has run, or an external validation report (Pinnacle 21, CDISC CORE / coreJ) has been added.

Tooltips don't appear on hover. - Check Display → Show Tooltips is enabled. - If tooltips appear but disappear too fast, press F2 while the tooltip is visible to focus and pin it.

Row numbers look non-sequential (1, 2, 3, 6, 7, 12, …). - This is intentional - you are viewing Real Row Numbers (the physical position in the stored file). After sort/filter, these numbers reflect the original positions, not the display order. - To see the display order instead, switch to Display → Row Numbers → Show Display Row Numbers or Show Both Row Numbers.

Columns are not in the order I expected. - Use Ctrl+Shift+O to reset to the original (stored) column order. - In the Hide/Unhide dialog (Ctrl+Shift+C), the 🔄 button restores the original order of the visible list.

15.3 Filters & Sort

A filter shows fewer rows than expected (e.g. AVAL > 8.55 excludes some "8.55" rows). - This is a floating-point display rounding effect. Hover the cell to see the Exact value in the tooltip - values displayed as ≈8.55 may actually be 8.5499… (just below the threshold). - See Smart Number Display.

Reset Sort Order doesn't go back to the order I expected. - Ctrl+Shift+R restores the stored sort order defined in the dataset (e.g. CDISC datasets often carry a canonical USUBJID + AESEQ order). To clear sorting entirely instead, use Ctrl+Shift+E (Clear Sort Order).

A memorized filter doesn't seem to apply. - A memorized filter applies only the parts whose variables exist in the current dataset. When none of its variables exist there, it is not applied and the status bar says so; when only some do, a notification names the parts that were dropped. See Memorized Filters.

15.4 AI Agent

The AI Agent pane shows "API key not configured". - Click the menu icon (☰) at the top of the AI Agent pane to open the AI settings (Edit → Settings… → AI Assistant). - Choose a provider, paste your API key, and click Save. - Power users can also set the key via environment variable (e.g. ANTHROPIC_API_KEY) or JVM system property - restart Cumba afterwards.

The AI doesn't seem to know about my data. - The AI works on the libraries open in the Libraries view - open the library first. What it may read is set by the Data access level (Settings → AI Assistant → Data access): with STATISTICS or NONE it sees no row values. - Some questions may need the AI to call tools (Filter, Statistics, etc.) - enable Verbose tool output under Settings → AI Assistant → Behaviour if you want to see what the AI is doing.

15.5 Validation

Check Using coreJ … - which datasets does it check? - The check always runs on a library (many rules are cross-domain). From the Tools menu or a dataset's context menu it runs on the library selected in the Libraries view, or the library of the selected dataset. Narrow Use Data Sets on the dialog's Data tab to validate only some datasets. - See Section 10.7.

Check Using coreJ … and Validate Define-XML are missing from the Tools menu. - The data manager Cumba runs on does not offer the checks (an installation configured for the basic data manager, or a server without them): Edit → Settings… → Extensions says so on the coreJ row. Or the coreJ extension is switched off there, or was removed by your administrator. See Section 10.7.

The validation finding shows on a column, but the values look fine. - Some findings are scoped to the column or the dataset, not to individual cells (e.g. "Variable length too long" applies to the column definition, not to any single value). The tooltip on the column or its yellow marker shows the rule's actual scope.

15.6 General

I can't find a function I expected to exist. - Cumba relies heavily on right-click context menus. Try right-clicking on cells, columns, datasets, or libraries - many functions live there and not in the top menu bar. - Use Ctrl+Shift+F to search columns by name or label. - Use Ctrl+F to search for values in the data.

An error dialog appeared out of nowhere. - That is intentional. Failures that used to die quietly in a log file now surface to you - including failures that happen before the main window is even up, which are held back and shown as soon as it appears. Seeing the message is better than wondering why something silently did not work. - The text of the message plus the build info from About is what makes a report useful.

Loading a large SAS file behaves differently than it used to. - sas7bdat files are read in parallel and memory-mapped by default. Row order and values are byte-identical to the older sequential reader - only the speed and the memory profile change. - If you ever need the old behaviour (to rule the loader out while chasing a bug), start Cumba with -Dbdat.parallel=false or -Dbdat.mmap=false.

Something else broken or unclear? - Check the About dialog for the build/hash of your version, and contact info@p-300.com with a description and the build info.


Appendix A. Glossary

Cumba UI concepts

  • Library - a top-level container in the Libraries view that holds datasets and formats. A library can be backed by a folder of files (SAS, Parquet, JSON, CSV, …), a single Define-XML, a single file, a URL (Open Study Builder, CDISC Library), a Databricks catalog schema or a database schema.
  • Libraries (view) - the left-hand pane of the application; lists all open libraries with their datasets and formats. Window → Show View → Libraries brings it back to the front. (Earlier releases called it the Library Explorer.)
  • Workspace - the right-hand area; contains the open dataset, format and analysis tabs.
  • Pane / Region - a sub-area of the Workspace that holds one or more tabs. Panes are created by splitting the Workspace (Split Right / Left / Above / Below) and can be maximized, closed, or merged again.
  • Tab - an opened item (dataset, format, analysis result, AI Agent) inside the Workspace.
  • F marker - a small F icon next to a column name indicating that a format is applied to that column.
  • N marker - indicator that a column is numeric.
  • Memorized Filter - a filter saved under a name; offered in every dataset and applied wherever its variables exist. Persists across application restarts.
  • SQL Bar - the collapsed bar above each opened dataset that expands to a full SQL editor showing the query underlying the current view.
  • Display Row Number - the row's position in the current view (after sort/filter); changes as the view changes.
  • Real Row Number - the row's physical position in the stored dataset; stable regardless of view.
  • Native value - the raw stored value of a cell. In clinical-data terminology this is also called the Value or Code.
  • Formatted value - the decoded label produced by an applied format. Also called the Decode.
  • By-Group sort - a sort that defines visual groups, indicated by a "ball" on the sort arrow and (optionally) horizontal separator lines in the data view.
  • Outlier marking - Cumba design principle: only the less common property of a column is marked (e.g. only numeric columns get an N marker, not character columns). The default case is unmarked.
  • Identity Format - a format where each code equals its decode; used to define an allowed value domain without translation.
  • Real Mapping Format - a format where codes differ from decodes; used to translate stored codes into human-readable display values.

Clinical data standards

  • ADaM - Analysis Data Model (CDISC standard for analysis datasets).
  • ADSL - Subject-Level Analysis Dataset; one row per subject.
  • BDS - Basic Data Structure; long-format ADaM convention.
  • CDISC - Clinical Data Interchange Standards Consortium.
  • coreJ - P300's conformance rule engine. It powers Cumba's built-in SDTM, ADaM, SEND and Define-XML validation (Check Using coreJ …, see Section 10.7) and is also available as a product of its own. Its rules are written from the CDISC, FDA and PMDA specifications.
  • Codelist - a controlled set of allowed values for a variable.
  • CT - Controlled Terminology; the maintained set of codelists used in CDISC standards.
  • Dataset - a structured set of records loaded from a file (e.g. DM, AE, LB). Cumba keeps dataset and table apart on purpose: a dataset is data, a table is a result - a Frequency, a Descriptive, a Compare. Both open as tabs and both behave like data, but the words are not interchangeable.
  • Dataset-JSON - CDISC's JSON-based exchange format for datasets, an alternative to SAS XPT.
  • Define-XML - CDISC metadata standard describing datasets, variables and codelists.
  • Domain - in SDTM, a thematic grouping of observations (e.g. AE adverse events, LB lab tests, VS vital signs).
  • Format - a code-to-decode mapping (see Identity Format / Real Mapping Format).
  • P21 (Pinnacle 21) - industry-standard validator for SDTM/ADaM datasets. Findings can be loaded into Cumba.
  • SDTM - Study Data Tabulation Model; CDISC standard for tabulation datasets.
  • SEND - Standard for Exchange of Nonclinical Data; structurally based on SDTM but for animal study data.
  • SUPP-- - Supplemental Qualifiers (e.g. SUPPAE, SUPPDM). Hold variables that don't fit in the main domain.
  • TIG Use Case - Therapeutic Implementation Guide use case; a CDISC-defined therapeutic-area-specific scenario for validation.
  • USUBJID - Unique Subject Identifier across the study.

File formats

  • Parquet - columnar binary file format with a typed schema. It has no slot for a format name; Cumba writes its own (see Section 4.4).
  • RData / RDS - R data formats. .RData (short form .rda) stores one or more named objects; .rds stores a single object. R factors are resolved to their labels while loading.
  • sas7bdat - native SAS dataset file.
  • sas7bcat - native SAS format catalog file; holds code/decode mappings referenced by sas7bdat files.
  • XPT / XPT v5 - SAS Transport file format, used for regulatory submissions.

End of Manual v0.5