stats for projects + dashboard page

Author: alexeygrigorev

AGENTS.md

@@ -0,0 +1 @@
+Use uv for dependency management and running scripts within the project

courses/admin/projects.py

@@ -3,14 +3,16 @@
 
 from django.contrib import messages
 
-from courses.models import Project, ReviewCriteria
+from courses.models import Project, ReviewCriteria, ProjectState
 
 from courses.projects import (
     assign_peer_reviews_for_project,
     score_project,
     ProjectActionStatus,
 )
 
+from courses.scoring import calculate_project_statistics
+
 
 def assign_peer_reviews_for_project_admin(
     modeladmin, request, queryset
@@ -48,11 +50,38 @@ def score_projects_admin(modeladmin, request, queryset):
 score_projects_admin.short_description = "Score projects"
 
 
+def calculate_statistics_selected_projects(
+    modeladmin, request, queryset
+):
+    for project in queryset:
+        if project.state != ProjectState.COMPLETED.value:
+            modeladmin.message_user(
+                request,
+                f"Cannot calculate statistics for {project} "
+                "because it has not been completed",
+                level=messages.WARNING,
+            )
+            continue
+
+        calculate_project_statistics(project, force=True)
+
+        message = f"Statistics calculated for {project}"
+        modeladmin.message_user(
+            request, message, level=messages.SUCCESS
+        )
+
+
+calculate_statistics_selected_projects.short_description = (
+    "Calculate statistics"
+)
+
+
 @admin.register(Project)
 class ProjectAdmin(ModelAdmin):
     actions = [
         assign_peer_reviews_for_project_admin,
         score_projects_admin,
+        calculate_statistics_selected_projects,
     ]
 
     list_display = ["title", "course", "state"]

courses/migrations/0022_projectstatistics.py

@@ -0,0 +1,59 @@
+# Generated by Django 5.2.4 on 2025-09-12 09:16
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('courses', '0021_course_min_projects_to_pass'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='ProjectStatistics',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('total_submissions', models.IntegerField(default=0)),
+                ('min_project_score', models.IntegerField(blank=True, null=True)),
+                ('max_project_score', models.IntegerField(blank=True, null=True)),
+                ('avg_project_score', models.FloatField(blank=True, null=True)),
+                ('median_project_score', models.FloatField(blank=True, null=True)),
+                ('q1_project_score', models.FloatField(blank=True, null=True)),
+                ('q3_project_score', models.FloatField(blank=True, null=True)),
+                ('min_project_learning_in_public_score', models.IntegerField(blank=True, null=True)),
+                ('max_project_learning_in_public_score', models.IntegerField(blank=True, null=True)),
+                ('avg_project_learning_in_public_score', models.FloatField(blank=True, null=True)),
+                ('median_project_learning_in_public_score', models.FloatField(blank=True, null=True)),
+                ('q1_project_learning_in_public_score', models.FloatField(blank=True, null=True)),
+                ('q3_project_learning_in_public_score', models.FloatField(blank=True, null=True)),
+                ('min_peer_review_score', models.IntegerField(blank=True, null=True)),
+                ('max_peer_review_score', models.IntegerField(blank=True, null=True)),
+                ('avg_peer_review_score', models.FloatField(blank=True, null=True)),
+                ('median_peer_review_score', models.FloatField(blank=True, null=True)),
+                ('q1_peer_review_score', models.FloatField(blank=True, null=True)),
+                ('q3_peer_review_score', models.FloatField(blank=True, null=True)),
+                ('min_peer_review_learning_in_public_score', models.IntegerField(blank=True, null=True)),
+                ('max_peer_review_learning_in_public_score', models.IntegerField(blank=True, null=True)),
+                ('avg_peer_review_learning_in_public_score', models.FloatField(blank=True, null=True)),
+                ('median_peer_review_learning_in_public_score', models.FloatField(blank=True, null=True)),
+                ('q1_peer_review_learning_in_public_score', models.FloatField(blank=True, null=True)),
+                ('q3_peer_review_learning_in_public_score', models.FloatField(blank=True, null=True)),
+                ('min_total_score', models.IntegerField(blank=True, null=True)),
+                ('max_total_score', models.IntegerField(blank=True, null=True)),
+                ('avg_total_score', models.FloatField(blank=True, null=True)),
+                ('median_total_score', models.FloatField(blank=True, null=True)),
+                ('q1_total_score', models.FloatField(blank=True, null=True)),
+                ('q3_total_score', models.FloatField(blank=True, null=True)),
+                ('min_time_spent', models.FloatField(blank=True, null=True)),
+                ('max_time_spent', models.FloatField(blank=True, null=True)),
+                ('avg_time_spent', models.FloatField(blank=True, null=True)),
+                ('median_time_spent', models.FloatField(blank=True, null=True)),
+                ('q1_time_spent', models.FloatField(blank=True, null=True)),
+                ('q3_time_spent', models.FloatField(blank=True, null=True)),
+                ('last_calculated', models.DateTimeField(auto_now=True)),
+                ('project', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, related_name='statistics', to='courses.project')),
+            ],
+        ),
+    ]

courses/models/project.py

@@ -220,3 +220,139 @@ class ProjectEvaluationScore(models.Model):
 
     def __str__(self):
         return f"Score: {self.score} for submission by {self.submission.id}"
+
+
+class ProjectStatistics(models.Model):
+    project = models.OneToOneField(
+        Project, on_delete=models.CASCADE, related_name="statistics"
+    )
+
+    total_submissions = models.IntegerField(default=0)
+
+    # Fields for project_score
+    min_project_score = models.IntegerField(null=True, blank=True)
+    max_project_score = models.IntegerField(null=True, blank=True)
+    avg_project_score = models.FloatField(null=True, blank=True)
+    median_project_score = models.FloatField(null=True, blank=True)
+    q1_project_score = models.FloatField(null=True, blank=True)
+    q3_project_score = models.FloatField(null=True, blank=True)
+
+    # Fields for project_learning_in_public_score
+    min_project_learning_in_public_score = models.IntegerField(null=True, blank=True)
+    max_project_learning_in_public_score = models.IntegerField(null=True, blank=True)
+    avg_project_learning_in_public_score = models.FloatField(null=True, blank=True)
+    median_project_learning_in_public_score = models.FloatField(null=True, blank=True)
+    q1_project_learning_in_public_score = models.FloatField(null=True, blank=True)
+    q3_project_learning_in_public_score = models.FloatField(null=True, blank=True)
+
+    # Fields for peer_review_score
+    min_peer_review_score = models.IntegerField(null=True, blank=True)
+    max_peer_review_score = models.IntegerField(null=True, blank=True)
+    avg_peer_review_score = models.FloatField(null=True, blank=True)
+    median_peer_review_score = models.FloatField(null=True, blank=True)
+    q1_peer_review_score = models.FloatField(null=True, blank=True)
+    q3_peer_review_score = models.FloatField(null=True, blank=True)
+
+    # Fields for peer_review_learning_in_public_score
+    min_peer_review_learning_in_public_score = models.IntegerField(null=True, blank=True)
+    max_peer_review_learning_in_public_score = models.IntegerField(null=True, blank=True)
+    avg_peer_review_learning_in_public_score = models.FloatField(null=True, blank=True)
+    median_peer_review_learning_in_public_score = models.FloatField(null=True, blank=True)
+    q1_peer_review_learning_in_public_score = models.FloatField(null=True, blank=True)
+    q3_peer_review_learning_in_public_score = models.FloatField(null=True, blank=True)
+
+    # Fields for total_score
+    min_total_score = models.IntegerField(null=True, blank=True)
+    max_total_score = models.IntegerField(null=True, blank=True)
+    avg_total_score = models.FloatField(null=True, blank=True)
+    median_total_score = models.FloatField(null=True, blank=True)
+    q1_total_score = models.FloatField(null=True, blank=True)
+    q3_total_score = models.FloatField(null=True, blank=True)
+
+    # Fields for time_spent
+    min_time_spent = models.FloatField(null=True, blank=True)
+    max_time_spent = models.FloatField(null=True, blank=True)
+    avg_time_spent = models.FloatField(null=True, blank=True)
+    median_time_spent = models.FloatField(null=True, blank=True)
+    q1_time_spent = models.FloatField(null=True, blank=True)
+    q3_time_spent = models.FloatField(null=True, blank=True)
+
+    last_calculated = models.DateTimeField(auto_now=True)
+
+    def get_value(self, field_name, stats_type):
+        attribute_name = f"{stats_type}_{field_name}"
+        return getattr(self, attribute_name)
+
+    def get_stat_fields(self):
+        results = []
+
+        results.append(
+            ("Project score", [
+                (self.min_project_score, "Minimum", "fas fa-arrow-down"),
+                (self.max_project_score, "Maximum", "fas fa-arrow-up"),
+                (self.avg_project_score, "Average", "fas fa-equals"),
+                (self.q1_project_score, "25th Percentile", "fas fa-percentage"),
+                (self.median_project_score, "Median", "fas fa-percentage"),
+                (self.q3_project_score, "75th Percentile", "fas fa-percentage"),
+            ], 'fas fa-project-diagram')
+        )
+
+        results.append(
+            ("Project learning in public score", [
+                (self.min_project_learning_in_public_score, "Minimum", "fas fa-arrow-down"),
+                (self.max_project_learning_in_public_score, "Maximum", "fas fa-arrow-up"),
+                (self.avg_project_learning_in_public_score, "Average", "fas fa-equals"),
+                (self.q1_project_learning_in_public_score, "25th Percentile", "fas fa-percentage"),
+                (self.median_project_learning_in_public_score, "Median", "fas fa-percentage"),
+                (self.q3_project_learning_in_public_score, "75th Percentile", "fas fa-percentage"),
+            ], 'fas fa-globe')
+        )
+
+        results.append(
+            ("Peer review score", [
+                (self.min_peer_review_score, "Minimum", "fas fa-arrow-down"),
+                (self.max_peer_review_score, "Maximum", "fas fa-arrow-up"),
+                (self.avg_peer_review_score, "Average", "fas fa-equals"),
+                (self.q1_peer_review_score, "25th Percentile", "fas fa-percentage"),
+                (self.median_peer_review_score, "Median", "fas fa-percentage"),
+                (self.q3_peer_review_score, "75th Percentile", "fas fa-percentage"),
+            ], 'fas fa-users')
+        )
+
+        results.append(
+            ("Peer review learning in public score", [
+                (self.min_peer_review_learning_in_public_score, "Minimum", "fas fa-arrow-down"),
+                (self.max_peer_review_learning_in_public_score, "Maximum", "fas fa-arrow-up"),
+                (self.avg_peer_review_learning_in_public_score, "Average", "fas fa-equals"),
+                (self.q1_peer_review_learning_in_public_score, "25th Percentile", "fas fa-percentage"),
+                (self.median_peer_review_learning_in_public_score, "Median", "fas fa-percentage"),
+                (self.q3_peer_review_learning_in_public_score, "75th Percentile", "fas fa-percentage"),
+            ], 'fas fa-share-alt')
+        )
+
+        results.append(
+            ("Total score", [
+                (self.min_total_score, "Minimum", "fas fa-arrow-down"),
+                (self.max_total_score, "Maximum", "fas fa-arrow-up"),
+                (self.avg_total_score, "Average", "fas fa-equals"),
+                (self.q1_total_score, "25th Percentile", "fas fa-percentage"),
+                (self.median_total_score, "Median", "fas fa-percentage"),
+                (self.q3_total_score, "75th Percentile", "fas fa-percentage"),
+            ], 'fas fa-star')
+        )
+
+        results.append(
+            ("Time spent on project", [
+                (self.min_time_spent, "Minimum", "fas fa-arrow-down"),
+                (self.max_time_spent, "Maximum", "fas fa-arrow-up"),
+                (self.avg_time_spent, "Average", "fas fa-equals"),
+                (self.q1_time_spent, "25th Percentile", "fas fa-percentage"),
+                (self.median_time_spent, "Median", "fas fa-percentage"),
+                (self.q3_time_spent, "75th Percentile", "fas fa-percentage"),
+            ], 'fas fa-clock')
+        )
+
+        return results
+
+    def __str__(self):
+        return f"Statistics for {self.project.slug}"

courses/scoring.py

@@ -24,6 +24,8 @@
     Enrollment,
     Project,
     ProjectSubmission,
+    ProjectStatistics,
+    ProjectState,
 )
 
 
@@ -455,4 +457,93 @@ def calculate_homework_statistics(homework, force=False):
 
         stats.save()
 
+    return stats
+
+
+def calculate_raw_project_statistics(project):
+    submissions = ProjectSubmission.objects.filter(project=project)
+
+    total_submissions = submissions.count()
+
+    stats = {"total_submissions": total_submissions}
+
+    nones = {
+        "min": None,
+        "max": None,
+        "avg": None,
+        "q1": None,
+        "median": None,
+        "q3": None,
+    }
+
+    fields = [
+        "project_score",
+        "project_learning_in_public_score",
+        "peer_review_score",
+        "peer_review_learning_in_public_score",
+        "total_score",
+        "time_spent",
+    ]
+
+    for field in fields:
+        values = list(
+            submissions.exclude(
+                **{f"{field}__isnull": True}
+            ).values_list(field, flat=True)
+        )
+
+        if not values or len(values) < 3:
+            stats[field] = nones
+            continue
+
+        quantiles = statistics.quantiles(
+            values, n=4, method="inclusive"
+        )
+
+        stats[field] = {
+            "min": min(values),
+            "max": max(values),
+            "avg": statistics.mean(values),
+            "q1": quantiles[0],
+            "median": quantiles[1],
+            "q3": quantiles[2],
+        }
+
+    return stats
+
+
+def calculate_project_statistics(project, force=False):
+    if project.state != ProjectState.COMPLETED.value:
+        raise ValueError(
+            f"Cannot calculate statistics for uncompleted project {project}"
+        )
+
+    stats, created = ProjectStatistics.objects.get_or_create(
+        project=project
+    )
+
+    if force or created:
+        calculated_stats = calculate_raw_project_statistics(project)
+
+        stats.total_submissions = calculated_stats["total_submissions"]
+
+        for field in [
+            "project_score",
+            "project_learning_in_public_score",
+            "peer_review_score",
+            "peer_review_learning_in_public_score",
+            "total_score",
+            "time_spent",
+        ]:
+            field_stats = calculated_stats[field]
+
+            setattr(stats, f"min_{field}", field_stats["min"])
+            setattr(stats, f"max_{field}", field_stats["max"])
+            setattr(stats, f"avg_{field}", field_stats["avg"])
+            setattr(stats, f"median_{field}", field_stats["median"])
+            setattr(stats, f"q1_{field}", field_stats["q1"])
+            setattr(stats, f"q3_{field}", field_stats["q3"])
+
+        stats.save()
+
     return stats

courses/templates/courses/course.html

@@ -19,6 +19,7 @@ <h2>{{ course.title }}</h2>
     {% if course.first_homework_scored %}
       <a class="btn btn-primary" href="{% url 'leaderboard' course.slug %}" role="button">Course leaderboard</a>
     {% endif %}
+    <a class="btn btn-secondary" href="{% url 'dashboard' course.slug %}" role="button">Course dashboard</a>
     {% if is_authenticated %}
       <a class="btn btn-info" href="{% url 'enrollment' course.slug %}" role="button">Edit course profile</a>
     {% endif %}