CODAP — Beginner Track

A full walkthrough of CODAP's interface, importing a dataset, reading and editing a case table, and building your first graphs.

1. What CODAP actually is

CODAP (the Common Online Data Analysis Platform) is a free, browser-based data analysis tool built by the Concord Consortium specifically for teaching statistical and data reasoning — it runs at codap.concord.org with nothing to install and no account required to start working. It's simpler than full statistical software like R or Tableau, deliberately so: the entire interface is built around a small number of concepts (a case table, draggable attributes, and drop-zone graphs) that you can learn in one sitting and then reuse for any dataset. That simplicity is exactly why it's a strong lab environment for building real data-reasoning skills without fighting a complicated tool at the same time.

The beginner track gets you from "never opened CODAP" to comfortably importing a dataset, reading and editing it as a case table, and building basic graphs to answer simple questions about it.

2. Getting started

1. Go to codap.concord.org in any modern browser (desktop or tablet) — no login, no install, no plugin.
2. You'll land on a blank document with a small toolbar at the top. Click "Example Documents" in the toolbar (or the menu icon) to browse CODAP's built-in sample datasets — use "Mammals" or "Roller Coasters" for this track, since both are small, clean, and easy to reason about.
3. Selecting an example opens it directly into a case table — a spreadsheet-like grid where each row is one "case" (one mammal, one roller coaster) and each column is an "attribute" (a variable, like Speed or Habitat).
4. If you'd rather start from your own data, use the same menu → Import Data → From File and choose a CSV — CODAP will build a case table automatically from the header row.

3. The CODAP interface, in plain terms

4. Reading and editing the case table

• Click any cell to edit its value directly — CODAP updates every graph or component using that attribute instantly.
• Click the + at the right edge of the column headers to add a new attribute (column).
• Right-click a column header for options including Rename, Delete Attribute, and Edit Attribute Properties (where you can set a description, unit, and type — categorical vs. numeric).
• Click the row-number area on the left and drag to select multiple cases; right-click for options like Delete Cases.

5. Building your first graph

1. Click the Graph icon in the toolbar to add a blank graph component to the canvas.
2. Drag an attribute — e.g. Habitat from the Mammals dataset — from the case table header onto the graph's horizontal axis. CODAP builds a dot plot grouped by category automatically.
3. Drag a numeric attribute — e.g. Speed — onto the vertical axis instead (or in addition), and CODAP switches the graph type to fit: a scatter plot appears if both axes are numeric.
4. Click any single dot in the graph — the matching row highlights in the case table. This linked-highlighting behavior (select in one component, see it highlighted everywhere else) is CODAP's core teaching feature and works in every direction: table → graph, graph → table, graph → graph.

Coloring and grouping points

1. Drag a categorical attribute (e.g. Diet) onto the interior of an existing graph (not an axis) to color-code the points by that category — a legend appears automatically.
2. Drag a second categorical attribute onto the graph again to split it into a grid of sub-plots (facets) — one small graph per category combination.

6. Basic summary tools

• Click directly on an axis of a numeric graph and look for the small gear/menu icon that appears — from there you can toggle a mean, median, or box plot overlay directly on the graph.
• Right-click inside a graph for a context menu with options like Display as Bar Chart vs. Display as Dot Plot for categorical data.
• Use the graph's built-in count/percent toggle (usually near the axis menu) to switch a bar chart between raw counts and percentages.

7. Lab: explore a dataset and answer three questions

8. Pre-attempt checklist

• I can import or open a dataset and see it as a case table
• I can drag an attribute onto a graph axis and get the right chart type
• I understand that selecting a point/row highlights it everywhere else in the document
• I can color a graph by a categorical attribute
• I can add a mean/median/box-plot overlay to a numeric graph

9. What to do after this lab

Try the same three-question exercise against the "Roller Coasters" example dataset instead of Mammals — different attribute types (more numeric variables, fewer categories) will surface a slightly different mix of chart types and give you a second rep on the drag-and-drop workflow. Once building graphs and reading linked selections feels automatic, move to the Intermediate track, which covers formulas, hierarchical/grouped data, and multiple linked datasets.

← Back to all practice tools & labs

CODAP — Intermediate Track

Where drag-and-drop graphing stops being enough. This guide covers formulas, hierarchical/grouped data, working with multiple linked datasets, and simple simulation with sliders.

1. What changes at this level

Beginner work uses attributes exactly as they exist in the imported data. Intermediate work is about creating new attributes with formulas, working with data that has natural groups or nested structure (like students within classrooms, or measurements repeated per subject), and combining more than one dataset in a single document. This is also where CODAP starts to feel less like "exploring a static dataset" and more like a lightweight modeling environment, especially once sliders enter the picture.

2. Formula-based attributes

Right-click any attribute's column header and choose Edit Formula (or use the + button to create a new attribute, then edit its formula) to define a value computed from other attributes in the same case.

// Basic arithmetic referencing other attribute names directly
Speed / Lifespan

// Conditional logic
if(Speed >= 60, "Fast", "Slow")

// Built-in functions — CODAP supports a fairly full formula language
round(mean(Speed), 1)
sqrt(Height^2 + Weight^2)

// String functions
concat(Genus, " ", Species)

Aggregate functions across all cases

// The mean of an attribute across every case in the collection —
// useful for building a "distance from average" attribute
Speed - mean(Speed)

// Count of cases matching a condition
count(Diet = "Carnivore")

3. Hierarchical and grouped data

Real datasets often have natural nesting — repeated measurements per subject, students within a class, trials within an experiment. CODAP handles this with hierarchical case tables: two or more linked tables where each row in a "parent" collection can expand to show its related "child" cases.

1. Import or build a dataset with a grouping attribute (e.g. ClassName for a set of student records).
2. Drag that grouping attribute from its column header to the left, past the leftmost column boundary of the table, until CODAP shows a drop indicator — this promotes it into its own parent collection, and the table splits into a grouped/nested view with an expand arrow per group.
3. Once grouped, dragging a numeric attribute onto a graph axis will, depending on which collection you drag from, show either individual case-level detail or one summarized point per group — this is the core intermediate skill: knowing which level of the hierarchy a graph is drawing from.

4. Working with multiple linked datasets

You can have more than one case table (from separate imports) open in the same document. Two attributes with matching values across tables can be linked so that selecting a case in one highlights the related case(s) in the other — useful for comparing, say, a "Countries" dataset against a separately-imported "Continents" reference table.

1. Import a second dataset (Import Data → From File or another Example Document) into the same document — it appears as its own case table component alongside the first.
2. If both tables share a common attribute (matching values, e.g. a Country or ID column), CODAP can link selections between them — select a row in one table and the matching row(s) highlight in the other, the same linked-selection behavior from the beginner track extended across separate datasets.
3. Build a graph pulling attributes from one dataset while using the linked selection in the other to visually compare subsets.

5. Sliders and simple simulation

The Slider component (toolbar) creates a single adjustable numeric value you can reference inside formulas — this is CODAP's entry point into simulation and "what-if" modeling.

1. Add a Slider from the toolbar and rename its variable (default is usually v1) to something descriptive, e.g. threshold.
2. Reference it inside a formula-based attribute: if(Speed >= threshold, "Above", "Below").
3. Drag the slider's handle — every case's formula value, and any graph built from it, recalculates live as the slider moves. This is a genuinely useful way to let a student explore how a cutoff or parameter affects a dataset without editing formulas by hand each time.

6. Lab: a formula-driven, linked multi-component document

7. Pre-attempt checklist

• I can create a formula-based attribute using arithmetic, conditionals, and at least one built-in function
• I understand the difference between a case-level value and an aggregate (mean/count) across cases
• I can promote an attribute into a parent collection to build a hierarchical table
• I can identify which collection level a graph's axis attribute is drawn from
• I've built and used at least one Slider inside a formula

← Back to all practice tools & labs

CODAP — Expert Track

The Data Interactive Plugin API, building a custom plugin, programmatic/API-driven data import, simulation design, and packaging a document as a shareable teaching activity.

1. What changes at this level

Intermediate work stays entirely inside CODAP's own UI — formulas, sliders, hierarchical tables. Expert work steps outside that boundary: CODAP exposes a full Data Interactive Plugin API that lets an external web page (a "plugin," running in an iframe embedded in a CODAP document) programmatically read and write case data, create components, and react to selection events. This is how CODAP's own built-in tools like the sampler and the graph itself are actually built, and it's the same API you use to build a custom simulation, a game, or a custom data-collection interface that talks to a live CODAP document. This track assumes basic JavaScript comfort — you're writing real code here, not just formulas.

2. The Plugin API model

A CODAP plugin is just a web page, loaded inside CODAP as an iframe component, that communicates with the parent CODAP document using postMessage under the hood — wrapped by an official helper library so you rarely touch postMessage directly. The two building blocks:

Every API call is an object with an action and a resource, sent through the helper library's codapInterface.sendRequest() method.

3. Setting up a minimal plugin

1. Create a bare HTML page and include CODAP's plugin API helper library (either via the official CDN script tag or as an npm package, iframe-phone plus the CODAP plugin API wrapper, depending on which starter you use).
2. Initialize the connection to the parent CODAP document — this registers your plugin, telling CODAP your plugin's name, version, and preferred iframe dimensions.
3. Host the page anywhere reachable over HTTPS (a simple static host works fine — this doesn't need a backend for a basic plugin).
4. In CODAP, use Insert Plugin → From URL from the toolbar and paste your hosted page's URL — CODAP loads it as a new component on the canvas.

Reading and writing data from the plugin

// Create a new data context (a fresh dataset) from the plugin
codapInterface.sendRequest({
  action: "create",
  resource: "dataContext",
  values: {
    name: "SimResults",
    collections: [{
      name: "Trials",
      attrs: [
        { name: "trial" },
        { name: "outcome" }
      ]
    }]
  }
});

// Add a new case (row) to that dataset
codapInterface.sendRequest({
  action: "create",
  resource: "dataContext[SimResults].collection[Trials].case",
  values: [{ values: { trial: 1, outcome: "heads" } }]
});

// Read all current cases back
codapInterface.sendRequest({
  action: "get",
  resource: "dataContext[SimResults].collection[Trials].caseSearch[*]"
});

4. Listening for events from CODAP

Plugins can also react to what happens inside CODAP itself — useful for building a plugin that responds when a user selects a case or changes an attribute.

codapInterface.on("notify", "dataContextChangeNotice", function(notification) {
  // fires when data in the connected context changes
  console.log(notification);
});

codapInterface.on("notify", "component", function(notification) {
  // fires on component-level events, e.g. selection changes
});

5. API-driven and external data import

Beyond CSV import, expert-level CODAP work often means pulling data from an external source programmatically rather than by hand:

• URL-based import: CODAP can fetch a CSV directly from a public URL via Import Data → From URL — useful for pointing a document at a dataset that updates independently (e.g. a Google Sheet published as CSV).
• Plugin-driven import: a plugin can fetch data from any public API (weather, public health, sensor data) client-side and push it into a CODAP data context using the create action shown above — this is how you connect CODAP to a live external data source that a plain URL import can't handle (auth, pagination, JSON reshaping).
• Sensor/hardware input: CODAP has existing plugins for connecting physical sensors (e.g. via Bluetooth) — worth studying as a reference implementation if you're building your own real-time data-collection plugin.

6. Designing a simulation

A well-designed CODAP simulation plugin follows a consistent shape: a control (button, slider, or repeated trigger) that runs one trial of a random or rule-based process, pushes the result as a new case, and lets CODAP's own graphing tools do the analysis rather than trying to visualize results inside the plugin itself.

1. Design the trial logic first, independent of CODAP — e.g. a coin flip, a random walk step, or a simple agent-based rule.
2. Wire a "Run Trial" button to execute one trial and push exactly one case per trial into a data context.
3. Add a "Run N Trials" option that loops the same logic, useful for building sampling-distribution activities (a core CODAP teaching use case, closely related to its sibling tool, the CODAP Sampler).
4. Leave all graphing to CODAP itself — build a Graph component next to your plugin and let students drag the plugin's output attributes onto axes rather than rendering charts inside the plugin.

7. Packaging a shareable teaching activity

• Arrange your final document layout deliberately — case table, key graphs, and any plugin components sized and positioned the way you want a student to first see them.
• Use File → Save to produce a .codap document, or Share to generate a public link others can open directly, depending on whether you want a downloadable file or a live shareable URL.
• Add Text components with explicit instructions/questions directly in the document — CODAP activities are typically self-contained, meant to be opened and worked through without an accompanying handout.
• If distributing a custom plugin as part of the activity, document its hosted URL separately, since the plugin's own code isn't embedded inside the .codap file — only a reference to load it from.

8. Lab: a custom simulation plugin feeding a live CODAP graph

9. Pre-attempt checklist

• I understand the resource/action model behind every Plugin API call
• I can initialize a plugin's connection to a parent CODAP document
• I can create a data context and push new cases into it programmatically
• I can listen for a notification event from CODAP inside a plugin
• I've built and hosted at least one minimal working plugin

← Back to all practice tools & labs