add docstrings and assertions

Author: hbmartin

.idea/dictionaries/haroldmartin.xml

@@ -11,7 +11,7 @@ def main():
 
         client = Client(
             dsn="https://f1fce21b51864819a26ea116ff4e5b7f:[email protected]/1266157",
-            release=__version__
+            release=__version__,
         )
     except BaseException:
         pass

graphviz2drawio/__main__.py

@@ -1,36 +1,57 @@
 from . import LinearRegression
 
+linear_min_r2 = 0.9
+
 
 class Curve:
     def __init__(self, start, end, cb):
+        """Takes complex numbers for start, end, and list of 4 Bezier control points"""
         super(Curve, self).__init__()
         self.start = start
         self.end = end
+        assert cb is None or len(cb) == 4
         self.cb = cb
 
     def __str__(self):
         control = "[" + (str(self.cb) if self.cb is not None else "None") + "]"
         return str(self.start) + ", " + control + ", " + str(self.end)
 
     @staticmethod
-    def is_linear(points):
+    def is_linear(points, threshold=linear_min_r2):
+        """
+        Returns a boolean indicating whether a list of complex points is linear.
+
+        Takes a list of complex points and optional minimum R**2 threshold for linear regression.
+        """
         r2 = LinearRegression.coefficients(points)[2]
-        return r2 > 0.9
+        return r2 > threshold
 
     def cubic_bezier_coordinates(self, t):
-        x = Curve.cubic_bezier(
-            [self.cb[0].real, self.cb[1].real, self.cb[2].real, self.cb[3].real], t
-        )
-        y = Curve.cubic_bezier(
-            [self.cb[0].imag, self.cb[1].imag, self.cb[2].imag, self.cb[3].imag], t
-        )
+        """
+        Returns a complex number representing the point along the cubic bezier curve.
+
+        Takes parametric parameter t where 0 <= t <= 1
+        """
+        x = Curve._cubic_bezier(self._cb("real"), t)
+        y = Curve._cubic_bezier(self._cb("imag"), t)
         return complex(x, y)
 
+    def _cb(self, prop):
+        return [getattr(x, prop) for x in self.cb]
+
     @staticmethod
-    def cubic_bezier(p, t):
+    def _cubic_bezier(p, t):
+        """
+        Returns a float representing the point along the cubic bezier curve in the given dimension.
+
+        Takes ordered list of 4 control points [P0, P1, P2, P3] and parametric parameter t where 0 <= t <= 1
+
+        implements explicit form of https://en.wikipedia.org/wiki/B%C3%A9zier_curve#Cubic_B%C3%A9zier_curves
+        """
+        assert 0 <= t <= 1
         return (
             (((1.0 - t) ** 3) * p[0])
-            + (3 * t * ((1.0 - t) ** 2) * p[1])
+            + (3.0 * t * ((1.0 - t) ** 2) * p[1])
             + (3.0 * (t ** 2) * (1.0 - t) * p[2])
             + ((t ** 3) * p[3])
         )

graphviz2drawio/mx/Curve.py

@@ -7,13 +7,15 @@ def variance(points, m):
 
 
 def covariance(points, m):
+    """Returns the covariance of a list of complex points"""
     covar = 0.0
     for point in points:
         covar += (point.real - m.real) * (point.imag - m.imag)
     return covar
 
 
 def determination(points, y_mean, b0, b1):
+    """Returns the coefficient of determination (R**2) for linear equation and list of complex points"""
     sse = []
     sst = []
     for point in points:
@@ -29,6 +31,7 @@ def determination(points, y_mean, b0, b1):
 
 
 def coefficients(points):
+    """Returns the coefficents of a linear equation and R**2 as a list for a list of complex points"""
     x = [point.real for point in points]
     m = mean(points)
     var = variance(x, m.real)