Merge pull request #161 from curveresearch/docstrings

Add docstrings for chart utils

curvesim/plot/altair/chart_properties.py

@@ -1,10 +1,33 @@
+"""
+This module provides functionality for creating and manipulating chart properties.
+
+It contains utility functions for creating keyword arguments for a chart, updating
+and initializing chart properties, and handling property-specific behaviors.
+"""
 from copy import deepcopy
 from functools import partial
 
 from altair import Color, MarkDef, X, Y
 
 
 def make_chart_kwargs(default, override_dicts):
+    """
+    Create the keyword arguments for a chart by updating a default dictionary with
+    values from a list of override dictionaries.
+
+    Parameters
+    ----------
+    default : dict
+        The default keyword arguments for the chart.
+    override_dicts : list
+        A list of dictionaries containing addtional keyword arguments and/or overrides
+        for the default keyword arguments.
+
+    Returns
+    -------
+    dict
+        A dictionary containing the keyword arguments for the chart.
+    """
     chart_kwargs = deepcopy(default)
 
     for d in override_dicts:
@@ -16,6 +39,25 @@ def make_chart_kwargs(default, override_dicts):
 
 
 def update_properties(prop_dict, key, val, depth=0, count=0):
+    """
+    Update properties in a dictionary. If the current depth matches the target depth,
+    the value is updated directly. Otherwise, the function is called recursively on
+    nested dictionaries.
+
+    Parameters
+    ----------
+    prop_dict : dict
+        The dictionary of properties to update.
+    key : str
+        The key of the property to update.
+    val : any
+        The new value for the property.
+    depth : int, optional
+        The target depth for the update. Defaults to 0.
+    count : int, optional
+        The current depth of the update. Defaults to 0.
+    """
+
     if depth in [0, count]:
         prop_dict[key] = val
     else:
@@ -25,6 +67,19 @@ def update_properties(prop_dict, key, val, depth=0, count=0):
 
 
 def concat_properties(prop_dict, key, val):
+    """
+    Concatenate values to a property in a dictionary. If the value is a list, extend
+    the property with it. Otherwise, append the value to the property.
+
+    Parameters
+    ----------
+    prop_dict : dict
+        The dictionary of properties to update.
+    key : str
+        The key of the property to update.
+    val : any
+        The value to concatenate to the property.
+    """
     prop_dict.setdefault(key, [])
 
     if isinstance(val, list):
@@ -34,10 +89,44 @@ def concat_properties(prop_dict, key, val):
 
 
 def ignore_property(prop_dict, key, val):  # pylint: disable=unused-argument
-    pass
+    """
+    Ignore a property during an update operation. This function does nothing and is
+    intended to be used as a placeholder in UPDATE_RULES where certain properties
+    should be ignored.
+
+    Parameters
+    ----------
+    prop_dict : dict
+        The dictionary of properties to update.
+    key : str
+        The key of the property to ignore.
+    val : any
+        The value of the property to ignore.
+    """
 
 
 def init_properties(prop_dict, classes=None):
+    """
+    Initialize the properties of a dictionary using a mapping of classes. If a
+    property's key is present in the classes dictionary, its value is replaced
+    with an instance of the corresponding class, initialized with the value as
+    keyword arguments.
+
+    Parameters
+    ----------
+    prop_dict : dict
+        The dictionary of properties to initialize.
+    classes : dict, optional
+        A dictionary mapping keys to classes. If a key in prop_dict matches a
+        key in classes, the value in prop_dict is replaced with an instance of
+        the corresponding class. Defaults to PROPERTY_CLASSES.
+
+    Returns
+    -------
+    dict
+        The dictionary of properties, with values replaced with class instances
+        where applicable.
+    """
     classes = classes or PROPERTY_CLASSES
     for key, val in prop_dict.items():
         try:

curvesim/plot/altair/make_chart.py

@@ -1,14 +1,47 @@
-from altair import Scale, Chart, data_transformers
+"""
+This module provides functionality for creating Altair charts with custom styles.
+
+It contains utility functions for creating charts and default chart properties. It
+uses styles defined in the .styles module and allows custom configuration of chart
+properties.
+"""
+from altair import Chart, Scale, data_transformers
 
 from curvesim.exceptions import PlotError
+
 from .chart_properties import make_chart_kwargs
 from .styles import STYLES
 
-
 data_transformers.disable_max_rows()
 
 
 def make_chart(config, x=None, y=None, color=None, **kwargs):
+    """
+    Create an interactive chart with custom properties and styles.
+
+    Parameters
+    ----------
+    config : dict
+        The configuration dictionary for the chart. Must contain a 'style' key.
+    x : str or dict, optional
+        The x-axis property. Can be a shorthand string or a dictionary of alt.X kwargs.
+    y : str or dict, optional
+        The y-axis property. Can be a shorthand string or a dictionary of alt.Y kwargs.
+    color : str or dict, optional
+        The color property. Can be a shorthand string or a dictionary of alt.Color kwargs.
+    **kwargs
+        Additional keyword arguments are added to the chart configuration.
+
+    Returns
+    -------
+    altair.Chart
+        The created chart.
+
+    Raises
+    ------
+    PlotError
+        If no style is found in the config or if the style is not found in STYLES.
+    """
     title = config.get("title", "")
 
     try:
@@ -26,7 +59,31 @@ def make_chart(config, x=None, y=None, color=None, **kwargs):
     return Chart(**chart_kwargs).interactive()
 
 
-def make_defaults(title, x, y, color):
+def make_defaults(title, x=None, y=None, color=None):
+    """
+    Create default properties for a chart.
+
+    Parameters
+    ----------
+    title : str
+        The title of the chart.
+    x : str or dict, optional
+        The x-axis property. Can be a shorthand string or a dictionary of alt.X kwargs.
+    y : str or dict, optional
+        The y-axis property. Can be a shorthand string or a dictionary of alt.Y kwargs.
+    color : str or dict, optional
+        The color property. Can be a shorthand string or a dictionary of alt.Color kwargs.
+
+    Returns
+    -------
+    dict
+        The default properties for a chart.
+
+    Raises
+    ------
+    PlotError
+        If x, y, or color is not a string (shorthand) or a dictionary (altair kwargs).
+    """
     defaults = {
         "title": title,
         "encoding": {

curvesim/plot/altair/results/__init__.py

@@ -0,0 +1 @@
+"""Submodule with resources for plotting simulation results with Altair."""