Improve documentation and add comments for scripts.

Author: zhouhq10

scripts/eval_causal_support.py

@@ -8,35 +8,32 @@
 import pandas as pd
 import numpy as np
 
-import knowledge_tracing.utils.visualize as visualize
-import knowledge_tracing.utils.utils as utils
-
-import matplotlib.pyplot as plt
-
 
 def parse_args(parser):
     parser.add_argument(
         "--base_pth",
         type=str,
+        default="../data",
+        help="path to the directory containing the dataset",
     )
-    parser.add_argument("--dataset", type=str, default=1, help="Name of dataset")
+    parser.add_argument("--dataset", type=str, help="Name of dataset")
     parser.add_argument(
         "--gap",
         type=int,
         default=1,
-        help="The order of transition in evaluation causal support",
+        help="the order of transition in evaluation causal support",
     )
     parser.add_argument(
         "--test",
         type=int,
         default=1,
-        help="Whether using test data in evaluation causal support",
+        help="whether using test data in evaluation causal support",
     )
     parser.add_argument(
         "--num_sample",
         type=int,
         default=1e6,
-        help="Number of samples in estimating causal support",
+        help="number of samples in estimating causal support",
     )
 
     return parser
@@ -48,31 +45,47 @@ def parse_args(parser):
     parser = parse_args(parser)
     args, extras = parser.parse_known_args()
 
-    # assistment12
+    # Load interaction data and skill corpus from files
+    # Read interactions CSV file
     inter = pd.read_csv(
         f"{args.base_pth}/{args.dataset}/multi_skill/interactions.csv", sep="\t"
     )
+    # Load corpus object from pickle file
     with open(f"{args.base_pth}/{args.dataset}/multi_skill/Corpus.pkl", "rb") as f:
         corpus = pickle.load(f)
 
+    # Extract unique skill IDs and count the number of nodes (skills)
     skill_id = list(inter.skill_id.unique())
     num_node = len(skill_id)
 
+    # Create a list of skill texts by matching skill IDs in interactions
     skill_list = []
     for i in range(len(skill_id)):
         text = list(inter.loc[inter["skill_id"] == i]["skill_text"])[0]
         skill_list.append(text)
 
-    # ----- Calculate transition matrix -----
+    # Calculate transition matrix for skill sequences
+    # The gap and start variables define the range of transitions to consider
     gap = args.gap
-    start = 10 if args.test else 0
-    T = np.zeros((num_node, num_node, 4))  # 0-1, 0-0, 1-1, 1-0
-    N = np.zeros((num_node, num_node))
+    start = (
+        10 if args.test else 0
+    )  # Start index for considering transitions, based on whether it's a test run
+    T = np.zeros(
+        (num_node, num_node, 4)
+    )  # Transition counts for each pair of skills and outcomes (0-1, 0-0, 1-1, 1-0)
+    N = np.zeros(
+        (num_node, num_node)
+    )  # Total transition counts between each pair of skills
+
+    # Iterate through each user sequence in the corpus
     for l in range(len(corpus.user_seq_df)):
         correct = corpus.user_seq_df["correct_seq"][l]
         index = corpus.user_seq_df["skill_seq"][l]
 
-        for i in range(start, start + 10 - gap):
+        # Count transitions and outcomes for each sequence, considering the defined gap
+        for i in range(
+            start, start + 10 - gap
+        ):  # Ensure transition between different skills
             if index[i + gap] != index[i]:
                 if correct[i] == 0:
                     if correct[i + gap] == 1:
@@ -84,25 +97,29 @@ def parse_args(parser):
                         T[index[i], index[i + gap], 2] += 1
                     else:
                         T[index[i], index[i + gap], 3] += 1
-                N[index[i], index[i + gap]] += 1
+                N[index[i], index[i + gap]] += 1  # Increment total transition count
+
+    # Calculate the probability of a successful transition
     success_transition = abs(T[..., 2]) / (T[..., 2] + T[..., 3] + 1e-6)
+    # Create a mask to filter transitions with sufficient data
     mask = T[..., 2] + T[..., 3] + T[..., 0] + T[..., 1] > 1
 
+    # Counters for calculating causal support
     Nc_minus = T[..., 0] + T[..., 1]
     Nc_plus = T[..., 2] + T[..., 3]
     Ne_minus = T[..., 1] + T[..., 3]
     Ne_plus = T[..., 0] + T[..., 2]
 
-    # ----- Compute causal support -----
-    # P(D|G0)
+    # Compute causal support for the transitions
+    # Probability of data given no causal relationship (P(D|G0))
     num_sample = args.num_sample
     w0 = np.arange(0, num_sample, 1) / num_sample
     w0 = w0.reshape(num_sample, 1, 1).repeat(num_node, 1).repeat(num_node, -1)
     p0 = np.power(w0, np.expand_dims(Ne_plus, 0).repeat(num_sample, 0)) * np.power(
         1 - w0, np.expand_dims(Ne_minus, 0).repeat(num_sample, 0)
     )
 
-    # P(D|G1)
+    # Probability of data given a causal relationship (P(D|G1))
     w0 = np.arange(0, num_sample, 1) / num_sample
     w0 = w0.reshape(num_sample, 1, 1).repeat(num_node, 1).repeat(num_node, -1)
     w0 = w0.repeat(num_sample, 0)
@@ -119,5 +136,5 @@ def parse_args(parser):
 
     p1 = np.multiply(p_e1_c1, p_e1_c0)
 
-    # Support
+    # Calculate and print the causal support
     support = np.log(p1.mean(0) + 1e-6) - np.log(p0.mean(0) + 1e-6)

scripts/generate_synthetic_data.py

@@ -18,17 +18,17 @@
 def parse_args(parser):
     # ----- global -----
     parser.add_argument(
-        "--random_seed", type=int, default=1, help="Random seed for reproducibility"
+        "--random_seed", type=int, default=1, help="random seed for reproducibility"
     )
     parser.add_argument(
-        "--num_sequence", type=int, default=1, help="Number of sequences to generate"
+        "--num_sequence", type=int, default=1, help="number of sequences to generate"
     )
     parser.add_argument(
         "--learner_model",
         type=str,
         default="graph_ou",
         choices=["hlr", "ppe", "ou", "graph_ou"],
-        help="Type of learner model: hlr, ou, graph_ou, egraph_ou, ppe",
+        help="type of learner models: hlr, ou, graph_ou, egraph_ou, ppe",
     )
 
     # ----- time points -----
@@ -37,71 +37,71 @@ def parse_args(parser):
         type=str,
         default="random",
         choices=["random", "uniform"],
-        help="Type of time distribution: random or uniform",
+        help="type of time distributions: random or uniform",
     )
     parser.add_argument(
-        "--time_step", type=int, default=20, help="Time step between points"
+        "--time_step", type=int, default=20, help="time step between points"
     )
     parser.add_argument(
-        "--max_time_step", type=int, default=250, help="Maximum time step"
+        "--max_time_step", type=int, default=250, help="maximum time step"
     )
 
     # ----- random graph -----
     parser.add_argument(
-        "--num_node", type=int, default=2, help="Number of nodes in the random graph"
+        "--num_node", type=int, default=10, help="number of nodes in the random graph"
     )
     parser.add_argument(
         "--edge_prob",
         type=float,
         default=0.4,
-        help="Probability of an edge between nodes",
+        help="probability of an edge between nodes",
     )
 
     # ----- ou process -----
     parser.add_argument(
         "--mean_rev_speed",
         type=float,
         default=0.02,
-        help="Mean reversion speed parameter",
+        help="mean reversion speed parameter",
     )
     parser.add_argument(
         "--mean_rev_level",
         type=float,
         default=0.7,
-        help="Mean reversion level parameter",
+        help="mean reversion level parameter",
     )
-    parser.add_argument("--vola", type=float, default=0.01, help="Volatility parameter")
-    parser.add_argument("--rho", type=float, default=2, help="Rho parameter")
-    parser.add_argument("--omega", type=float, default=0.75, help="Omega parameter")
+    parser.add_argument("--vola", type=float, default=0.01, help="volatility parameter")
+    parser.add_argument("--rho", type=float, default=2, help="rho parameter")
+    parser.add_argument("--omega", type=float, default=0.75, help="omega parameter")
     parser.add_argument(
-        "--gamma", type=float, default=[0.1, 0.2, 0.5, 0.75, 1], help="Gamma parameter"
+        "--gamma", type=float, default=[0.1, 0.2, 0.5, 0.75, 1], help="gamma parameter"
     )
 
     # ----- hlr process -----
     parser.add_argument(
         "--theta",
         type=list,
         default=[1 / 4, 1 / 2, -1 / 3],
-        help="List of theta parameters",
+        help="list of theta parameters",
     )
 
     # ----- ppe process -----
     parser.add_argument(
         "--learning_rate",
         type=float,
         default=[0.01, 0.05, 0.1, 0.2, 0.5, 1],
-        help="Learning rate for the PPE process",
+        help="learning rate for the PPE process",
     )
     parser.add_argument(
-        "--decay_rate", type=float, default=0.2, help="Decay rate for the PPE process"
+        "--decay_rate", type=float, default=0.2, help="decay rate for the PPE process"
     )
 
     # ----- save path -----
     parser.add_argument(
         "--save_path",
         type=str,
         default="..kt_data/synthetic",
-        help="Path to save results",
+        help="path to save results",
     )
 
     return parser

scripts/predict_learner_performance_baseline.py

@@ -29,7 +29,7 @@ def global_parse_args():
     parser = argparse.ArgumentParser(description="Global")
 
     parser.add_argument(
-        "--model_name", type=str, default="CausalKT", help="Choose a model to run."
+        "--model_name", type=str, default="CausalKT", help="choose a model to run."
     )
 
     return parser
@@ -52,7 +52,6 @@ def global_parse_args():
     # ----- args -----
     # reference:
     # # https://docs.python.org/3/library/argparse.html?highlight=parse_known_args#argparse.ArgumentParser.parse_known_args
-
     global_args.model_name = model_name
     global_args.time = datetime.datetime.now().isoformat()
     global_args.device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")