yieldplotlib.util
=================

.. py:module:: yieldplotlib.util

.. autoapi-nested-parse::

   Utility functions.



Functions
---------

.. autoapisummary::

   yieldplotlib.util.get_nice_number
   yieldplotlib.util.calculate_axis_limits_and_ticks
   yieldplotlib.util.is_monotonic
   yieldplotlib.util.rgetattr
   yieldplotlib.util.discretize_colormap
   yieldplotlib.util.find_unit_for_module_key
   yieldplotlib.util.get_unit


Module Contents
---------------

.. py:function:: get_nice_number(value, round=False)

   Calculates a "nice" number for labeling axes in a plot.

   Args:
       value (float):
           The value to be transformed into a "nice" number.
       round (bool, optional):
           If True, rounds the number to the nearest "nice" number. If False,
           the number is only scaled to be a "nice" number.

   Returns:
       float:
           A "nice" number that is a rounded or scaled version of the input value.


.. py:function:: calculate_axis_limits_and_ticks(data_min, data_max, num_ticks=5, exact=False)

   Calculates the axis limits and tick spacing for a plot.

   Args:
       data_min (float):
           The minimum value of the data.
       data_max (float):
           The maximum value of the data.
       num_ticks (int, optional):
           The desired number of tick marks on the axis. Default is 5.
       exact (bool, optional):
           If True, use exact min and max values for the limits. If False, the
           limits are adjusted to "nice" values.

   Returns:
       tuple:
           nice_min (float):
               The adjusted minimum axis limit.
           nice_max (float):
               The adjusted maximum axis limit.
           tick_spacing (float):
               The spacing between ticks.
           offset (float):
               A small offset to apply to the axis limits for better visualization.


.. py:function:: is_monotonic(x)

   Checks if an array is monotonic.


.. py:function:: rgetattr(obj, attr, *args)

   Recursively get attributes of an object.


.. py:function:: discretize_colormap(num_colors, colormap_name, start_frac=0.1, end_frac=0.9)

   Returns evenly spaced discrete colors from a matplotlib colormap.


.. py:function:: find_unit_for_module_key(module_key, module_name, key_map)

   Find the unit for a given module-specific key.

   Searches through the KEY_MAP to find a mapping where the provided module key
   matches the 'name' field for the specified module. If found, returns the
   corresponding unit.

   Args:
       module_key (str):
           The module-specific key (e.g., 'Angdiam (mas)' for AYO,
           'pixelScale' for EXOSIMS).
       module_name (str):
           The name of the module (e.g., 'AYOCSVFile', 'EXOSIMSInputFile').
       key_map (dict):
           The key mapping dictionary to use for lookups.

   Returns:
       str or None:
           The unit string if found, None otherwise.


.. py:function:: get_unit(key, module_name, find_unit_func=None)

   Get the associated unit for a given key.

   This generic method handles both yieldplotlib keys and module-specific keys:
   1. First tries a direct lookup in KEY_MAP (assuming key is a yieldplotlib key)
   2. If not found, tries to find the corresponding yieldplotlib key by looking up
      the module-specific key in KEY_MAP

   Args:
       key (str):
           The key to look up the unit for (can be either a yieldplotlib key
           or a module-specific key).
       module_name (str):
           The name of the module making the request (used for KEY_MAP lookup).
       find_unit_func (callable, optional):
           Optional custom fallback function that takes a key and returns a
           unit string. If None, the built-in find_unit_for_module_key
           function will be used.

   Returns:
       astropy.units.Unit or None:
           The astropy Unit object if found, None otherwise.