NuAnalytics

Version 0.5.4

NuAnalytics is a Rust-based tool for analyzing computer science curricula. It computes detailed metrics about curriculum structure including complexity, blocking relationships, delay paths, and centrality measures to help understand how courses are organized and their impact on students.

It is based off the work of Greg Heileman, and CurricularAnalytics.org. Current version provides command line capabilities for curriculum analysis, degree program validation, and comprehensive reporting.

0.4.0 has two breaking changes (the degree command became a subcommand dispatcher and database access now requires login on every call). See CHANGELOG.md for the full migration checklist before upgrading from 0.3.x.

Features

• Curriculum Analysis: Parse CSV-formatted curriculum files and analyze course dependencies
• Degree Program Validation: Validate YAML-based degree programs with comprehensive checks
• Degree Plan Generation: Generate all possible degree plans and compute aggregate statistics
• Unified JSON Degree Format (new in 0.4.1): Author and analyze degrees as JSON as well as YAML — every degree subcommand auto-detects the format on load. degree convert turns ai-landscape program JSON into the unified format, and degree schema emits its JSON Schema for downstream validation.
• Parallel Batch Analysis (new in 0.4.1): degree analyze -j N runs a process-isolated worker pool (default 8) so a pathological degree (e.g. a full-catalog scrape) can't take down the whole batch; failures are logged and the run continues.
• Degree Trim (new in 0.4.0): Collapse a degree to one walkable shortest-path-per-course variant — useful for visualisation and downstream tools that don't reason about alternatives. Protected major subjects keep all options; pattern pools survive orphan pruning. Accepts YAML or JSON and round-trips the input format.
• Gen-Ed Tracking: Track how major courses satisfy general education requirements
• Graph Analysis: Build and analyze course prerequisite graphs
• Curriculum Auditing: Identify issues like missing prerequisites and complex prerequisite chains
• Metric Computation: Calculate comprehensive metrics including:
  • Complexity: Measure of course density and impact on overall curriculum
  • Blocking: Count of courses directly blocked by a given course
  • Delay: Longest path from a course to course with no prerequisites
  • Centrality: Importance of a course in the curriculum network
• Report Generation: Create visual reports in multiple formats:
  • HTML: Interactive web-based reports with box plots and statistics
  • PDF: Print-ready reports via Chrome/Chromium conversion
  • Markdown: Text-based reports for documentation
• Term Scheduling: Automatic course scheduling respecting prerequisites and credit limits
• Configuration Management: Flexible configuration system with CLI overrides
• MCP Server (optional): AI model integration for interactive degree building via Model Context Protocol. Degree tools accept YAML, unified JSON, or raw ai-landscape JSON; convert_degree (new in 0.4.1) converts ai-landscape JSON to the unified format and get_degree_json_schema (new in 0.4.1) returns the machine schema. The trim_degree tool pipes a fresh cache:<hash> handle back for chained validate_degree / audit_degree calls.
• Authenticated Database Access (behavior change in 0.4.0): Supabase reads and writes both require a logged-in user (nuanalytics db login); session tokens auto-refresh.
• Degree Database Import & Stored Programs (new in 0.5.0): Import degree reports into a normalized, queryable program store (nuanalytics db import, or the import_degree MCP tool) — one report becomes a program plus its courses, flattened requirement tree, and analysis run, alongside the lossless source document. Stored programs can be analyzed straight from the database with degree analyze --from-db <NAME>. See Database Setup.

Quick Start

Installation

Stable (crates.io) - Recommended

Install the CLI via Cargo:

cargo install nu-analytics

This provides the nuanalytics binary globally.

From Git (for latest)

Install directly from Git:

cargo install --git https://github.com/NeuCurricularAnalytics/NuAnalytics --bin nuanalytics

Building

cargo build --release

The executable will be at target/release/nuanalytics.

Running (installed)

Analyze a curriculum CSV file and generate both metrics CSV and HTML report:

nuanalytics planner path/to/curriculum.csv

Generate only a PDF report:

nuanalytics planner path/to/curriculum.csv --no-csv --report-format pdf

Generate only CSV metrics (no report):

nuanalytics planner path/to/curriculum.csv --no-report

Analyze a degree program (generates plans, metrics, and reports):

nuanalytics degree analyze samples/degrees/csu-cs-bscs-general.yaml

Validate a degree program only:

nuanalytics degree validate samples/degrees/csu-cs-bscs-general.yaml

Audit a degree program for issues:

nuanalytics degree audit samples/degrees/csu-cs-bscs-general.yaml

Trim a degree to one walkable path per course (collapses alternatives outside the major):

nuanalytics degree trim samples/degrees/csu-cs-bscs-general.yaml

Scaffold a new research project (creates degrees/, plans/, MCP wiring, and three SKILL.md skills for Claude Code under .claude/):

nuanalytics init my-research-project
cd my-research-project && claude

Sign in to the Supabase-backed IPEDS database (required for any DB tool — both reads and writes):

nuanalytics db login
nuanalytics db status

Manage configuration:

nuanalytics config get level
nuanalytics config set level debug
nuanalytics config set degree_analysis.max_plans 5000

Configuration

NuAnalytics uses a three-tier configuration system with the following precedence (highest to lowest):

1. Command-line arguments - Override any config value for a single run
2. Local config (nuanalytics.toml in current directory) - Project-specific settings
3. Home config (~/.config/nuanalytics/config.toml) - User-wide defaults
4. Built-in defaults - Fallback values

This allows you to set project-specific configurations by creating a nuanalytics.toml file in your project directory:

# nuanalytics.toml - Local project configuration
[paths]
metrics_dir = "./metrics"
reports_dir = "./reports"

[degree_analysis]
max_plans = 500
sampling_strategy = "stratified"

Documentation

• Config Command - Configure NuAnalytics settings (logging, database, output directories, degree analysis)
• Planner Command - Analyze curricula for a degree plan, compute metrics, and generate reports
• Degree Command - Validate, analyze, and audit degree program YAML files
• MCP Server - AI model integration via Model Context Protocol (optional feature)

Development

If you are contributing or working locally, see Development.md for cargo run workflows and setup.

Project Structure

├── src/
│   ├── cli/              # Command-line interface
│   │   ├── main.rs       # CLI entry point
│   │   ├── args.rs       # Argument definitions (clap)
│   │   └── commands/     # Command handlers
│   ├── core/             # Core analysis engine
│   │   ├── config.rs     # Configuration management
│   │   ├── metrics.rs    # Metric computation algorithms
│   │   ├── metrics_export.rs  # CSV export functionality
│   │   ├── models/       # Data structures (Course, Degree, Plan, School, DAG)
│   │   ├── degree/       # Degree program analysis
│   │   │   ├── gen_ed_tracker.rs  # Gen-ed satisfaction tracking
│   │   │   ├── plan_generator.rs  # Plan enumeration
│   │   │   └── plan_validation.rs # Plan validation
│   │   ├── planner/      # CSV parsing and planning
│   │   └── report/       # Report generation
│   │       ├── formats/  # HTML, PDF, Markdown reporters
│   │       └── term_scheduler.rs  # Course scheduling algorithm
│   ├── logger/           # Internal logging module
│   └── lib.rs            # Library exports
├── tests/                # Integration and unit tests
├── docs/                 # Documentation
└── Cargo.toml            # Project manifest

Report Formats

HTML Reports

Self-contained HTML files with:

• Interactive course dependency visualization
• Box plots for curriculum metrics distribution
• Term-by-term schedule view
• Detailed metrics table
• Plan comparison (shortest/longest/random samples)

PDF Reports

Generated via headless Chrome/Chromium:

• Same content as HTML reports
• Print-optimized layout
• Requires Chrome, Chromium, or custom converter

Markdown Reports

Simple text-based reports suitable for:

• Documentation systems
• Version control diffing
• Email attachments

License

See LICENSE file for details.