BSOS Social Science Data Repository
BSOS Instructor Guide

Use the repository like a classroom workflow, not a flat file cabinet.

This page is separate from the about section and is built for teaching decisions. It explains how to move from a course goal, to a dataset shortlist, to metadata review, to methodology fit, to a classroom-ready package of files, previews, and links. The dashboard now groups records more clearly by region and category, while advanced query tools stay optional.

Browse datasets Open dashboard Back to about
Teaching themes Metadata and documentation Method tags Live previews and quality signals
Instructor guide panels

Open one teaching surface at a time instead of scrolling through the entire guide.

Choose the part of the workflow you need right now. Each view keeps only the relevant explainer visible, while the click-driven workflow, metadata, and method details continue to update inside the active panel.

Minimal guide

Use a simple public workflow first

Most teaching prep only needs three moves: narrow the collection, inspect one dataset page, then carry the key file and notes into class.

01

Browse by category and region

Use the dashboard or dataset browse page to reduce the catalog to a short list instead of starting from raw filenames.

  • Start with a course topic, method, or comparison question.
  • Use region and category groupings to remove irrelevant records quickly.
02

Open one dataset page and inspect the preview

The dataset page should answer the teaching question directly: what this record is, what the important files are, and whether students can read it without extra cleanup.

  • Read the title, context, and updated date first.
  • Use the preview table and support docs before downloading.
03

Carry the key file and notes into class

Share the data file together with the codebook, support notes, and dataset URL so students can retrace the same public workflow you used.

  • Prefer the featured data file instead of a long undifferentiated resource list.
  • Keep the dataset page link with the download so provenance stays visible.
Optional advanced SQL and API tips
Read only

Use the public browser query first

The default advanced step is still a browser tool, not local SQL. Use the dashboard's read-only query view when you need filtered rows or CSV export.

Dashboard route: /analytics/
Use the Browse Data tab or the live table query panel inside a dataset workspace.
API

Pull catalog metadata from CKAN

Use the CKAN action API when you need programmatic access to dataset metadata, resource URLs, or search results.

/api/3/action/package_search?rows=25&q=crime
/api/3/action/package_show?id=dmv-crime-incidents-2019-2021-dataset
Local only

Use SQL only for pilot maintenance

SQL is optional and only relevant on the local pilot machine. It is useful for validation, export checks, and internal QA, not for normal classroom browsing.

SELECT *
FROM bsos_browser.materialized_dataset_inventory
ORDER BY dataset_name
LIMIT 25;

Default teaching flow: stay on the public dataset and dashboard pages. Drop to API or SQL only when you need automation or pilot maintenance.

Interactive workflow

Follow the instructor journey from question to classroom use

Click any move in the sequence below. The active panel explains what you should do and what the repository is doing in the background.

Animated path

Teaching workflow

Let the guide auto-rotate or lock onto a stage by clicking it.

Dataset page anatomy

Understand the surfaces you should inspect before assigning a dataset

The visual map below mirrors the main teaching-facing areas of a dataset page: teaching context, metrics, preview, documentation, and provenance.

Visual explainer

Dataset page map

Each block opens a focused explanation.

dataset page
Metadata and methodology

Read the record, then match the method to the assignment

These explainers separate metadata quality from methodological fit so you can decide both whether a dataset is usable and what kind of class work it supports.

Metadata explorer

What to inspect in the record

Focus on the fields that reduce prep time and ambiguity.

Method fit

How to use method signals

Choose a method family to see what it is good for and what to verify.

Use cases

Three ways to turn the same repository into course material

These are common teaching paths: a quick live demo, a methods lab, or a longer project sequence.

Fast path

Quick lecture demo

Choose one dataset with a strong preview table and a clear note block, then use the page itself as the live handout.

  • Use dataset browse to narrow by theme or method.
  • Open the preview and read the Teaching Context out loud.
  • Give students the dataset URL instead of a detached file.
Open a preview-friendly example
Methods lab

Guided methods assignment

Use metadata, method tags, and the Instructor Snapshot to decide whether the dataset is strong enough for a specific analytic technique.

  • Compare two candidate datasets in the dashboard first.
  • Check row counts, column types, support docs, and provenance.
  • Download the data plus the codebook as a single teaching bundle.
Compare records in the dashboard
Longer arc

Project-based sequence

Give students a repeatable discovery process: browse, inspect, compare, document, and justify their dataset choice before analysis begins.

  • Start from theme and method filters rather than assigning a file immediately.
  • Require students to defend their choice with metadata and preview evidence.
  • Use dashboard context to support comparison and reflection.
Start from dataset browse