Make ranking weights modifiable via singleton

Author: julianweng

backend/clubs/management/commands/rank.py

@@ -7,7 +7,39 @@
 from django.db.models import DurationField, ExpressionWrapper, F
 from django.utils import timezone
 
-from clubs.models import Club, ClubFair, EventShowing, Membership
+from clubs.models import Club, ClubFair, EventShowing, Membership, RankingWeights
+
+
+# Default weight values mirroring the historic constant scoring system
+DEFAULT_WEIGHTS = {
+    "inactive_penalty": -1000,
+    "favorites_per": 1 / 25,
+    "tags_good": 15,
+    "tags_many": 7,
+    "officer_bonus": 15,
+    "member_base": 10,
+    "member_per": 1 / 10,
+    "logo_bonus": 15,
+    "subtitle_bad": -10,
+    "subtitle_good": 5,
+    "images_bonus": 3,
+    "desc_short": 25,
+    "desc_med": 10,
+    "desc_long": 10,
+    "fair_bonus": 10,
+    "application_bonus": 25,
+    "today_event_base": 10,
+    "today_event_good": 10,
+    "week_event_base": 5,
+    "week_event_good": 5,
+    "email_bonus": 10,
+    "social_bonus": 10,
+    "howto_penalty": -30,
+    "outdated_penalty": -10,
+    "testimonial_one": 10,
+    "testimonial_three": 5,
+    "random_scale": 25,
+}
 
 
 class Command(BaseCommand):
@@ -62,6 +94,16 @@ def set_recruiting_statuses(self):
     def rank(self):
         count = 0
 
+        # Retrieve ranking weights singleton
+        weights = RankingWeights.get()
+
+        def _w(key):
+            """Fetch weight: RankingWeights field ➔ DEFAULT_WEIGHTS ➔ 1.0."""
+            val = getattr(weights, key, None)
+            if val is not None:
+                return val
+            return DEFAULT_WEIGHTS.get(key, 1.0)
+
         clubs = Club.objects.prefetch_related(
             "favorite_set",
             "tags",
@@ -77,74 +119,74 @@ def rank(self):
 
             # inactive clubs get deprioritized
             if not club.active:
-                ranking -= 1000
+                ranking += _w("inactive_penalty")
 
             # small points for favorites
-            ranking += club.favorite_set.count() / 25
+            ranking += club.favorite_set.count() * _w("favorites_per")
 
             # points for minimum amount of tags
             tags = club.tags.count()
-            if tags >= 3 and tags <= 7:
-                ranking += 15
+            if 3 <= tags <= 7:
+                ranking += _w("tags_good")
             elif tags > 7:
-                ranking += 7
+                ranking += _w("tags_many")
 
             # lots of points for officers
             officers = club.membership_set.filter(
                 active=True, role__lte=Membership.ROLE_OFFICER
             ).count()
             if officers >= 3:
-                ranking += 15
+                ranking += _w("officer_bonus")
 
             # ordinary members give even more points
             members = club.membership_set.filter(
                 active=True, role__gte=Membership.ROLE_MEMBER
             ).count()
             if members >= 3:
-                ranking += 10
-            ranking += members / 10
+                ranking += _w("member_base")
+            ranking += members * _w("member_per")
 
             # points for logo
             if club.image is not None:
-                ranking += 15
+                ranking += _w("logo_bonus")
 
             # points for subtitle
             subtitle = club.subtitle.strip()
             if subtitle.lower() == "your subtitle here":
-                ranking -= 10
+                ranking += _w("subtitle_bad")
             elif len(subtitle) > 3:
-                ranking += 5
+                ranking += _w("subtitle_good")
 
             # images in description? awesome
             if "<img" in club.description or "<iframe" in club.description:
-                ranking += 3
+                ranking += _w("images_bonus")
 
             # points for longer descriptions
             cleaned_description = bleach.clean(
                 club.description, tags=[], attributes={}, styles=[], strip=True
             ).strip()
 
             if len(cleaned_description) > 25:
-                ranking += 25
+                ranking += _w("desc_short")
 
             if len(cleaned_description) > 250:
-                ranking += 10
+                ranking += _w("desc_med")
 
             if len(cleaned_description) > 1000:
-                ranking += 10
+                ranking += _w("desc_long")
 
             # points for fair
             now = timezone.now()
             if ClubFair.objects.filter(
                 end_time__gte=now, participating_clubs=club
             ).exists():
-                ranking += 10
+                ranking += _w("fair_bonus")
 
             # points for club applications
             if club.clubapplication_set.filter(
                 application_start_time__lte=now, application_end_time__gte=now
             ).exists():
-                ranking += 25
+                ranking += _w("application_bonus")
 
             # points for events
             # Get all events with showings today
@@ -172,15 +214,15 @@ def rank(self):
                 )
 
                 if short_showings:
-                    ranking += 10
+                    ranking += _w("today_event_base")
                     # Check for events with good descriptions and images
                     if all(
                         len(e.description) >= 3
                         and e.description not in {"Replace this description!"}
                         and e.image is not None
                         for e in today_events
                     ):
-                        ranking += 10
+                        ranking += _w("today_event_good")
 
             # Get all events with showings in the next week
             close_showings = EventShowing.objects.filter(
@@ -207,19 +249,19 @@ def rank(self):
                 )
 
                 if short_showings:
-                    ranking += 5
+                    ranking += _w("week_event_base")
                     # Check for events with good descriptions and images
                     if all(
                         len(e.description) > 3
                         and e.description not in {"Replace this description!"}
                         and e.image is not None
                         for e in close_events
                     ):
-                        ranking += 5
+                        ranking += _w("week_event_good")
 
             # points for public contact email
             if club.email and club.email_public:
-                ranking += 10
+                ranking += _w("email_bonus")
 
             # points for social links
             social_fields = [
@@ -237,28 +279,28 @@ def rank(self):
             ]
             has_fields = [field for field in social_fields if field]
             if len(has_fields) >= 2:
-                ranking += 10
+                ranking += _w("social_bonus")
 
             # points for how to get involved
             if len(club.how_to_get_involved.strip()) <= 3:
-                ranking -= 30
+                ranking += _w("howto_penalty")
 
             # points for updated
             if club.updated_at < now - datetime.timedelta(days=30 * 8):
-                ranking -= 10
+                ranking += _w("outdated_penalty")
 
             # points for testimonials
             num_testimonials = club.testimonials.count()
             if num_testimonials >= 1:
-                ranking += 10
+                ranking += _w("testimonial_one")
             if num_testimonials >= 3:
-                ranking += 5
+                ranking += _w("testimonial_three")
 
             # random number, mostly shuffles similar clubs with average of 25 points
             # but with long right tail to periodically feature less popular clubs
             # given ~700 active clubs, multiplier c, expected # clubs with rand > cd
             # is 257, 95, 35, 13, 5, 2, 1 for c = 1, 2, 3, 4, 5, 6, 7
-            ranking += np.random.standard_exponential() * 25
+            ranking += np.random.standard_exponential() * _w("random_scale")
 
             club.rank = floor(ranking)
             club.skip_history_when_saving = True

backend/clubs/migrations/0124_rankingweights.py

@@ -0,0 +1,51 @@
+# Generated by Django 5.2.4 on 2025-08-05 03:51
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('clubs', '0123_category_eligibility_club_category_and_more'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='RankingWeights',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('inactive_penalty', models.FloatField(default=-1000)),
+                ('favorites_per', models.FloatField(default=0.04)),
+                ('tags_good', models.FloatField(default=15)),
+                ('tags_many', models.FloatField(default=7)),
+                ('officer_bonus', models.FloatField(default=15)),
+                ('member_base', models.FloatField(default=10)),
+                ('member_per', models.FloatField(default=0.1)),
+                ('logo_bonus', models.FloatField(default=15)),
+                ('subtitle_bad', models.FloatField(default=-10)),
+                ('subtitle_good', models.FloatField(default=5)),
+                ('images_bonus', models.FloatField(default=3)),
+                ('desc_short', models.FloatField(default=25)),
+                ('desc_med', models.FloatField(default=10)),
+                ('desc_long', models.FloatField(default=10)),
+                ('fair_bonus', models.FloatField(default=10)),
+                ('application_bonus', models.FloatField(default=25)),
+                ('today_event_base', models.FloatField(default=10)),
+                ('today_event_good', models.FloatField(default=10)),
+                ('week_event_base', models.FloatField(default=5)),
+                ('week_event_good', models.FloatField(default=5)),
+                ('email_bonus', models.FloatField(default=10)),
+                ('social_bonus', models.FloatField(default=10)),
+                ('howto_penalty', models.FloatField(default=-30)),
+                ('outdated_penalty', models.FloatField(default=-10)),
+                ('testimonial_one', models.FloatField(default=10)),
+                ('testimonial_three', models.FloatField(default=5)),
+                ('random_scale', models.FloatField(default=25)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('updated_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='modified_ranking_weights', to=settings.AUTH_USER_MODEL)),
+            ],
+        ),
+    ]

backend/clubs/models.py

@@ -39,6 +39,62 @@
 types_regex = re.compile(r"\s*<!--\s*TYPES:\s*(.*?)\s*-->", re.DOTALL)
 
 
+class RankingWeights(models.Model):
+    """Singleton storing weighting factors for club ranking."""
+
+    SINGLETON_PK = 1
+
+    # core weights (defaults mirror historical constants)
+    inactive_penalty = models.FloatField(default=-1000)
+    favorites_per = models.FloatField(default=1 / 25)
+    tags_good = models.FloatField(default=15)
+    tags_many = models.FloatField(default=7)
+    officer_bonus = models.FloatField(default=15)
+    member_base = models.FloatField(default=10)
+    member_per = models.FloatField(default=0.1)  # 1/10
+    logo_bonus = models.FloatField(default=15)
+    subtitle_bad = models.FloatField(default=-10)
+    subtitle_good = models.FloatField(default=5)
+    images_bonus = models.FloatField(default=3)
+    desc_short = models.FloatField(default=25)
+    desc_med = models.FloatField(default=10)
+    desc_long = models.FloatField(default=10)
+    fair_bonus = models.FloatField(default=10)
+    application_bonus = models.FloatField(default=25)
+    today_event_base = models.FloatField(default=10)
+    today_event_good = models.FloatField(default=10)
+    week_event_base = models.FloatField(default=5)
+    week_event_good = models.FloatField(default=5)
+    email_bonus = models.FloatField(default=10)
+    social_bonus = models.FloatField(default=10)
+    howto_penalty = models.FloatField(default=-30)
+    outdated_penalty = models.FloatField(default=-10)
+    testimonial_one = models.FloatField(default=10)
+    testimonial_three = models.FloatField(default=5)
+    random_scale = models.FloatField(default=25)
+
+    updated_at = models.DateTimeField(auto_now=True)
+    updated_by = models.ForeignKey(
+        get_user_model(),
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="modified_ranking_weights",
+    )
+
+    def save(self, *args, **kwargs):
+        self.pk = self.SINGLETON_PK
+        super().save(*args, **kwargs)
+
+    def delete(self, *args, **kwargs):
+        raise ValueError("Cannot delete singleton instance")
+
+    @classmethod
+    def get(cls):
+        obj, _ = cls.objects.get_or_create(pk=cls.SINGLETON_PK)
+        return obj
+
+
 def get_mail_type_annotation(name):
     """
     Given a template name, return the type annotation metadata.