InstantGrade Documentation

Welcome to InstantGrade, an automated evaluation framework for grading Python Jupyter notebooks and Excel spreadsheets. InstantGrade simplifies the assessment process by comparing student submissions against reference solutions and generating comprehensive HTML reports.

Contents

• Installation
  • Requirements
  • Install from PyPI
  • Install from Source
  • Optional Dependencies
  • Verify Installation
  • Dependencies
  • Platform Support
  • Troubleshooting
  • Next Steps
• Quick Start Guide
  • Basic Workflow
  • Your First Evaluation
  • Understanding the Output
  • Excel Example
  • Command-Line Interface
  • What’s Next?
  • Common Use Cases
  • Tips & Best Practices
• Usage Guide
  • Basic Usage
  • Supported File Types
  • Configuration Options
  • Directory Structure
  • Report Format
  • Advanced Features
  • CLI Advanced Usage
  • Environment Variables
  • Best Practices
  • Troubleshooting
  • Next Steps
• Examples
  • Example 1: Basic Data Analysis Assignment
  • Example 2: Excel Spreadsheet Evaluation
  • Example 3: Multi-Assignment Grading
  • Example 4: Custom Report Processing
  • Example 5: Automated Feedback Emails
  • Example 6: Integration with Learning Management System
  • Example 7: Continuous Integration
  • Example 8: Custom Comparison Tolerance
  • Example 9: Batch Processing with Progress
  • Example 10: Machine Learning Assignment
  • Tips for Each Example
  • Next Steps
• API Reference
  • Core Classes
  • Evaluator
  • Ingestion Services
  • Execution Services
  • Comparison Services
  • Reporting Services
  • Utility Functions
  • Command-Line Interface
  • Data Models
  • Exceptions
  • Constants
  • Type Hints
  • Usage Examples
  • Advanced API Usage
  • See Also
• Contributing to InstantGrade
  • Ways to Contribute
  • Getting Started
  • Development Workflow
  • Submitting Changes
  • Reporting Bugs
  • Suggesting Features
  • Documentation
  • Code of Conduct
  • Questions?
  • License
  • Recognition
• Changelog
  • Unreleased
  • 0.1.0 - 2025-12-01
  • Release Notes
  • Future Plans
  • Contributing
  • Links

What is InstantGrade?

InstantGrade is a powerful tool designed for educators and course administrators who need to:

• ✅ Automate grading of Jupyter notebooks and Excel files

• 📊 Compare outputs between student submissions and reference solutions

• 📝 Generate reports showing detailed comparisons and scores

• ⚡ Save time by eliminating manual comparison work

• 🎯 Ensure consistency in grading across multiple submissions

Key Features

🐍 Python Notebook Support

• Execute and compare Jupyter notebooks

• Cell-by-cell output comparison

• Variable state tracking

• Error handling and reporting

📊 Excel File Support

• Compare spreadsheet data

• Support for multiple sheets

• Formula validation

• Cell-by-cell difference highlighting

📈 Comprehensive Reporting

• HTML reports with detailed comparisons

• Visual diff highlighting

• Score calculations

• Execution logs and error tracking

🔧 Flexible Configuration

• Customizable evaluation criteria

• Support for multiple file formats

• Batch processing capabilities

• CLI and Python API

Quick Example

from instantgrade import Evaluator

# Initialize the evaluator
evaluator = Evaluator(
    solution_path="solution.ipynb",
    submissions_dir="submissions/",
    report_dir="reports/"
)

# Run evaluation
evaluator.run()

# Results are saved in reports/ directory

Use Cases

Education

• Grade programming assignments

• Evaluate data analysis projects

• Assess Excel spreadsheet exercises

• Provide detailed feedback to students

Training

• Evaluate workshop exercises

• Check coding bootcamp submissions

• Assess certification exams

Research

• Validate experimental results

• Compare data analysis outputs

• Reproduce computational research

Get Started

Community & Support

• GitHub: chandraveshchaudhari/instantgrade

• Issues: Report bugs or request features on GitHub Issues

• PyPI: pypi.org/project/instantgrade

License

InstantGrade is released under the MIT License. See the LICENSE file for details.