Docstrings

Author: eltos

xplt/line.py

@@ -45,11 +45,12 @@ def order(knl):
 
 
 class KnlPlot(XManifoldPlot):
+    """A plot for knl values along line"""
+
     def __init__(
         self, line=None, *, knl=None, filled=True, resolution=1000, line_length=None, **kwargs
     ):
         """
-        A plot for knl values along line
 
         Args:
             line (xtrack.Line): Line of elements.
@@ -183,6 +184,8 @@ def label_for(self, *pp, unit=True, description=True):
 
 
 class FloorPlot(XPlot):
+    """A floor plan of the line based on survey data"""
+
     def __init__(
         self,
         survey=None,
@@ -195,7 +198,6 @@ def __init__(
         **kwargs,
     ):
         """
-        A floor plan of the line based on survey data
 
         Args:
             survey (Any): Survey data.

xplt/particles.py

@@ -21,13 +21,18 @@
 
 
 class ParticlePlotMixin:
+    """Mixin for plotting of particle data
+
+    .. automethod:: _init_particle_mixin
+    """
+
     def _init_particle_mixin(
         self, *, twiss=None, beta=None, frev=None, circumference=None, **kwargs
     ):
-        r"""Mixin for plotting of particle data
+        r"""Initializes the mixin by providing associated information
 
-        In addition to the inherent particle properties (like ``x``, ``y``, ``px``, ``py``, ``zeta``, ``delta``, ...)
-        the following derived properties are supported (but may require passing of twiss etc.):
+        For a given particle object with inherent properties like ``x``, ``y``, ``px``, ``py``, ``zeta``, ``delta``, etc.
+        this mixin allows determination of the following derived properties:
 
         - Normalized coordinates: ``X``, ``Y``, ``Px``, ``Py``
            |  :math:`X = x/\sqrt{\beta_x} = \sqrt{2J_x} \cos(\Theta_x)`
@@ -43,7 +48,7 @@ def _init_particle_mixin(
 
         Args:
             twiss (dict | None): Twiss parameters (alfx, alfy, betx and bety) to use for conversion to normalized phase space coordinates.
-            beta (float | None): Relativistic beta of particles. Defaults to particles.beta0.
+            beta (float | None): Relativistic beta of particles. Defaults to `beta0` property of particles.
             frev (float | None): Revolution frequency of circular line for calculation of particle time.
             circumference (float | None): Path length of circular line if frev is not given.
             kwargs: Keyword arguments for :class:`~.base.XPlot`
@@ -90,6 +95,7 @@ def _init_particle_mixin(
 
     @property
     def circumference(self):
+        """Circumference of circular accelerator"""
         if self._circumference is not None:
             return self._circumference
         if self.twiss is not None:
@@ -167,6 +173,7 @@ def _particle_time(self, turn, zeta, particles=None):
     def get_property(self, name):
         # Note: this method is not used by the library, but it's handy for standalone use
         """Public method to get a particle property by key
+
         Args:
             name (str): Key
         Returns:
@@ -177,6 +184,8 @@ def get_property(self, name):
 
 
 class ParticlesPlot(XManifoldPlot, ParticlePlotMixin):
+    """A plot of particle properties as function of another property"""
+
     def __init__(
         self,
         particles=None,
@@ -189,7 +198,6 @@ def __init__(
         **kwargs,
     ):
         """
-        A plot of particle properties as function of another property.
 
         Args:
             particles (Any): Particles data to plot.

xplt/phasespace.py

@@ -24,6 +24,8 @@
 
 
 class PhaseSpacePlot(XPlot, ParticlePlotMixin):
+    """A plot for phase space distributions"""
+
     def __init__(
         self,
         particles=None,
@@ -53,7 +55,6 @@ def __init__(
         **kwargs,
     ):
         """
-        A plot for phase space distributions
 
         Args:
             particles (Any): A dictionary with particle information
@@ -64,22 +65,22 @@ def __init__(
                      In addition, abbreviations for x-y-parameter pairs are supported (e.g. 'x' for 'x-px').
                      For normalized coordinates, use uppercase letters (e.g. 'X' for 'X-Px').
             plot (str): Defines the type of plot. Can be 'auto', 'scatter' or 'hist'. Default is 'auto' for which the plot type is chosen automatically based on the number of particles.
-            scatter_kwargs (dict): Additional kwargs for scatter plot
-            hist_kwargs (dist): Additional kwargs for 2D histogram plot (see :meth:`matplotlib.pyplot.hexbin`)
+            scatter_kwargs (dict): Additional kwargs for scatter plot, see :meth:`matplotlib.axes.Axes.scatter`.
+            hist_kwargs (dist): Additional kwargs for 2D histogram plot, see :meth:`matplotlib.axes.Axes.hexbin`.
             mask (Any): An index mask to select particles to plot. If None, all particles are plotted.
             masks (list[mask]): List of masks for each subplot.
             color (str | list[str]): Properties defining the color of points for the scatter plot(s). Implies plot='scatter'. Pass a list of properties to use different values for each subplot
             cmap (str): Colormap to use for the hist plot.
             cbar_loc (str): Location of the colorbar, such as 'auto', 'right', 'inside upper right', etc.
                             Use None to disable colorbar.
             projections (bool | str | list): Add histogrammed projections onto axis. Can be True, False, "x", "y", "auto" or a list of these for each subplot
-            projections_kwargs (dict): Additional kwargs for histogram projection (step plot)
+            projections_kwargs (dict): Additional kwargs for histogram projection, see :meth:`matplotlib.axes.Axes.step`.
             mean (bool | list): Whether to indicate mean of distribution with a cross marker. Boolean or list of booleans for each subplot.
-            mean_kwargs (dict): Additional kwargs for mean cross
+            mean_kwargs (dict): Additional kwargs for marker, see :meth:`matplotlib.axes.Axes.plot`.
             std (bool | list): Whether to indicate standard deviation of distribution with an ellipse. Boolean or list of booleans for each subplot.
-            std_kwargs (dict): Additional kwargs for std ellipses.
+            std_kwargs (dict): Additional kwargs for std ellipses, see :class:`matplotlib.patches.Ellipse`.
             percentiles (list): List of percentiles (in percent) to indicate in the distribution with ellipses. Can also be a list of lists for each subplot.
-            percentile_kwargs (dict): Additional kwargs for percentile ellipses.
+            percentile_kwargs (dict): Additional kwargs for percentile ellipses, see :class:`matplotlib.patches.Ellipse`.
             ncols (int | None): Number of columns in subplot layout. If None, the layout is determined automatically.
             nrows (int | None): Number of columns in subplot layout. If None, the layout is determined automatically.
             titles (list[str]): List of titles for each subplot or 'auto' to automatically set titles based on plot kind.

xplt/timestructure.py

@@ -95,6 +95,8 @@ def binned_timeseries(times, *, what=None, n=None, dt=None, t_range=None, moment
 
 
 class TimePlot(ParticlesPlot):
+    """A plot of particle properties as function of time"""
+
     def __init__(self, particles=None, kind="x+y", **kwargs):
         """
         A thin wrapper around the ParticlesPlot plotting data as function of time.
@@ -116,6 +118,8 @@ def __init__(self, particles=None, kind="x+y", **kwargs):
 
 
 class TimeBinPlot(XManifoldPlot, ParticlePlotMixin):
+    """A binned histogram plot of particles as function of times"""
+
     def __init__(
         self,
         particles=None,
@@ -132,7 +136,6 @@ def __init__(
         **kwargs,
     ):
         """
-        A binned histogram plot of particles as function of times.
 
         The plot is based on the particle arrival time, which is:
             - For circular lines: at_turn / frev - zeta / beta / c0
@@ -309,6 +312,8 @@ def update(self, particles, mask=None, autoscale=False):
 
 
 class TimeFFTPlot(XManifoldPlot, ParticlePlotMixin):
+    """A frequency plot based on particle arrival times"""
+
     def __init__(
         self,
         particles=None,
@@ -324,7 +329,6 @@ def __init__(
         **kwargs,
     ):
         """
-        A frequency plot based on particle arrival times.
 
         The particle arrival time is:
             - For circular lines: at_turn / frev - zeta / beta / c0
@@ -521,6 +525,8 @@ def plot_harmonics(self, f, df=0, *, n=20, **plot_kwargs):
 
 
 class TimeIntervalPlot(XManifoldPlot, ParticlePlotMixin):
+    """A histogram plot of particle arrival intervals (i.e. delay between consecutive particles)"""
+
     def __init__(
         self,
         particles=None,
@@ -536,7 +542,6 @@ def __init__(
         **kwargs,
     ):
         """
-        A histogram plot of particle arrival intervals (i.e. delay between consecutive particles).
 
         The plot is based on the particle arrival time, which is:
             - For circular lines: at_turn / frev - zeta / beta / c0
@@ -819,6 +824,8 @@ def _format_metric_axes(self, add_compatible_twin_axes):
 
 
 class TimeVariationPlot(XManifoldPlot, ParticlePlotMixin, MetricesMixin):
+    """Plot variability of particle time on microscopic scale as function of time on macroscopic scale"""
+
     def __init__(
         self,
         particles=None,
@@ -836,7 +843,6 @@ def __init__(
         **kwargs,
     ):
         """
-        Plot variability of particle time on microscopic scale as function of time on macroscopic scale
 
         The particle arrival times are histogramed into counting bins, the width of which
         corresponds to the time resolution of a detector (``counting_dt``).
@@ -979,6 +985,8 @@ def update(self, particles, mask=None, autoscale=False):
 
 
 class TimeVariationScalePlot(XManifoldPlot, ParticlePlotMixin, MetricesMixin):
+    """Plot variability of particle time as function of timescale"""
+
     def __init__(
         self,
         particles=None,
@@ -996,7 +1004,7 @@ def __init__(
         ignore_insufficient_statistics=False,
         **kwargs,
     ):
-        """Plot variability of particle time as function of timescale
+        """
 
         The particle arrival times are histogramed into counting bins, the width of which
         corresponds to the time resolution of a detector (``counting_dt``).
@@ -1200,8 +1208,10 @@ def update(
 
 
 class TimeBinMetricHelper(ParticlePlotMixin, MetricesMixin):
+    """Helper class for binning and evaluating metrices on timeseries data"""
+
     def __init__(self, *, twiss=None, beta=None, frev=None, circumference=None):
-        """Helper class for binning and evaluating metrices on timeseries data.
+        """
 
         Args:
             twiss (dict | None): Twiss parameters (alfx, alfy, betx and bety) to use for conversion to normalized phase space coordinates.

xplt/twiss.py

@@ -17,9 +17,10 @@
 
 
 class TwissPlot(XManifoldPlot):
+    """A plot for twiss parameters and closed orbit"""
+
     def __init__(self, twiss=None, kind="bet-dx,x+y", *, line=None, line_kwargs={}, **kwargs):
         """
-        A plot for twiss parameters and closed orbit
 
         Args:
             twiss (Any): Dictionary with twiss information