Merge pull request #13 from Eleven1Liu/unify_comments

Unify doc strings

Author: Eleven1Liu

libmultilabel/common_utils.py

@@ -34,10 +34,10 @@ def __setattr__(self, key: str, value: any) -> None:
         self._used.discard(key)
 
     def used_items(self) -> dict:
-        """Returns the items that have been used at least once after being set.
+        """Return the items that have been used at least once after being set.
 
         Returns:
-            dict: the used items.
+            dict: The used items.
         """
         return {k: self[k] for k in self._used}
 
@@ -46,10 +46,10 @@ def dump_log(log_path, metrics=None, split=None, config=None):
     """Write log including the used items of config and the evaluation scores.
 
     Args:
-        log_path(str): path to log path
-        metrics (dict): metric and scores in dictionary format, defaults to None
-        split (str): val or test, defaults to None
-        config (dict): config to save, defaults to None
+        log_path(str): Path to log path.
+        metrics (dict): Metric and scores in dictionary format, defaults to None.
+        split (str): One of `val` or `test`, defaults to None.
+        config (dict): Config to save, defaults to None.
     """
     os.makedirs(os.path.dirname(log_path), exist_ok=True)
     if os.path.isfile(log_path):
@@ -82,7 +82,8 @@ def argsort_top_k(vals, k, axis=-1):
         k: Consider only the top k elements for each query
         axis: Axis along which to sort. The default is -1 (the last axis).
 
-    Returns: Array of indices that sort vals along the specified axis.
+    Returns: 
+        Array of indices that sort vals along the specified axis.
     """
     unsorted_top_k_idx = np.argpartition(vals, -k, axis=axis)[:, -k:]
     unsorted_top_k_scores = np.take_along_axis(vals, unsorted_top_k_idx, axis=axis)
@@ -130,7 +131,7 @@ def is_multiclass_dataset(dataset, label="label"):
 
 
 def timer(func):
-    """Log info-level wall time"""
+    """Log info-level wall time."""
 
     @wraps(func)
     def wrapper(*args, **kwargs):

libmultilabel/linear/linear.py

@@ -39,7 +39,7 @@ def __init__(
         self.multiclass = multiclass
 
     def predict_values(self, x: sparse.csr_matrix) -> np.ndarray:
-        """Calculates the decision values associated with x.
+        """Calculate the decision values associated with x.
 
         Args:
             x (sparse.csr_matrix): A matrix with dimension number of instances * number of features.
@@ -79,7 +79,7 @@ def train_1vsrest(
     options: str = "",
     verbose: bool = True,
 ) -> FlatModel:
-    """Trains a linear model for multi-label data using a one-vs-rest strategy.
+    """Train a linear model for multi-label data using a one-vs-rest strategy.
 
     Args:
         y (sparse.csr_matrix): A 0/1 matrix with dimensions number of instances * number of classes.
@@ -169,9 +169,9 @@ def train_thresholding(
     options: str = "",
     verbose: bool = True,
 ) -> FlatModel:
-    """Trains a linear model for multi-label data using a one-vs-rest strategy
+    """Train a linear model for multi-label data using a one-vs-rest strategy
     and cross-validation to pick decision thresholds optimizing the sum of Macro-F1 and Micro-F1.
-    Outperforms train_1vsrest in most aspects at the cost of higher time complexity
+    Outperform train_1vsrest in most aspects at the cost of higher time complexity
     due to an internal cross-validation.
 
     This method is the micromacro-freq approach from this CIKM 2023 paper:
@@ -235,7 +235,7 @@ def _micromacro_one_label(
             negatives, and the number of labels processed.
 
     Returns:
-        tuple[np.ndarray, float, dict]: the weights, threshold, and the updated stats for calculating
+        tuple[np.ndarray, float, dict]: The weights, threshold, and the updated stats for calculating
         Micro-F1.
     """
 
@@ -319,7 +319,7 @@ def micro_plus_macro(tp, fp, fn):
 
 
 def _do_train(y: np.ndarray, x: sparse.csr_matrix, options: str) -> np.matrix:
-    """Wrapper around liblinear.liblinearutil.train.
+    """Wrap around liblinear.liblinearutil.train.
     Forcibly suppresses all IO regardless of options.
 
     Args:
@@ -328,7 +328,7 @@ def _do_train(y: np.ndarray, x: sparse.csr_matrix, options: str) -> np.matrix:
         options (str): The option string passed to liblinear.
 
     Returns:
-        np.matrix: the weights.
+        np.matrix: The weights.
     """
     if y.shape[0] == 0:
         return np.matrix(np.zeros((x.shape[1], 1)))
@@ -376,11 +376,11 @@ def _fmeasure(y_true: np.ndarray, y_pred: np.ndarray) -> float:
     """Calculate F1 score.
 
     Args:
-        y_true (np.ndarray): array of +1/-1.
-        y_pred (np.ndarray): array of +1/-1.
+        y_true (np.ndarray): Array of +1/-1.
+        y_pred (np.ndarray): Array of +1/-1.
 
     Returns:
-        float: the F1 score.
+        float: The F1 score.
     """
     tp = np.sum(np.logical_and(y_true == 1, y_pred == 1))
     fn = np.sum(np.logical_and(y_true == 1, y_pred == -1))
@@ -399,10 +399,10 @@ def train_cost_sensitive(
     options: str = "",
     verbose: bool = True,
 ) -> FlatModel:
-    """Trains a linear model for multi-label data using a one-vs-rest strategy
+    """Train a linear model for multi-label data using a one-vs-rest strategy
     and cross-validation to pick an optimal asymmetric misclassification cost
     for Macro-F1.
-    Outperforms train_1vsrest in most aspects at the cost of higher
+    Outperform train_1vsrest in most aspects at the cost of higher
     time complexity.
     See user guide for more details.
 
@@ -416,7 +416,7 @@ def train_cost_sensitive(
     Returns:
         A model which can be used in predict_values.
     """
-    # Follows the MATLAB implementation at https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/multilabel/
+    # Follow the MATLAB implementation at https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/multilabel/
     x, options, bias = _prepare_options(x, options)
 
     y = y.tocsc()
@@ -449,7 +449,7 @@ def _cost_sensitive_one_label(y: np.ndarray, x: sparse.csr_matrix, options: str)
         options (str): The option string passed to liblinear.
 
     Returns:
-        np.ndarray: the weights.
+        np.ndarray: The weights.
     """
 
     l = y.shape[0]
@@ -503,10 +503,10 @@ def train_cost_sensitive_micro(
     options: str = "",
     verbose: bool = True,
 ) -> FlatModel:
-    """Trains a linear model for multi-label data using a one-vs-rest strategy
+    """Train a linear model for multi-label data using a one-vs-rest strategy
     and cross-validation to pick an optimal asymmetric misclassification cost
     for Micro-F1.
-    Outperforms train_1vsrest in most aspects at the cost of higher
+    Outperform train_1vsrest in most aspects at the cost of higher
     time complexity.
     See user guide for more details.
 
@@ -574,7 +574,7 @@ def train_binary_and_multiclass(
     options: str = "",
     verbose: bool = True,
 ) -> FlatModel:
-    """Trains a linear model for binary and multi-class data.
+    """Train a linear model for binary and multi-class data.
 
     Args:
         y (sparse.csr_matrix): A 0/1 matrix with dimensions number of instances * number of classes.
@@ -628,7 +628,7 @@ def train_binary_and_multiclass(
 
 
 def predict_values(model, x: sparse.csr_matrix) -> np.ndarray:
-    """Calculates the decision values associated with x, equivalent to model.predict_values(x).
+    """Calculate the decision values associated with x, equivalent to model.predict_values(x).
 
     Args:
         model: A model returned from a training function.

libmultilabel/linear/metrics.py

@@ -8,7 +8,7 @@
 
 
 def _argsort_top_k(preds: np.ndarray, top_k: int) -> np.ndarray:
-    """Sorts the top k indices in O(n + k log k) time.
+    """Sort the top k indices in O(n + k log k) time.
     The sorting order is ascending to be consistent with np.sort.
     This means the last element is the largest, the first element is the kth largest.
     """
@@ -18,7 +18,7 @@ def _argsort_top_k(preds: np.ndarray, top_k: int) -> np.ndarray:
 
 
 def _dcg_argsort(argsort_preds: np.ndarray, target: np.ndarray, top_k: int) -> np.ndarray:
-    """Computes DCG@k with a sorted preds array and a target array."""
+    """Compute DCG@k with a sorted preds array and a target array."""
     top_k_idx = argsort_preds[:, -top_k:][:, ::-1]
     gains = np.take_along_axis(target, top_k_idx, axis=-1)
     discount = 1 / (np.log2(np.arange(top_k) + 2))
@@ -28,7 +28,7 @@ def _dcg_argsort(argsort_preds: np.ndarray, target: np.ndarray, top_k: int) -> n
 
 
 def _idcg(target: np.ndarray, top_k: int) -> np.ndarray:
-    """Computes IDCG@k for a 0/1 target array. A 0/1 target is a special case that
+    """Compute IDCG@k for a 0/1 target array. A 0/1 target is a special case that
     doesn't require sorting. If IDCG is computed with DCG,
     then target will need to be sorted, which incurs a large overhead.
     """
@@ -247,7 +247,7 @@ def __init__(self, metrics):
         self.max_k = max(getattr(metric, "top_k", 0) for metric in self.metrics.values())
 
     def update(self, preds: np.ndarray, target: np.ndarray):
-        """Adds a batch of decision values and labels.
+        """Add a batch of decision values and labels.
 
         Args:
             preds (np.ndarray): A matrix of decision values with dimensions number of instances * number of classes.
@@ -268,7 +268,7 @@ def update(self, preds: np.ndarray, target: np.ndarray):
                 metric.update(preds, target)
 
     def compute(self) -> dict[str, float]:
-        """Computes the metrics from the accumulated batches of decision values and labels.
+        """Compute the metrics from the accumulated batches of decision values and labels.
 
         Returns:
             dict[str, float]: A dictionary of metric values.
@@ -279,7 +279,7 @@ def compute(self) -> dict[str, float]:
         return ret
 
     def reset(self):
-        """Clears the accumulated batches of decision values and labels."""
+        """Clear the accumulated batches of decision values and labels."""
         for metric in self.metrics.values():
             metric.reset()
 

libmultilabel/linear/tree.py

@@ -59,7 +59,7 @@ def predict_values(
         x: sparse.csr_matrix,
         beam_width: int = 10,
     ) -> np.ndarray:
-        """Calculates the probability estimates associated with x.
+        """Calculate the probability estimates associated with x.
 
         Args:
             x (sparse.csr_matrix): A matrix with dimension number of instances * number of features.
@@ -118,7 +118,7 @@ def train_tree(
     dmax=10,
     verbose: bool = True,
 ) -> TreeModel:
-    """Trains a linear model for multi-label data using a divide-and-conquer strategy.
+    """Train a linear model for multi-label data using a divide-and-conquer strategy.
     The algorithm used is based on https://github.com/xmc-aalto/bonsai.
 
     Args:
@@ -178,7 +178,7 @@ def visit(node):
 
 
 def _build_tree(label_representation: sparse.csr_matrix, label_map: np.ndarray, d: int, K: int, dmax: int) -> Node:
-    """Builds the tree recursively by kmeans clustering.
+    """Build the tree recursively by kmeans clustering.
 
     Args:
         label_representation (sparse.csr_matrix): A matrix with dimensions number of classes under this node * number of features.
@@ -235,7 +235,7 @@ def collect_stat(node: Node):
 
 
 def _train_node(y: sparse.csr_matrix, x: sparse.csr_matrix, options: str, node: Node):
-    """If node is internal, computes the metalabels representing each child and trains
+    """If node is internal, compute the metalabels representing each child and train
     on the metalabels. Otherwise, train on y.
 
     Args:
@@ -258,7 +258,7 @@ def _train_node(y: sparse.csr_matrix, x: sparse.csr_matrix, options: str, node:
 
 
 def _flatten_model(root: Node) -> tuple[linear.FlatModel, np.ndarray]:
-    """Flattens tree weight matrices into a single weight matrix. The flattened weight
+    """Flatten tree weight matrices into a single weight matrix. The flattened weight
     matrix is used to predict all possible values, which is cached for beam search.
     This pessimizes complexity but is faster in practice.
     Consecutive values of the returned map denotes the start and end indices of the

libmultilabel/linear/utils.py

@@ -31,7 +31,7 @@
 
 
 def save_pipeline(checkpoint_dir: str, preprocessor: Preprocessor, model):
-    """Saves preprocessor and model to checkpoint_dir/linear_pipline.pickle.
+    """Save preprocessor and model to checkpoint_dir/linear_pipline.pickle.
 
     Args:
         checkpoint_dir (str): The directory to save to.
@@ -53,7 +53,7 @@ def save_pipeline(checkpoint_dir: str, preprocessor: Preprocessor, model):
 
 
 def load_pipeline(checkpoint_path: str) -> tuple[Preprocessor, Any]:
-    """Loads preprocessor and model from checkpoint_path.
+    """Load preprocessor and model from checkpoint_path.
 
     Args:
         checkpoint_path (str): The path to a previously saved pipeline.