# StatLens Instructor Guide

A practical guide for instructors using StatLens in their courses. Covers how to get data into StatLens, how to share pre-configured tool links with students, and how to use instructor-specific features.

---

## Getting Data Into StatLens

StatLens offers several ways to load data, from zero-setup to fully automated.

### Built-in Datasets

Every tool page has a **Datasets** tab with curated datasets filtered to match the tool. Students select from a dropdown — no files or URLs needed.

### Open a File (or a Link to One)

Every tool page has an **Open File/URL** tab that accepts:

- **CSV** files (comma-separated values)
- **TSV** files (tab-separated values — common when copying from spreadsheets)
- **JSON** files (StatLens dataset format — created by the [Dataset Builder](https://learnlens.org/statlens/data/builder/))

This is the simplest way for instructors to distribute custom data: build a dataset JSON in the Dataset Builder, download it, and share the `.json` file with students (via LMS, email, or course website). Students open it on whatever StatLens page they need.

The same tab also takes a **link** to a hosted file — any `https://` address pointing straight at the file. Loading data from a link writes it into the page's own URL, so **Share** then produces a QR code that opens the tool with that data already in it. See [Showing the class a QR code](#showing-the-class-a-qr-code).

If a file's first row is data rather than column names, uncheck **My data has headers** — StatLens supplies the column names instead of consuming the first value.

### Paste or Type Data

The **Edit Data** tab on each page lets students paste CSV data, type values into a spreadsheet-style editor, or (on categorical pages) enter summary counts directly.

JSON dataset files can also be pasted into the CSV textarea — StatLens detects the format automatically.

### URL Parameters

For textbook links, LMS integration, and pre-configured activities, data can be loaded via URL parameters:

| Parameter | Use case | Example |
|-----------|----------|---------|
| `?dataset=penny_ages` | Load a built-in dataset by ID | Textbook callouts |
| `?json=https://...` | Load a JSON dataset from a URL | Hosted custom datasets |
| `?csv=https://...` | Load a CSV/TSV file from a URL | Quick sharing without JSON conversion |
| `?data=1.2,3.4,5.6` | Inline numeric data | MyOpenMath per-student data |

See the full [URL API Reference](url-api.md) for all parameters.

### Hosting Custom Datasets

To create a shareable URL that auto-loads your dataset:

1. Build your dataset in the [Dataset Builder](https://learnlens.org/statlens/data/builder/) or prepare a CSV file
2. Host it on [GitHub Gist](https://gist.github.com) (click "Raw" to get the direct URL) or any HTTPS server
3. Either paste that link into the tool's **Open File/URL** tab and click **Share**, or append `?json=YOUR_RAW_URL` / `?csv=YOUR_RAW_URL` to any StatLens page URL by hand

This works on every page — explore tools, simulation pages, inference tests, distribution calculators.

### Showing the Class a QR Code

Every tool page has a **Share** button that renders the page's current link as a scannable QR code (with *Download SVG* for slides). A QR code carries a link, not a spreadsheet — so put the data on the web first, then let the link point at it:

1. Save the data as `.csv` (Excel: *File → Save As → CSV*).
2. At [gist.github.com](https://gist.github.com), paste the data into the text box, and **name the file** in the box above it, ending in `.csv` — `class_commute.csv`, not the `gistfile1.txt` GitHub defaults to. StatLens uses the filename as the name of your data, so it shows up in the summary bar, on the axes, and in student downloads.
3. Click **Create public gist** or **Create secret gist** — either works. "Secret" means unlisted, not private: anyone with the link can open it, which is all students need, and it stays off your profile and out of search. Public makes it findable so colleagues can reuse it. Either way, only data you'd be comfortable posting publicly; never student-identifiable data.
4. Click **Raw** and copy the address (it starts with `gist.githubusercontent.com`). Deleting the long revision hash between `/raw/` and the filename makes the link always serve the newest version, so editing the gist updates everyone who has scanned the code. If you rename the file later, update the last segment of the link.
5. In the StatLens tool, go to **Open File/URL**, paste the link, click **Load**.
6. Click **Share** and project the QR code.

A Google Sheet published via *File → Share → Publish to the web → CSV* gives a link that works the same way and updates when the sheet does.

---

## The Dataset Builder

The [Dataset Builder](https://learnlens.org/statlens/data/builder/) is an instructor tool for creating StatLens-compatible dataset files.

1. **Paste or upload** CSV/TSV data
2. **Configure columns** — override auto-detected types, set ordinal level ordering for categorical variables
3. **Add metadata** — display name, description, study context, variable descriptions
4. **Export** — copy JSON to clipboard or download as a `.json` file

### Ordinal Level Ordering

For categorical variables with a meaningful order (Likert scales, education levels, income brackets), you can specify the level order in the **Levels** column of the Column Configuration table. Enter comma-separated values in order:

```
Strongly Disagree, Disagree, Neutral, Agree, Strongly Agree
```

When a dataset with levels is loaded in StatLens, the "Data order" sort option respects this sequence. Without levels, categories appear in first-occurrence order.

---

## Pre-Configuring Tools with URL Parameters

Every StatLens page reads URL parameters to pre-configure its state. This lets you create direct links that open exactly the view you want students to see.

### Common patterns

**Textbook callout** — link students to a specific dataset:
```
https://learnlens.org/statlens/simulate/bootstrap-mean/?dataset=penny_ages
```

**Graded assessment** — add a seed for reproducible output:
```
https://learnlens.org/statlens/simulate/randomization-one-prop/?dataset=opportunity_cost&seed=hw3q5&direction=less
```

**Visual judgment exercise** — hide numeric labels so students must judge from the chart:
```
https://learnlens.org/statlens/explore/one-cat/?dataset=brexit&labels=names
```

**Category ordering exploration** — start with alphabetical sort so students discover frequency ordering is better:
```
https://learnlens.org/statlens/explore/one-cat/?dataset=brexit&sort=alpha
```

**Embedded in an LMS** — compact mode hides navigation chrome:
```
https://learnlens.org/statlens/simulate/bootstrap-mean/?dataset=penny_ages&embed=true
```

**Guided activity** — load a step-by-step instruction panel alongside the tool:
```
https://learnlens.org/statlens/simulate/bootstrap-mean/?activity=bootstrap-explore.json
```

See the full [URL API Reference](url-api.md) for all available parameters.

---

## Presentation Mode

StatLens activity pages support two modes:

- **Discovery mode** (default) — progressive disclosure with gated questions for student self-pacing
- **Presentation mode** — all steps visible, clean interface for instructor projection

Toggle via the settings gear on any activity page, or add `?mode=present` to the URL.

---

## Guided Activities

Activities are JSON files that add a step-by-step instruction panel to any tool page. They're used for in-class walkthroughs and homework explorations.

- **Using activities**: Append `?activity=filename.json` to any tool URL
- **Authoring activities**: See the [Activity Authoring Guide](activity-authoring-guide.md)
- **Activity files**: Stored in [`activities/`](https://learnlens.org/statlens/activities/)

---

## Assessment Integration

### MyOpenMath

MOM homework problems can generate per-student data and build StatLens URLs with `?data=` and `?seed=`. Students run simulations in StatLens and enter results back in MOM. The deterministic PRNG ensures reproducible output for grading.

### Canvas New Quizzes

Pre-computed quiz variants link to StatLens with specific seeds. See [Canvas Integration Report](Canvas_Quiz_StatLens_Integration_Report.md) and [MyOpenMath Investigation](MyOpenMath_Investigation_Report.md) for details.

---

## Quick Reference

| I want to... | Do this |
|---|---|
| Share a custom dataset with students | Build in Dataset Builder → download JSON → share file |
| Get my own data to a whole class at once | Post the CSV to a gist → paste the raw link into **Open File/URL** → **Share** → project the QR code |
| Link students to a pre-loaded tool | Use `?dataset=id` or `?json=url` in the link |
| Hide numbers for a visual exercise | Add `?labels=names` or `?labels=none` |
| Pre-set category ordering | Add `?sort=alpha` or `?sort=freq-desc` |
| Embed in Canvas/Moodle | Add `?embed=true` to the URL |
| Make output reproducible for grading | Add `?seed=some_string` |
| Create a guided walkthrough | Write an activity JSON, link with `?activity=filename.json` |
| Project in class without gates | Add `?mode=present` or use settings gear |