docs: consistent docstrings & defaults for rotation arguments

stimupy/components/__init__.py

@@ -35,7 +35,7 @@ def image_base(visual_size=None, shape=None, ppd=None, rotation=0.0, origin="mea
     shape : Sequence[Number, Number], Number, or None (default)
         shape [height, width] of image, in pixels
     rotation : float, optional
-        rotation (in degrees) counterclockwise from 3 o'clock, by default 0.0
+        rotation (in degrees) from 3 o'clock, counterclockwise, by default 0.0
     origin : "corner", "mean" or "center"
         if "corner": set origin to upper left corner
         if "mean": set origin to hypothetical image center (default)
@@ -145,7 +145,7 @@ def mask_regions(
     shape : Sequence[Number, Number], Number, or None (default)
         shape [height, width] of image, in pixels
     rotation : float, optional
-        rotation (in degrees) counterclockwise from 3 o'clock, by default 0.0
+        rotation (in degrees) from 3 o'clock, counterclockwise, by default 0.0
     origin : "corner", "mean" or "center"
         if "corner": set origin to upper left corner
         if "mean": set origin to hypothetical image center (default)

stimupy/components/angulars.py

@@ -83,8 +83,7 @@ def wedge(
     radius : float
         radius of disc, in degrees visual angle
     rotation : float, optional
-        angle of rotation (in degrees) of segment,
-        counterclockwise from 3 o'clock, by default 0.0
+        rotation (in degrees) from 3 o'clock, counterclockwise, by default 0.0
     inner_radius : float, optional
         inner radius (in degrees visual angle), to turn disc into a ring, by default 0
     intensity_wedge : float, optional
@@ -155,8 +154,7 @@ def mask_segments(
     edges : Sequence[Number]
         upper-limit of each consecutive segment, in angular degrees 0-360
     rotation : float, optional
-        angle of rotation (in degrees) of segments,
-        counterclockwise away from 3 o'clock, by default 0.0
+        rotation (in degrees) from 3 o'clock, counterclockwise, by default 0.0
     visual_size : Sequence[Number, Number], Number, or None (default)
         visual size [height, width] of image, in degrees
     ppd : Sequence[Number, Number], Number, or None (default)
@@ -212,8 +210,7 @@ def segments(
     angles : Sequence[Number] or None (default)
         upper-limit of each segment, in angular degrees 0-360
     rotation : float, optional
-        angle of rotation (in degrees) of segments,
-        counterclockwise away from 3 o'clock, by default 0.0angles
+        rotation (in degrees) from 3 o'clock, counterclockwise, by default 0.0
     intensity_background : Number
         intensity value for background; default is 0.5.
     intensity_segments : Sequence[Number, ...]

stimupy/components/edges.py

@@ -28,8 +28,8 @@ def step(
         pixels per degree [vertical, horizontal]
     shape : Sequence[Number, Number], Number, or None (default)
         shape [height, width] of image, in pixels
-    rotation : float
-        rotation of stimulus in degrees (default: 0)
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0
     intensity_edges : (float, float)
         intensity values of edges (default: (0., 1.))
 
@@ -88,8 +88,8 @@ def gaussian(
         shape [height, width] of image, in pixels
     sigma : float or (float, float)
         sigma of Gaussian in degree visual angle (y, x)
-    rotation : float
-        rotation of stimulus in degrees (default: 0)
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0
     intensity_edges : (float, float)
         intensity values of edges (default: (0., 1.))
     intensity_background : float
@@ -134,7 +134,7 @@ def cornsweet(
     ppd=None,
     shape=None,
     ramp_width=None,
-    rotation=0,
+    rotation=0.0,
     intensity_edges=(0.0, 1.0),
     intensity_plateau=0.5,
     exponent=2.75,
@@ -159,8 +159,8 @@ def cornsweet(
         shape [height, width] of grating, in pixels
     ramp_width : float
         width of luminance ramp in degrees of visual angle
-    rotation : float
-        rotation of stimulus in degrees (default: 0)
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0
     intensity_edges : (float, float)
         intensity of edges
     intensity_plateau : float

stimupy/components/gaussians.py

@@ -13,7 +13,7 @@ def gaussian(
     ppd=None,
     shape=None,
     sigma=None,
-    rotation=0,
+    rotation=0.0,
     intensity_max=1.0,
     origin="mean",
 ):
@@ -29,8 +29,8 @@ def gaussian(
         shape [height, width] of image, in pixels
     sigma : float or (float, float)
         Sigma auf Gaussian in degree visual angle (y, x)
-    rotation : float
-        Rotation of Gaussian in degree (default 0)
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0
     intensity_max : float
         Maximal intensity value of Gaussian
     origin : "corner", "mean" or "center"

stimupy/components/lines.py

@@ -22,7 +22,7 @@ def line(
     line_position=None,
     line_length=None,
     line_width=0,
-    rotation=0,
+    rotation=0.0,
     intensity_line=1,
     intensity_background=0,
     origin="corner",
@@ -45,8 +45,8 @@ def line(
     line_width : Number
         width of the line, in degrees visual angle;
         if line_width=0 (default), line will be one pixel wide
-    rotation : float
-        rotation of grating in degrees (default: 0 = horizontal)
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0 (horizontal)
     intensity_line : Number
         intensity value of the line (default: 1)
     intensity_background : Number
@@ -137,7 +137,7 @@ def dipole(
     line_length=None,
     line_width=0,
     line_gap=None,
-    rotation=0,
+    rotation=0.0,
     intensity_lines=(0, 1),
 ):
     """Draw a two centered parallel lines
@@ -157,8 +157,8 @@ def dipole(
         if line_width=0 (default), line will be one pixel wide
     line_gap : Number
         distance between line centers, in degrees visual angle
-    rotation : float
-        rotation of grating in degrees (default: 0 = horizontal)
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0 (horizonal)
     intensity_lines : (Number, Number)
         intensity value of the line (default: (0, 1));
         background intensity is the mean of these two values

stimupy/components/shapes.py

@@ -27,7 +27,7 @@ def rectangle(
     rectangle_position=None,
     intensity_rectangle=1.0,
     intensity_background=0.0,
-    rotation=0,
+    rotation=0.0,
 ):
     """Draw a rectangle
 
@@ -48,8 +48,8 @@ def rectangle(
         intensity value for rectangle, by default 1.0
     intensity_background : float, optional
         intensity value of background, by default 0.0
-    rotation : float
-        rotation of rectangle in degrees visual angle (default 0)
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0 (horizonal)
 
     Returns
     -------
@@ -145,7 +145,7 @@ def triangle(
     intensity_triangle=1.0,
     intensity_background=0.0,
     include_corners=True,
-    rotation=0,
+    rotation=0.0,
 ):
     """Draw a triangle
 
@@ -163,8 +163,8 @@ def triangle(
         intensity value for triangle, by default 1.0
     intensity_background : float, optional
         intensity value of background, by default 0.0
-    rotation : float
-        rotation of triangle in degrees visual angle (default 0)
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0
 
     Returns
     -------
@@ -233,7 +233,7 @@ def cross(
     cross_arm_ratios=(1.0, 1.0),
     intensity_cross=1.0,
     intensity_background=0.0,
-    rotation=0,
+    rotation=0.0,
 ):
     """Draw a cross
 
@@ -255,8 +255,8 @@ def cross(
         intensity value for cross, by default 1.0
     intensity_background : float, optional
         intensity value of background, by default 0.0
-    rotation : float
-        rotation of triangle in degrees visual angle (default 0)
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0
 
     Returns
     -------
@@ -339,7 +339,7 @@ def parallelogram(
     parallelogram_size=None,
     intensity_parallelogram=1.0,
     intensity_background=0.0,
-    rotation=0,
+    rotation=0.0,
 ):
     """Draw a parallelogram
 
@@ -357,8 +357,8 @@ def parallelogram(
         intensity value for parallelogram, by default 1.0
     intensity_background : float, optional
         intensity value of background, by default 0.0
-    rotation : float
-        rotation of triangle in degrees visual angle (default 0)
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0
 
     Returns
     -------
@@ -451,7 +451,7 @@ def ellipse(
     radius=None,
     intensity_ellipse=1.0,
     intensity_background=0.0,
-    rotation=0,
+    rotation=0.0,
     origin="mean",
     restrict_size=True,
 ):
@@ -471,8 +471,8 @@ def ellipse(
         intensity value for ellipse, by default 1.0
     intensity_background : float, optional
         intensity value of background, by default 0.0
-    rotation : float
-        rotation of triangle in degrees visual angle (default 0)
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0
     origin : "corner", "mean" or "center"
         if "corner": set origin to upper left corner
         if "mean": set origin to hypothetical image center (default)
@@ -588,7 +588,7 @@ def circle(
         radius=radius,
         intensity_ellipse=intensity_circle,
         intensity_background=intensity_background,
-        rotation=0,
+        rotation=0.0,
         origin=origin,
         restrict_size=restrict_size,
     )

stimupy/components/waves.py

@@ -280,8 +280,8 @@ def sine(
         ensure whether the grating has "even" number of phases, "odd"
         number of phases, either or whether not to round the number of
         phases ("ignore")
-    rotation : float
-        rotation of grating in degrees, by default 0.0
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0 (horizonal)
     phase_shift : float
         phase shift of grating in degrees, by default 0.0
     intensities : Sequence[float, float]
@@ -503,8 +503,8 @@ def square(
         ensure whether the grating has "even" number of phases, "odd"
         number of phases, either or whether not to round the number of
         phases ("ignore")
-    rotation : float
-        rotation of grating in degrees, by default 0.0
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0 (horizonal)
     phase_shift : float
         phase shift of grating in degrees, by default 0.0
     intensities : Sequence[float, float]
@@ -587,8 +587,8 @@ def staircase(
         ensure whether the grating has "even" number of phases, "odd"
         number of phases, either or whether not to round the number of
         phases ("ignore")
-    rotation : float
-        rotation of grating in degrees, by default 0.0
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0 (horizonal)
     phase_shift : float
         phase shift of grating in degrees, by default 0.o
     origin : "corner", "mean", or "center" (default)
@@ -687,7 +687,7 @@ def bessel(
         visual_size=visual_size,
         ppd=ppd,
         shape=shape,
-        rotation=0,
+        rotation=0.0,
         origin=origin,
     )
 

stimupy/stimuli/benarys.py

@@ -22,7 +22,7 @@ def cross_generalized(
     cross_thickness=None,
     target_size=None,
     target_type="r",
-    target_rotation=0,
+    target_rotation=0.0,
     target_x=None,
     target_y=None,
     intensity_background=1.0,
@@ -45,8 +45,8 @@ def cross_generalized(
         size of all target(s) in degrees visual angle
     target_type : tuple of strings
         type of targets to use; option: r (rectangle), t (triangle); as many targets as types
-    target_rotation : tuple of floats
-        tuple with rotation of targets in deg, as many targets as rotations
+    target_rotation : tuple of floats, or float
+        tuple with rotation of targets in deg, counterclockwise, as many targets as rotations
     target_x : tuple of floats
         tuple with x coordinates of targets in degrees, as many targets as coordinates
     target_y : tuple of floats
@@ -302,7 +302,7 @@ def todorovic_generalized(
     L_width=None,
     target_size=None,
     target_type="r",
-    target_rotation=0,
+    target_rotation=0.0,
     target_x=None,
     target_y=None,
     intensity_background=1.0,
@@ -326,8 +326,8 @@ def todorovic_generalized(
         size of all target(s) in degrees visual angle
     target_type : tuple of strings
         type of targets to use; option: r (rectangle), t (triangle); as many targets as types
-    target_rotation : tuple of floats
-        tuple with rotation of targets in deg, as many targets as rotations
+    target_rotation : tuple of floats, or float
+        tuple with rotation of targets in deg, counterclockwise, as many targets as rotations
     target_x : tuple of floats
         tuple with x coordinates of targets in degrees, as many targets as coordinates
     target_y : tuple of floats
@@ -467,7 +467,7 @@ def todorovic_rectangles(
         L_width=L_width,
         target_size=target_size,
         target_type=("r",) * 2,
-        target_rotation=0,
+        target_rotation=0.0,
         target_x=np.round(np.array(target_x) * ppd) / ppd,
         target_y=np.round(np.array(target_y) * ppd) / ppd,
         intensity_background=intensity_background,
@@ -581,8 +581,8 @@ def add_targets(
         size of all target(s) in degrees visual angle
     target_type : tuple of strings
         type of targets to use; option: r (rectangle), t (triangle); as many targets as types
-    target_rotation : tuple of floats
-        tuple with rotation of targets in deg, as many targets as rotations
+    target_rotation : tuple of floats, or float
+        tuple with rotation of targets in deg, counterclockwise, as many targets as rotations
     target_x : tuple of floats
         tuple with x coordinates of targets in degrees, as many targets as coordinates
     target_y : tuple of floats

stimupy/stimuli/checkerboards.py

@@ -119,7 +119,7 @@ def checkerboard(
     target_indices=None,
     extend_targets=False,
     period="ignore",
-    rotation=0,
+    rotation=0.0,
     intensity_checks=(0.0, 1.0),
     intensity_target=0.5,
     round_phase_width=True,
@@ -154,8 +154,8 @@ def checkerboard(
         ensure whether the grating has "even" number of phases, "odd"
         number of phases, either or whether not to round the number of
         phases ("ignore")
-    rotation : float
-        rotation of grating in degrees (default: 0 = horizontal)
+    rotation : float, optional
+        rotation (in degrees), counterclockwise, by default 0.0 (horizonal)
     intensity_checks : Sequence[float, float]
         intensity values of checks, by default (0.0, 1.0)
     round_phase_width : Bool
@@ -316,7 +316,7 @@ def contrast_contrast(
     check_visual_size=None,
     target_shape=None,
     period="ignore",
-    rotation=0,
+    rotation=0.0,
     intensity_checks=(0.0, 1.0),
     tau=0.5,
     alpha=None,