BUG: EngFormatter accuracy wrong

[cparg]

Pandas version checks

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of pandas.

• I have confirmed this bug exists on the main branch of pandas.

Reproducible Example

from pandas.io.formats.format import EngFormatter

def test_eng_formatter():
    formatter4 = EngFormatter(use_eng_prefix=True, accuracy=4)
    formatter5 = EngFormatter(use_eng_prefix=True, accuracy=5)

    assert formatter4(12_345_678.90)   == "123.5M"
    assert formatter5(12_345_678.90)   == "123.46M"
    assert formatter4(0.0001234567890) == "123.5u"
    assert formatter5(0.01234567890)   == "12.346m"

test_eng_formatter()

Issue Description

The accuracy argument of the EngFormatter is generating a different number of digits.

It is expected to obtain 5 digits in total with accuracy=5, but the argument seems to affect only the digits behind the decimal point. This is wrong. It is not Engineering Notation !

Expected Behavior

Example:
with accuracy=4

• 12_345_678.90 returns 12.3457M , expected : 12.35M
• 123.4568u returns 123.4568u, expected 123.5u

with accuracy=5

• 12_345_678.90 returns 12.34568M, expected 12.345M
• 0.01234567890 returns 12.34568m, expected 12.346m

Installed Versions

INSTALLED VERSIONS ------------------ commit : 9c8bc3e python : 3.9.21 python-bits : 64 OS : Linux OS-release : 6.17.5-1.el9.elrepo.x86_64 Version : #1 SMP PREEMPT_DYNAMIC Thu Oct 23 13:22:49 EDT 2025 machine : x86_64 processor : x86_64 byteorder : little LC_ALL : None LANG : de_DE.UTF-8 LOCALE : de_DE.UTF-8

pandas : 2.3.3
numpy : 2.0.2
pytz : 2025.2
dateutil : 2.9.0.post0
pip : 21.3.1
Cython : None
sphinx : None
IPython : None
adbc-driver-postgresql: None
adbc-driver-sqlite : None
bs4 : None
blosc : None
bottleneck : None
dataframe-api-compat : None
fastparquet : None
fsspec : None
html5lib : None
hypothesis : None
gcsfs : None
jinja2 : None
lxml.etree : 4.6.5
matplotlib : None
numba : None
numexpr : None
odfpy : None
openpyxl : None
pandas_gbq : None
psycopg2 : None
pymysql : None
pyarrow : None
pyreadstat : None
pytest : None
python-calamine : None
pyxlsb : None
s3fs : None
scipy : None
sqlalchemy : None
tables : None
tabulate : None
xarray : None
xlrd : None
xlsxwriter : None
zstandard : None
tzdata : 2025.2
qtpy : None
pyqt5 : None

[cparg]

See also : https://en.wikipedia.org/wiki/Significant_figures

[cparg]

Updated Test

• The formatter adds a Space in front of the mantis
• There was a mistake in the values, should be 12.35M and 12.35M

import pandas as pd 

from pandas.io.formats.format import EngFormatter
# pd.show_versions()

def test_eng_formatter():
    formatter4 = EngFormatter(use_eng_prefix=True, accuracy=4)
    formatter5 = EngFormatter(use_eng_prefix=True, accuracy=5)

    print(formatter4(12_345_678.90))
    print(formatter4(0.0001234567890))

    print(formatter5(12_345_678.90))
    print(formatter5(0.01234567890))  

    

    assert formatter4(12_345_678.90)   == " 12.35M"
    assert formatter4(0.0001234567890) == " 123.5u"
    assert formatter5(12_345_678.90)   == " 12.346M"
    assert formatter5(0.01234567890)   == " 12.346m"

test_eng_formatter() 

This is the fix in

    def __call__(self, num: float) -> str:
        """
        Formats a number in engineering notation, appending a letter
        representing the power of 1000 of the original number. Some examples:
        >>> format_eng = EngFormatter(accuracy=0, use_eng_prefix=True)
        >>> format_eng(0)
        ' 0'
        >>> format_eng = EngFormatter(accuracy=1, use_eng_prefix=True)
        >>> format_eng(1_000_000)
        ' 1.0M'
        >>> format_eng = EngFormatter(accuracy=2, use_eng_prefix=False)
        >>> format_eng("-1e-6")
        '-1.00E-06'

        @param num: the value to represent
        @type num: either a numeric value or a string that can be converted to
                   a numeric value (as per decimal.Decimal constructor)

        @return: engineering formatted string
        """
        dnum = Decimal(str(num))

        if Decimal.is_nan(dnum):
            return "NaN"

        if Decimal.is_infinite(dnum):
            return "inf"

        sign = 1

        if dnum < 0:  # pragma: no cover
            sign = -1
            dnum = -dnum

        if dnum != 0:
            pow10 = Decimal(int(math.floor(dnum.log10() / 3) * 3))
        else:
            pow10 = Decimal(0)

        pow10 = pow10.min(max(self.ENG_PREFIXES.keys()))
        pow10 = pow10.max(min(self.ENG_PREFIXES.keys()))
        int_pow10 = int(pow10)

        if self.use_eng_prefix:
            prefix = self.ENG_PREFIXES[int_pow10]
        elif int_pow10 < 0:
            prefix = f"E-{-int_pow10:02d}"
        else:
            prefix = f"E+{int_pow10:02d}"

        mant = sign * dnum / (10**pow10)

        if self.accuracy is None:  # pragma: no cover
            format_str = "{mant: g}{prefix}"
        else:
            len_int=len(str(int(mant)))
            if len_int >= self.accuracy:
                # no decimal places
                format_str = f"{{mant: .0f}}{{prefix}}"
            else:
                # self.accuracy significant digits
                decimal_figuers = self.accuracy - len_int
                decimal_figuers = max(decimal_figuers, 0)
                
                format_str = f"{{mant: .{decimal_figuers:d}f}}{{prefix}}"

        formatted = format_str.format(mant=mant, prefix=prefix)

        return formatted

• doc test string is probably not correct anymore.
• This is the complete call() method of EngFormatter class in pandas/io/formats/format.py

[cparg]

Diff:

cparg@bart : .../io/formats$ diff -p format.py format.py.backup
*** format.py   2025-11-02 21:34:07.008622109 +0100
--- format.py.backup    2025-11-02 21:20:44.694018559 +0100
*************** class EngFormatter:
*** 1934,1950 ****
          if self.accuracy is None:  # pragma: no cover
              format_str = "{mant: g}{prefix}"
          else:
!             len_int=len(str(int(mant)))
!             if len_int >= self.accuracy:
!                 # no decimal places
!                 format_str = f"{{mant: .0f}}{{prefix}}"
!             else:
!                 # self.accuracy significant digits
!                 decimal_figuers = self.accuracy - len_int
!                 decimal_figuers = max(decimal_figuers, 0)
!                 # decimal_figuers = min(decimal_figuers, 3)   
!                 
!                 format_str = f"{{mant: .{decimal_figuers:d}f}}{{prefix}}"
  
          formatted = format_str.format(mant=mant, prefix=prefix)
  
--- 1934,1940 ----
          if self.accuracy is None:  # pragma: no cover
              format_str = "{mant: g}{prefix}"
          else:
!             format_str = f"{{mant: .{self.accuracy:d}f}}{{prefix}}"
  
          formatted = format_str.format(mant=mant, prefix=prefix)

[cparg]

• found a bug with previous patch with negative numbers.
• fixed by adding .lstrip('-') in len_int=len(str(int(mant)).lstrip("-"))
• added doc-string tests (not verified)

cparg@bart : .../io/formats$ diff -p format.py format.py.backup
*** format.py   2025-11-03 09:07:21.888156729 +0100
--- format.py.backup    2025-11-02 21:20:44.694018559 +0100
*************** class EngFormatter:
*** 1891,1910 ****
          ' 1.0M'
          >>> format_eng = EngFormatter(accuracy=2, use_eng_prefix=False)
          >>> format_eng("-1e-6")
!         '-1.0E-06'
!         >>> formatter4 = EngFormatter(use_eng_prefix=True, accuracy=4)
!         >>> formatter4(12_345_678.90)
!         ' 12.35M'
!         >>> formatter4 = EngFormatter(use_eng_prefix=True, accuracy=4) 
!         >>> formatter4(0.0001234567890)
!         ' 123.5u'
!         >>> formatter5 = EngFormatter(use_eng_prefix=True, accuracy=5)
!         >>> formatter5(12_345_678.90)
!         ' 12.346M'
!         >>> formatter5 = EngFormatter(use_eng_prefix=True, accuracy=5)
!         >>> formatter5(0.01234567890)
!         ' 12.346m'
!         
          @param num: the value to represent
          @type num: either a numeric value or a string that can be converted to
                     a numeric value (as per decimal.Decimal constructor)
--- 1891,1898 ----
          ' 1.0M'
          >>> format_eng = EngFormatter(accuracy=2, use_eng_prefix=False)
          >>> format_eng("-1e-6")
!         '-1.00E-06'
! 
          @param num: the value to represent
          @type num: either a numeric value or a string that can be converted to
                     a numeric value (as per decimal.Decimal constructor)
*************** class EngFormatter:
*** 1942,1966 ****
              prefix = f"E+{int_pow10:02d}"
  
          mant = sign * dnum / (10**pow10)
!         
!         # bug fix for 62963 https://github.com/pandas-dev/pandas/issues/62963
          if self.accuracy is None:  # pragma: no cover
              format_str = "{mant: g}{prefix}"
          else:
!             len_int=len(str(int(mant)).lstrip("-"))
!             if len_int >= self.accuracy:
!                 # no decimal places
!                 format_str = f"{{mant: .0f}}{{prefix}}"
!             else:
!                 # self.accuracy significant digits
!                 decimal_figuers = self.accuracy - len_int
!                 decimal_figuers = max(decimal_figuers, 0)
!                 # decimal_figuers = min(decimal_figuers, 3)   
!                 
!                 format_str = f"{{mant: .{decimal_figuers:d}f}}{{prefix}}"
  
          formatted = format_str.format(mant=mant, prefix=prefix)
-         # Bug-fix - End
  
          return formatted
  
--- 1930,1942 ----
              prefix = f"E+{int_pow10:02d}"
  
          mant = sign * dnum / (10**pow10)
! 
          if self.accuracy is None:  # pragma: no cover
              format_str = "{mant: g}{prefix}"
          else:
!             format_str = f"{{mant: .{self.accuracy:d}f}}{{prefix}}"
  
          formatted = format_str.format(mant=mant, prefix=prefix)
  
          return formatted

[Liam3851]

As the document says, EngFormatter is based on matplotlib.ticker.EngFormatter. The latter is specific that this is a number of digits after the decimal point, but also uses the kwarg places instead of accuracy.

matplotlib.ticker.EngFormatter(
    unit='',
    places=None,
    sep=' ',
    *,
    usetex=None,
    useMathText=None,
)


...

places : int, default: None
    Precision with which to display the number, specified in
    digits after the decimal point (there will be between one
    and three digits before the decimal point). If it is None,
    the formatting falls back to the floating point format '%g',
    which displays up to 6 *significant* digits, i.e. the equivalent
    value for *places* varies between 0 and 5 (inclusive).

Anyway I have no preference on the desirability/necessity here of matching matplotlib's API (if people will expect they match), or the use of accuracy in pandas rather than places in matplotlib (the latter of which is arguably clearer), but just noting this seems it would be an API change not a bugfix.

[rhshadrach]

Thanks for the report. This is used to format floats as strings within pandas, so strongly against a change in behavior here. Since this doesn't occur in our API documentation, it seems to me EngFormatter is internal (although admittedly, I do not expect this to be clear to users). The accuracy argument is clearly documented as

Number of decimal digits after the floating point.

Whether this is an objection to the name Eng or accuracy, I do not think this is worth renaming. Closing.