pylint

Author: hroskes

docs/02_rocpicker.tex

@@ -76,6 +76,7 @@ \subsection{Discrete points}
 \xdot(t)&=\sum_n \mathscr{x}_n \delta(t-t_n) \\
 \ydot(t)&=\sum_r \mathscr{y}_r \delta(t-t_r) \\
 \end{aligned}
+\label{eq:roc-from-delta-functions}
 \end{align}
 The indices \(n\) and \(r\) index the non-responders and responders, \(\mathscr{X}_n\) and \(\mathscr{Y}_r\) are the numbers of non-responders and responders with \(t=t_n\) or \(t=t_r\), and \(\mathscr{x}_n\) and \(\mathscr{y}_r\) are the fractions of non-responders and responders with \(t=t_n\) or \(t=t_r\) in the true probability distribution.
 

roc_picker/datacard.py

@@ -155,7 +155,7 @@ def systematics_mc(self, *, id_start=0, flip_sign=False):
         count = ScipyDistribution(
           nominal=p["value"],
           scipydistribution=scipy.stats.poisson(mu=p["value"]),
-          id=next(id_generator)
+          unique_id=next(id_generator)
         )
         patient_distributions.append({
           "response": p["response"],
@@ -167,12 +167,12 @@ def systematics_mc(self, *, id_start=0, flip_sign=False):
         numerator = ScipyDistribution(
           nominal=p["numerator"],
           scipydistribution=scipy.stats.poisson(mu=p["numerator"]),
-          id=next(id_generator)
+          unique_id=next(id_generator)
         )
         denominator = ScipyDistribution(
           nominal=p["denominator"],
           scipydistribution=scipy.stats.poisson(mu=p["denominator"]),
-          id=next(id_generator)
+          unique_id=next(id_generator)
         )
         ratio = numerator / denominator
         patient_distributions.append({
@@ -186,7 +186,7 @@ def systematics_mc(self, *, id_start=0, flip_sign=False):
         log_norm_factor = ScipyDistribution(
           nominal=0,
           scipydistribution=scipy.stats.norm(),
-          id=next(id_generator)
+          unique_id=next(id_generator)
         )
         try:
           for patient, value in zip(patient_distributions, systematic["values"], strict=True):

roc_picker/delta_functions.py

@@ -1,21 +1,67 @@
-import functools, numpy as np, scipy.optimize, warnings
+"""
+Optimize the discrete ROC curve using the Lagrangian method
+applied to delta functions.  This is a sanity check and should
+be equivalent to the discrete method.  See docs/02_rocpicker.tex
+for the math details and docs/03_examples.md for usage examples.
+"""
+
+import functools, warnings
+import numpy as np, scipy.optimize
 from .discrete_base import DiscreteROCBase
 
 class DeltaFunctions(DiscreteROCBase):
+  """
+  Optimize the discrete ROC curve using the Lagrangian method
+  applied to delta functions.  This is a sanity check and should
+  be equivalent to the discrete method.  See docs/02_rocpicker.tex
+  for the math details and docs/03_examples.md for usage examples.
+
+  Parameters
+  ----------
+  responders: array-like
+    The parameter values for the responders.
+  nonresponders: array-like
+    The parameter values for the nonresponders.
+  flip_sign: bool, optional
+    If True, the sign of the parameter is flipped.
+    Default is False.
+  """
   @functools.cached_property
   def sign(self):
-    if self.flip_sign: return -1
-    return 1
+    """
+    The sign to multiply the parameter values by.
+    """
+    if self.flip_sign:
+      return -1
+    else:
+      return 1
   @functools.cached_property
   def ts(self):
+    """
+    The parameter values for all patients.
+    """
     return sorted(set(self.responders) | set(self.nonresponders) | {np.inf, -np.inf})
 
   def X(self, t):
+    """
+    The X coordinate of the nominal ROC curve at the parameter value t,
+    which represents the number of nonresponders at or below t.
+    """
     return sum(1 for ni in self.nonresponders if ni*self.sign < t*self.sign)
   def Y(self, t):
+    """
+    The Y coordinate of the nominal ROC curve at the parameter value t,
+    which represents the number of responders at or below t.
+    """
     return sum(1 for ri in self.responders if ri*self.sign < t*self.sign)
 
   def xy(self, c1, c5, Lambda):
+    """
+    The x and y functions for the fitted ROC curve,
+    given the parameters c1, c5, and Lambda.
+    (The optimization is to determine those parameters.)
+    c3 and c4 are trivial to calculate from the boundary conditions.
+    """
     c3 = c4 = 0
     if self.flip_sign:
       c3 = c4 = 1
@@ -53,6 +99,9 @@ def y(t):
     return x, y
 
   def findparams(self, *, AUC, c1_guess, c5_guess, Lambda_guess):
+    """
+    Find the parameters c1, c5, and Lambda that satisfy the boundary conditions.
+    """
     def bc(params):
       if not self.flip_sign:
         target_at_inf = 1
@@ -75,10 +124,37 @@ def bc(params):
     guess = [c1_guess, c5_guess, Lambda_guess]
     return scipy.optimize.fsolve(bc, guess)
 
-  def optimize(self, *, AUC, c1_guess=1, c5_guess=1, Lambda_guess=1):
+  def optimize(self, *, AUC=None, c1_guess=1, c5_guess=1, Lambda_guess=1):
+    """
+    Optimize the ROC curve to match the given AUC.
+
+    Parameters
+    ----------
+    AUC: float
+      The target AUC.
+    c1_guess: float, optional
+      The initial guess for the parameter c1.
+      Default is 1.
+    c5_guess: float, optional
+      The initial guess for the parameter c5.
+      Default is 1.
+    Lambda_guess: float, optional
+      The initial guess for the parameter Lambda.
+      Default is 1.
+    """
     with warnings.catch_warnings():
-      warnings.filterwarnings("ignore", "The number of calls to function has reached maxfev = |The iteration is not making good progress")
-      c1, c5, Lambda = self.findparams(AUC=AUC, c1_guess=c1_guess, c5_guess=c5_guess, Lambda_guess=Lambda_guess)
+      warnings.filterwarnings(
+        "ignore",
+        "The number of calls to function has reached maxfev = "
+        "|"
+        "The iteration is not making good progress"
+      )
+      c1, c5, Lambda = self.findparams(
+        AUC=AUC,
+        c1_guess=c1_guess,
+        c5_guess=c5_guess,
+        Lambda_guess=Lambda_guess
+      )
 
     x, y = self.xy(c1, c5, Lambda)
 

roc_picker/discrete.py

@@ -1,47 +1,104 @@
+"""
+Optimize the ROC curve using the discrete method.
+See docs/02_rocpicker.tex for the math details
+and docs/03_examples.md for usage examples.
+"""
+
 import collections, functools, numpy as np, scipy.optimize
 from .discrete_base import DiscreteROCBase
 
 class DiscreteROC(DiscreteROCBase):
+  """
+  Optimize the ROC curve using the discrete method.
+  See docs/02_rocpicker.tex for the math details
+  and docs/03_examples.md for usage examples.
+
+  Parameters
+  ----------
+  responders: array-like
+    The parameter values for the responders.
+  nonresponders: array-like
+    The parameter values for the nonresponders.
+  flip_sign: bool, optional
+    If True, the sign of the parameter is flipped.
+    Default is False.
+  check_validity: bool, optional
+    If True, run sanity checks at each step.
+    This should not be necessary for normal use.
+    Default is False.
+  """
   def __init__(self, *args, check_validity=False, **kwargs):
     self.__check_validity = check_validity
     super().__init__(*args, **kwargs)
 
   @functools.cached_property
   def ts(self):
+    """
+    The parameter values for all patients.
+    """
     return np.array(sorted(set(self.responders) | set(self.nonresponders)))
   @functools.cached_property
   def Xscr(self):
+    """
+    The number of nonresponders at each parameter value.
+    """
     counter = collections.Counter(self.nonresponders)
     return np.array([counter[t] for t in self.ts])
   @functools.cached_property
   def Yscr(self):
+    """
+    The number of responders at each parameter value.
+    """
     counter = collections.Counter(self.responders)
     return np.array([counter[t] for t in self.ts])
 
   @functools.cached_property
   def nonzeroXindices(self):
+    """
+    The indices of parameter values for non-responders.
+    """
     return self.Xscr != 0
   @functools.cached_property
   def nonzeroYindices(self):
+    """
+    The indices of parameter values for responders.
+    """
     return self.Yscr != 0
   @functools.cached_property
   def numnonzeroXindices(self):
+    """
+    The number of distinct parameter values for non-responders.
+    """
     return np.count_nonzero(self.nonzeroXindices)
 
   @functools.cached_property
   def nonzeroXscr(self):
+    """
+    The number of nonresponders at each nonzero parameter value.
+    """
     return self.Xscr[self.nonzeroXindices]
   @functools.cached_property
   def nonzeroYscr(self):
+    """
+    The number of responders at each nonzero parameter value.
+    """
     return self.Yscr[self.nonzeroYindices]
 
   def checkvalidity(self, xscr, yscr):
-    if not self.__check_validity: return
+    """
+    Check whether a candidate ROC curve is valid.
+    """
+    if not self.__check_validity:
+      return
     np.testing.assert_array_equal(xscr[self.Xscr==0], 0)
     np.testing.assert_array_equal(yscr[self.Yscr==0], 0)
     np.testing.assert_allclose([xscr.sum(), yscr.sum()], 1)
 
   def evalNLL(self, xscr, yscr):
+    """
+    Evaluate the negative log-likelihood of a candidate ROC curve (xscr, yscr)
+    given the data (self.Xscr, self.Yscr).
+    """
     self.checkvalidity(xscr, yscr)
 
     nonzeroxscr = xscr[self.nonzeroXindices]
@@ -56,6 +113,10 @@ def evalNLL(self, xscr, yscr):
     return NLL
 
   def buildroc(self, xscr, yscr):
+    """
+    Build the ROC curve (x, y) from the delta function coordinates
+    (xscr, yscr).  (See eq.~\ref{eq:roc-from-delta-functions} in docs/02_rocpicker.tex.)
+    """
     self.checkvalidity(xscr, yscr)
     x = np.zeros(shape=len(self.ts)+1)
     y = np.zeros(shape=len(self.ts)+1)
@@ -73,10 +134,13 @@ def buildroc(self, xscr, yscr):
     return x, y
 
   def evalAUC(self, xscr, yscr):
+    """
+    Evaluate the area under the ROC curve constructed from (xscr, yscr).
+    """
     xx, yy = self.buildroc(xscr, yscr)
     return np.sum(0.5 * (xx[1:] - xx[:-1]) * (yy[1:] + yy[:-1]))
 
-  def optimize(self, AUC=None):
+  def optimize(self, *, AUC=None):
     def unpackxy(xy):
       length = len(self.ts)
       xscr = np.zeros(length)
@@ -96,12 +160,12 @@ def NLL(xy):
 
     guess = np.concatenate([self.Xscr[self.nonzeroXindices], self.Yscr[self.nonzeroYindices]])
 
-    def sumxscr(xy):
-      xscr, yscr = unpackxy(xy)
-      return sum(xscr) - 1
-    def sumyscr(xy):
-      xscr, yscr = unpackxy(xy)
-      return sum(yscr) - 1
+    #def sumxscr(xy):
+    #  xscr, yscr = unpackxy(xy)
+    #  return sum(xscr) - 1
+    #def sumyscr(xy):
+    #  xscr, yscr = unpackxy(xy)
+    #  return sum(yscr) - 1
     constraints = [
       #{
       #  "type": "eq",

roc_picker/discrete_base.py

@@ -27,7 +27,7 @@ def __init__(self, responders, nonresponders, *, flip_sign=False):
     self.flip_sign = flip_sign
 
   @abc.abstractmethod
-  def optimize(self, AUC=None):
+  def optimize(self, *, AUC=None):
     """
     Optimize the ROC curve, either unconditionally or for a given AUC.
     """