ENH: Add argument to apply `formatters` in `DataFrame.to_string` to the index

[ntjess]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/dev/reference/api/pandas.DataFrame.to_string.html?highlight=formatters

Documentation problem

The current to_string documentation for formatters indicates formatting can be applied to columns, but it is unclear whether anything can be set for the index as well. Deep within format.py, it appears adding an __index__ key to formatters will handle this well. I tested with the code below which seemed to work:

import pandas as pd
fmt = "{:.4f}".format
fmt_dict = dict(__index__=fmt)
print(pd.DataFrame([[1,2,3]]).to_string(formatters=fmt_dict))

Is this feature meant to be public? If so, I would recommend exposing it in the formatters parameter description. Thanks!

Suggested fix for documentation

New formatters description resembling the following. Added sentence is italicized:

Formatter functions to apply to columns’ elements by position or name. The result of each function must be a unicode string. List/tuple must be of length equal to the number of columns. If a dict-like formatter is specified, the dataframe's index can be formatted with an __index__ key.

---

Alternatively, the MWE in this issue (or something similar) can be added to the Examples section.

[ntjess]

As a side-note, this will also lead to strange behavior for someone with a column named __index__, but I imagine that scenario is somewhat unlikely.

[mroeschke]

I would venture to guess since it's labeled __index__, this was intended to be an internal convention and not to be public.

If formatting applied to the index is desired, it would be better if a new keyword was added (formatting_axis) was added instead so the intention is clear.

[ntjess]

Would it make more sense to add an index_formatter=... keyword instead? Otherwise, my first impression is that formatting_axis="index" would apply a formatter per index label (and formatting_index="columns" would replicate current behavior -- acting on the axis names)

Edit: I forgot MultiIndex was a thing, but it still might be confusing for people unfamiliar with them. However, unless formatting_axis could take both axes at once (i.e. formatting_axis=["index", "columns"]), I would still prefer a separate kwarg. Otherwise, to_string wouldn't be able to format both the index and columns at the same time

[mroeschke]

Good point. Agreed it would be good for index formatting to be independent from the column formatting, but it would be odd to have a formatters and index_formatter argument.

Appears formatters can take a dict, maybe the dict support can be expanded somehow to indicate to apply the formatting to the index?

[ntjess]

Something like an __index__ key? 😉 Joking aside, one straightforward solution is to have the dict formatters also searched for index names. Example usage:

import pandas as pd
fmt = "{:.4f}".format
df = pd.DataFrame([[1,2,3]]).rename_axis(index="test")
fmt_dict = dict(test=fmt)
#               ^^^^ matches index name
print(df.to_string(formatters=fmt_dict))

As of the latest pandas release, this code does not format the index.

[mroeschke]

Yeah that sound reasonable (with consideration of overlapping labels). As long as it's explicit :)