add more comments in firebaes functions and use contributor_count in python function

Author: Hagellach37

firebase/functions/index.js

@@ -6,8 +6,12 @@ const admin = require('firebase-admin')
 admin.initializeApp()
 
 
-// Calculate number of users who finished a group and
-// Gets triggered when new results of a group are written to the database.
+/*
+    Log the userIds of all users who finished a group to /v2/userGroups/{projectId}/{groupId}/.
+    Gets triggered when new results of a group are written to the database.
+    This is the basis to calculate number of users who finished a group (requiredCount and finishedCount),
+    which will be handled in the groupFinishedCountUpdater function.
+*/
 exports.groupUsersCounter = functions.database.ref('/v2/results/{projectId}/{groupId}/{userId}/').onCreate((snapshot, context) => {
     const promises = []  // List of promises to return
     const result = snapshot.val()
@@ -67,16 +71,26 @@ exports.groupUsersCounter = functions.database.ref('/v2/results/{projectId}/{gro
                 }
             }
         })
-    promises.push(updateValues.userContribution)
-    promises.push(updateValues.groupUsers)
-    promises.push(updateValues.totalTaskContributionCount)
-    promises.push(updateValues.taskContributionCount)
 
+    // Check if updateValues is null (happens when user submitted this group twice)
+    // and return null in this case.
+    if (updateValues === null) {
+        return null
+    } else {
+        promises.push(updateValues.userContribution)
+        promises.push(updateValues.groupUsers)
+        promises.push(updateValues.totalTaskContributionCount)
+        promises.push(updateValues.taskContributionCount)
+    }
 })
 
 
-// set group finishedCount and group requiredCount.
-// Gets triggered when new userId key is written to groupsUsers.
+/*
+    Set group finishedCount and group requiredCount.
+    Gets triggered when new userId key is written to v2/groupsUsers/{projectId}/{groupId}.
+    FinishedCount and requiredCount of a group are calculated based on the number of userIds
+    that are present in v2/groupsUsers/{projectId}/{groupId}.
+*/
 exports.groupFinishedCountUpdater = functions.database.ref('/v2/groupsUsers/{projectId}/{groupId}/').onWrite((snapshot, context) => {
     const promises_new = []
 

mapswipe_workers/mapswipe_workers/generate_stats/project_stats.py

@@ -329,13 +329,13 @@ def set_progress_in_firebase(project_id: str, progress: int):
     logger.info(f"set progress for project {project_id}: {progress}")
 
 
-def set_contributors_in_firebase(project_id: str, contributors: int):
+def set_contributor_count_in_firebase(project_id: str, contributor_count: int):
     """Update the project contributors value in Firebase."""
 
     fb_db = auth.firebaseDB()
     project_progress_ref = fb_db.reference(f"v2/projects/{project_id}/contributorCount")
-    project_progress_ref.set(contributors)
-    logger.info(f"set contributors for project {project_id}: {contributors}")
+    project_progress_ref.set(contributor_count)
+    logger.info(f"set contributorCount attribute for project {project_id}: {contributor_count}")
 
 
 def get_per_project_statistics(project_id: str, project_info: pd.Series) -> dict:
@@ -417,14 +417,18 @@ def get_per_project_statistics(project_id: str, project_info: pd.Series) -> dict
         )
 
         # update progress and contributors in firebase
+        # cum_progress[-1] refers to the latest value available for project progress
+        # cum_progess contains overall project progress reached at each day
         set_progress_in_firebase(
             project_id=project_id,
             progress=int(100*project_stats_by_date_df["cum_progress"][-1])
         )
 
-        set_contributors_in_firebase(
+        # cum_number_of_users[-1] refers to the latest value available for contributorCount
+        # cum_number_of_users contains overall contributor count reached at each day
+        set_contributor_count_in_firebase(
             project_id=project_id,
-            contributors=int(project_stats_by_date_df["cum_number_of_users"][-1])
+            contributor_count=int(project_stats_by_date_df["cum_number_of_users"][-1])
         )
 
         # generate geometries for HOT Tasking Manager

mapswipe_workers/mapswipe_workers/generate_stats/project_stats_by_date.py

@@ -54,8 +54,22 @@ def get_progress_by_date(
 ) -> pd.DataFrame:
     """
     for each project we retrospectively generate the following attributes for a given
-    date utilizing the results:
-    number_of_results, cum_number_of_results, progress, cum_progress
+    date utilizing the results.
+
+    number_of_results:
+        - number of results that have been contributed per day
+        - not used in firebase
+
+    cum_number_of_results:
+        - sum of daily number of results up to that day
+
+    progress:
+        - relative progress per day (e.g. overall progress increased by 0.15 on that day)
+        - not used in firebase
+
+    cum_progress:
+        - absolute progress up to that day
+        - refers to the project progress attribute in firebase
     """
 
     groups_df["required_results"] = (
@@ -127,7 +141,18 @@ def get_contributors_by_date(results_df: pd.DataFrame) -> pd.DataFrame:
     """
     for each project we retrospectively generate the following attributes for a given
     date utilizing the results:
-    number_of_users, number_of_new_users, cum_number_of_users
+
+    number_of_users:
+        - number of distinct users active per day
+        - not used in firebase
+
+    number_of_new_users:
+        - number of distinct users who mapped the first group in that project per day
+        - not used in firebase
+
+    cum_number_of_users:
+        - overall number of distinct users active up to that day
+        - refers to the project contributorCount attribute in firebase
     """
 
     user_first_day_df = results_df.groupby(["user_id"]).agg(