FEat: add comments

recopytex/df_marks_manip.py

@@ -6,7 +6,9 @@ import numpy as np
 from math import ceil, floor
 from .config import COLUMNS, VALIDSCORE
 
-# Values manipulations
+"""
+Functions for manipulate score dataframes
+"""
 
 
 def round_half_point(val):
@@ -19,12 +21,13 @@ def round_half_point(val):
 
 
 def score_to_mark(x):
-    """ Compute the mark
+    """Compute the mark
 
     if the item is leveled then the score is multiply by the score_rate
     otherwise it copies the score
 
     :param x: dictionnary with COLUMNS["is_leveled"], COLUMNS["score"] and COLUMNS["score_rate"] keys
+    :return: the mark
 
     >>> d = {"Eleve":["E1"]*6 + ["E2"]*6,
     ...    COLUMNS["score_rate"]:[1]*2+[2]*2+[2]*2 + [1]*2+[2]*2+[2]*2,
@@ -43,7 +46,9 @@ def score_to_mark(x):
 
     if x[COLUMNS["is_leveled"]]:
         if x[COLUMNS["score"]] not in [0, 1, 2, 3]:
-            raise ValueError(f"The evaluation is out of range: {x[COLUMNS['score']]} at {x}")
+            raise ValueError(
+                f"The evaluation is out of range: {x[COLUMNS['score']]} at {x}"
+            )
         return round_half_point(x[COLUMNS["score"]] * x[COLUMNS["score_rate"]] / 3)
 
     if x[COLUMNS["score"]] > x[COLUMNS["score_rate"]]:
@@ -54,9 +59,10 @@ def score_to_mark(x):
 
 
 def score_to_level(x):
-    """ Compute the level (".",0,1,2,3).
+    """Compute the level (".",0,1,2,3).
 
     :param x: dictionnary with COLUMNS["is_leveled"], COLUMNS["score"] and COLUMNS["score_rate"] keys
+    :return: the level
 
     >>> d = {"Eleve":["E1"]*6 + ["E2"]*6,
     ...    COLUMNS["score_rate"]:[1]*2+[2]*2+[2]*2 + [1]*2+[2]*2+[2]*2,
@@ -91,7 +97,9 @@ def score_to_level(x):
 
 
 def compute_mark(df):
-    """ Add Mark column to df
+    """Compute the mark for the dataframe
+
+    apply score_to_mark to each row
 
     :param df: DataFrame with COLUMNS["score"], COLUMNS["is_leveled"] and COLUMNS["score_rate"] columns.
 
@@ -122,9 +130,12 @@ def compute_mark(df):
 
 
 def compute_level(df):
-    """ Add Mark column to df
+    """Compute level for the dataframe
+
+    Applies score_to_level to each row
 
     :param df: DataFrame with COLUMNS["score"], COLUMNS["is_leveled"] and COLUMNS["score_rate"] columns.
+    :return: Columns with level
 
     >>> d = {"Eleve":["E1"]*6 + ["E2"]*6,
     ...    COLUMNS["score_rate"]:[1]*2+[2]*2+[2]*2 + [1]*2+[2]*2+[2]*2,
@@ -153,9 +164,10 @@ def compute_level(df):
 
 
 def compute_normalized(df):
-    """ Compute the normalized mark (Mark / score_rate)
+    """Compute the normalized mark (Mark / score_rate)
 
     :param df: DataFrame with "Mark" and COLUMNS["score_rate"] columns
+    :return: column with normalized mark
 
     >>> d = {"Eleve":["E1"]*6 + ["E2"]*6,
     ...    COLUMNS["score_rate"]:[1]*2+[2]*2+[2]*2 + [1]*2+[2]*2+[2]*2,
@@ -186,7 +198,9 @@ def compute_normalized(df):
 
 
 def pp_q_scores(df):
-    """ Postprocessing questions scores dataframe
+    """Postprocessing questions scores dataframe
+
+    Add 3 columns: mark, level and normalized
 
     :param df: questions-scores dataframe
     :return: same data frame with mark, level and normalize columns