great-tables icon indicating copy to clipboard operation
great-tables copied to clipboard

numpy: add docstring examples showing typical _normalize_to_dict inputs

Open machow opened this issue 5 months ago • 0 comments

In great_tables._utils_nanoplots, the _normalize_to_dict() is used 7 times. However, it's not clear to me what concretely it gets feed in these 7 different situations.

Let's add examples to the docstring, illustrating concretely how it's used in these different situations. If each of the 7 situations use it differently, I'm onboard with 7 examples. Otherwise, I'd say whatever captures the variability in uses works!

I would try triggering the debugger for each of the 7 calls, and then printing / exploring its inputs and output. The tests in tests/test__utils_nanoplots.py could be helpful for triggering the debugger.

Let's just add an examples section, with a python block for now. E.g.

def _normalize_to_dict(**kwargs: list[int | float]) -> dict[str, list[int | float]]:
    """
    Normalize a collection of numeric values to be between 0 and 1. Account for missing values.
    This only accepts values (scalar or list) associated with keyword arguments. A dictionary
    is returned with the same keys but the values are normalized lists. This is done so that
    any disparate collection of normalized values are distinguishable by their original keys.

    ```{python}
    # case 1: short description
    code here...

    # case 2: short description
    code here...
    ```
    """

machow avatar Jun 04 '25 16:06 machow