feat: add course stats; fixes #19

Author: nkdem

backend/categories/migrations/0018_coursestats.py

@@ -0,0 +1,28 @@
+# Generated by Django 4.1.13 on 2025-09-26 21:09
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('categories', '0017_2040413_merge_upstream'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='CourseStats',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('course_name', models.CharField(max_length=256)),
+                ('course_code', models.CharField(db_index=True, max_length=12)),
+                ('mean_mark', models.FloatField(blank=True, null=True)),
+                ('std_deviation', models.FloatField(blank=True, null=True)),
+                ('academic_year', models.CharField(max_length=10)),
+            ],
+            options={
+                'ordering': ['course_code', 'academic_year'],
+                'unique_together': {('course_code', 'academic_year')},
+            },
+        ),
+    ]

backend/categories/models.py

@@ -86,3 +86,20 @@ class EuclidCode(models.Model):
     category = models.ForeignKey(
         "Category", related_name="euclid_codes", on_delete=models.CASCADE
     )
+
+
+class CourseStats(models.Model):
+    course_name = models.CharField(max_length=256)
+    course_code = models.CharField(max_length=12, db_index=True)
+    mean_mark = models.FloatField(null=True, blank=True)  # Can be null for N/A values
+    std_deviation = models.FloatField(
+        null=True, blank=True
+    )  # Can be null for N/A values
+    academic_year = models.CharField(max_length=10)  # e.g. "2023-24"
+
+    class Meta:
+        unique_together = ["course_code", "academic_year"]
+        ordering = ["course_code", "academic_year"]
+
+    def __str__(self):
+        return f"{self.course_code} ({self.academic_year}): {self.mean_mark}"

backend/categories/urls.py

@@ -37,4 +37,5 @@
         name="slugfromeuclidcode",
     ),
     path("listeuclidcodes/", views.list_euclid_codes, name="listeuclidcodes"),
+    path("stats/<slug:slug>/", views.get_course_stats, name="course_stats"),
 ]

backend/categories/views.py

@@ -4,7 +4,7 @@
 from django.shortcuts import get_object_or_404
 
 from answers.models import Answer
-from categories.models import Category, MetaCategory, EuclidCode
+from categories.models import Category, MetaCategory, EuclidCode, CourseStats
 from ediauth import auth_check
 from util import response, func_cache
 
@@ -416,3 +416,31 @@ def list_euclid_codes(request):
         for code in codes
     ]
     return response.success(value=res)
+
+
+@response.request_get()
+@auth_check.require_login
+def get_course_stats(request, slug):
+    cat = get_object_or_404(Category, slug=slug)
+    
+    # Get all Euclid codes for this category
+    euclid_codes = list(cat.euclid_codes.all().values_list("code", flat=True))
+    
+    if not euclid_codes:
+        return response.success(value=[])
+    
+    # Get course stats for all Euclid codes associated with this category
+    stats = CourseStats.objects.filter(course_code__in=euclid_codes).order_by('course_code', 'academic_year')
+    
+    res = [
+        {
+            "course_name": stat.course_name,
+            "course_code": stat.course_code,
+            "mean_mark": stat.mean_mark,
+            "std_deviation": stat.std_deviation,
+            "academic_year": stat.academic_year,
+        }
+        for stat in stats
+    ]
+    
+    return response.success(value=res)

backend/testing/management/commands/create_testdata.py

@@ -8,12 +8,13 @@
 from ediauth.models import Profile
 from answers.models import Answer, AnswerSection, Comment, Exam, ExamType
 from documents.models import DocumentType, Document, DocumentFile
-from categories.models import Category, MetaCategory, EuclidCode
+from categories.models import Category, MetaCategory, EuclidCode, CourseStats
 from feedback.models import Feedback
 from filestore.models import Attachment
 from images.models import Image
 from notifications.models import Notification, NotificationSetting, NotificationType
 import os
+import random
 from answers import pdf_utils
 
 
@@ -329,12 +330,87 @@ def create_documents(self):
                     if (i + user.id) % 4 == 0:
                         document.likes.add(user)
 
+    def create_course_stats(self):
+        self.stdout.write("Create course statistics")
+
+        # Generate realistic course names for Informatics courses
+        course_name_patterns = [
+            "Algorithms and Data Structures",
+            "Secure Programming",
+            "Machine Learning",
+            "Software Engineering and Professional Practice",
+            "Introduction to Databases",
+            "Systems Design Project",
+            "Operating Systems",
+            "Human-Computer Interaction",
+            "Reasoning and Agents",
+            "Cyber Security",
+            "Applied Cloud Programming",
+            "Distributed Systems",
+            "Computer Vision",
+        ]
+
+        # Academic years from 2017-18 to 2024-25
+        academic_years = [
+            "2017-18",
+            "2018-19",
+            "2019-20",
+            "2020-21",
+            "2021-22",
+            "2022-23",
+            "2023-24",
+            "2024-25",
+        ]
+
+        objs = []
+
+        # Get all Euclid codes from categories
+        euclid_codes = EuclidCode.objects.all()
+
+        for euclid_code in euclid_codes:
+            # Pick a random course name pattern
+            base_course_name = random.choice(course_name_patterns)
+            course_name = f"{base_course_name} ({euclid_code.category.displayname})"
+
+            # Generate stats for each academic year
+            for year in academic_years:
+                # Generate realistic grade statistics
+                # Mean marks typically range from 45-85, with most courses 55-75
+                base_mean = random.uniform(55, 75)
+
+                # Add some year-to-year variation (-5 to +5)
+                year_variation = random.uniform(-5, 5)
+                mean_mark = max(45, min(85, base_mean + year_variation))
+
+                # Standard deviation typically 10-25, with most 12-20
+                std_deviation = random.uniform(12, 20)
+
+                # Some years might have missing data (simulate N/A values)
+                if random.random() < 0.05:  # 5% chance of missing data
+                    mean_mark = None
+                    std_deviation = None
+
+                objs.append(
+                    CourseStats(
+                        course_name=course_name,
+                        course_code=euclid_code.code,
+                        mean_mark=mean_mark,
+                        std_deviation=std_deviation,
+                        academic_year=year,
+                    )
+                )
+
+        # Bulk create all course stats
+        CourseStats.objects.bulk_create(objs, ignore_conflicts=True)
+        self.stdout.write(f"Created {len(objs)} course statistics entries")
+
     def handle(self, *args, **options):
         self.flush_db()
         self.create_users()
         self.create_images()
         self.create_meta_categories()
         self.create_categories()
+        self.create_course_stats()
         self.create_exam_types()
         self.create_exams()
         self.create_answer_sections()

frontend/src/api/hooks.ts

@@ -7,6 +7,7 @@ import {
   CategoryExam,
   CategoryMetaData,
   CategoryMetaDataMinimal,
+  CourseStats,
   CutVersions,
   ExamMetaData,
   FeedbackEntry,
@@ -594,3 +595,16 @@ export const useRegenerateDocumentAPIKey = (
   documentSlug: string,
   onSuccess?: (res: Document) => void,
 ) => useMutation(() => regenerateDocumentAPIKey(documentSlug), onSuccess);
+
+// Course Stats
+export const loadCourseStats = async (slug: string) => {
+  return (await fetchGet(`/api/category/stats/${slug}/`)).value as CourseStats[];
+};
+
+export const useCourseStats = (slug: string) => {
+  const { error, loading, data } = useRequest(() => loadCourseStats(slug), {
+    cacheKey: `course-stats-${slug}`,
+    refreshDeps: [slug],
+  });
+  return [error, loading, data] as const;
+};