numpy.core.arrayprint

Parameters

a : ndarray

Input array.

max_line_width : int, optional

Inserts newlines if text is longer than max_line_width. Defaults to numpy.get_printoptions()['linewidth'].

precision : int or None, optional

Floating point precision. Defaults to numpy.get_printoptions()['precision'].

suppress_small : bool, optional

Represent numbers "very close" to zero as zero; default is False. Very close is defined by precision: if the precision is 8, e.g., numbers smaller (in absolute value) than 5e-9 are represented as zero. Defaults to numpy.get_printoptions()['suppress'].

separator : str, optional

Inserted between elements.

prefix : str, optional suffix : str, optional

The length of the prefix and suffix strings are used to respectively align and wrap the output. An array is typically printed as:

prefix + array2string(a) + suffix

The output is left-padded by the length of the prefix string, and wrapping is forced at the column max_line_width - len(suffix). It should be noted that the content of prefix and suffix strings are not included in the output.

style : _NoValue, optional

Has no effect, do not use.

Deprecated since version 1.14.0.

formatter : dict of callables, optional

If not None, the keys should indicate the type(s) that the respective formatting function applies to. Callables should return a string. Types that are not specified (by their corresponding keys) are handled by the default formatters. Individual types for which a formatter can be set are:

• 'bool'
• 'int'
• 'timedelta' : a numpy.timedelta64
• 'datetime' : a numpy.datetime64
• 'float'
• 'longfloat' : 128-bit floats
• 'complexfloat'
• 'longcomplexfloat' : composed of two 128-bit floats
• 'void' : type numpy.void
• 'numpystr' : types numpy.string_ and numpy.unicode_

Other keys that can be used to set a group of types at once are:

• 'all' : sets all types
• 'int_kind' : sets 'int'
• 'float_kind' : sets 'float' and 'longfloat'
• 'complex_kind' : sets 'complexfloat' and 'longcomplexfloat'
• 'str_kind' : sets 'numpystr'

threshold : int, optional

Total number of array elements which trigger summarization rather than full repr. Defaults to numpy.get_printoptions()['threshold'].

edgeitems : int, optional

Number of array items in summary at beginning and end of each dimension. Defaults to numpy.get_printoptions()['edgeitems'].

sign : string, either '-', '+', or ' ', optional

Controls printing of the sign of floating-point types. If '+', always print the sign of positive values. If ' ', always prints a space (whitespace character) in the sign position of positive values. If '-', omit the sign character of positive values. Defaults to numpy.get_printoptions()['sign'].

floatmode : str, optional

Controls the interpretation of the precision option for floating-point types. Defaults to numpy.get_printoptions()['floatmode']. Can take the following values:

• 'fixed': Always print exactly precision fractional digits, even if this would print more or fewer digits than necessary to specify the value uniquely.
• 'unique': Print the minimum number of fractional digits necessary to represent each value uniquely. Different elements may have a different number of digits. The value of the precision option is ignored.
• 'maxprec': Print at most precision fractional digits, but if an element can be uniquely represented with fewer digits only print it with that many.
• 'maxprec_equal': Print at most precision fractional digits, but if every element in the array can be uniquely represented with an equal number of fewer digits, use that many digits for all elements.

legacy : string or False, optional

If set to the string '1.13' enables 1.13 legacy printing mode. This approximates numpy 1.13 print output by including a space in the sign position of floats and different behavior for 0d arrays. If set to False, disables legacy mode. Unrecognized strings will be ignored with a warning for forward compatibility.

New in version 1.14.0.

Returns

array_str : str

String representation of the array.

Raises

TypeError

if a callable in formatter does not return a string.

See Also

array_str, array_repr, set_printoptions, get_printoptions

Notes

If a formatter is specified for a certain type, the precision keyword is ignored for that type.

This is a very flexible function; array_repr and array_str are using array2string internally so keywords with the same name should work identically in all three functions.

Examples

>>> x = np.array([1e-16,1,2,3])
>>> np.array2string(x, precision=2, separator=',',
...                       suppress_small=True)
'[0.,1.,2.,3.]'

>>> x  = np.arange(3.)
>>> np.array2string(x, formatter={'float_kind':lambda x: "%.2f" % x})
'[0.00 1.00 2.00]'

>>> x  = np.arange(3)
>>> np.array2string(x, formatter={'int':lambda x: hex(x)})
'[0x0 0x1 0x2]'

Parameters

arr : ndarray

Input array.

max_line_width : int, optional

Inserts newlines if text is longer than max_line_width. Defaults to numpy.get_printoptions()['linewidth'].

precision : int, optional

Floating point precision. Defaults to numpy.get_printoptions()['precision'].

suppress_small : bool, optional

Represent numbers "very close" to zero as zero; default is False. Very close is defined by precision: if the precision is 8, e.g., numbers smaller (in absolute value) than 5e-9 are represented as zero. Defaults to numpy.get_printoptions()['suppress'].

Returns

string : str

The string representation of an array.

See Also

array_str, array2string, set_printoptions

Examples

>>> np.array_repr(np.array([1,2]))
'array([1, 2])'
>>> np.array_repr(np.ma.array([0.]))
'MaskedArray([0.])'
>>> np.array_repr(np.array([], np.int32))
'array([], dtype=int32)'

>>> x = np.array([1e-6, 4e-7, 2, 3])
>>> np.array_repr(x, precision=6, suppress_small=True)
'array([0.000001,  0.      ,  2.      ,  3.      ])'

Parameters

a : ndarray

Input array.

max_line_width : int, optional

Inserts newlines if text is longer than max_line_width. Defaults to numpy.get_printoptions()['linewidth'].

precision : int, optional

Floating point precision. Defaults to numpy.get_printoptions()['precision'].

suppress_small : bool, optional

Represent numbers "very close" to zero as zero; default is False. Very close is defined by precision: if the precision is 8, e.g., numbers smaller (in absolute value) than 5e-9 are represented as zero. Defaults to numpy.get_printoptions()['suppress'].

See Also

array2string, array_repr, set_printoptions

Examples

>>> np.array_str(np.arange(3))
'[0 1 2]'

Parameters

dtype : dtype

Data type

Returns

implied : bool

True if the dtype is implied by the representation of its values.

Examples

>>> np.core.arrayprint.dtype_is_implied(int)
True
>>> np.array([1, 2, 3], int)
array([1, 2, 3])
>>> np.core.arrayprint.dtype_is_implied(np.int8)
False
>>> np.array([1, 2, 3], np.int8)
array([1, 2, 3], dtype=int8)

Parameters

x : python float or numpy floating scalar

Value to format.

precision : non-negative integer or None, optional

Maximum number of digits to print. May be None if unique is True, but must be an integer if unique is False.

unique : boolean, optional

If True, use a digit-generation strategy which gives the shortest representation which uniquely identifies the floating-point number from other values of the same type, by judicious rounding. If precision is given fewer digits than necessary can be printed, or if min_digits is given more can be printed, in which cases the last digit is rounded with unbiased rounding. If False, digits are generated as if printing an infinite-precision value and stopping after precision digits, rounding the remaining value with unbiased rounding

fractional : boolean, optional

If True, the cutoffs of precision and min_digits refer to the total number of digits after the decimal point, including leading zeros. If False, precision and min_digits refer to the total number of significant digits, before or after the decimal point, ignoring leading zeros.

trim : one of 'k', '.', '0', '-', optional

Controls post-processing trimming of trailing digits, as follows:

• 'k' : keep trailing zeros, keep decimal point (no trimming)
• '.' : trim all trailing zeros, leave decimal point
• '0' : trim all but the zero before the decimal point. Insert the zero if it is missing.
• '-' : trim trailing zeros and any trailing decimal point

sign : boolean, optional

Whether to show the sign for positive values.

pad_left : non-negative integer, optional

Pad the left side of the string with whitespace until at least that many characters are to the left of the decimal point.

pad_right : non-negative integer, optional

Pad the right side of the string with whitespace until at least that many characters are to the right of the decimal point.

min_digits : non-negative integer or None, optional

Minimum number of digits to print. Only has an effect if unique=True in which case additional digits past those necessary to uniquely identify the value may be printed, rounding the last additional digit.

-- versionadded:: 1.21.0

Returns

rep : string

The string representation of the floating point value

See Also

format_float_scientific

Examples

>>> np.format_float_positional(np.float32(np.pi))
'3.1415927'
>>> np.format_float_positional(np.float16(np.pi))
'3.14'
>>> np.format_float_positional(np.float16(0.3))
'0.3'
>>> np.format_float_positional(np.float16(0.3), unique=False, precision=10)
'0.3000488281'

Parameters

x : python float or numpy floating scalar

Value to format.

precision : non-negative integer or None, optional

Maximum number of digits to print. May be None if unique is True, but must be an integer if unique is False.

unique : boolean, optional

If True, use a digit-generation strategy which gives the shortest representation which uniquely identifies the floating-point number from other values of the same type, by judicious rounding. If precision is given fewer digits than necessary can be printed. If min_digits is given more can be printed, in which cases the last digit is rounded with unbiased rounding. If False, digits are generated as if printing an infinite-precision value and stopping after precision digits, rounding the remaining value with unbiased rounding

trim : one of 'k', '.', '0', '-', optional

Controls post-processing trimming of trailing digits, as follows:

• 'k' : keep trailing zeros, keep decimal point (no trimming)
• '.' : trim all trailing zeros, leave decimal point
• '0' : trim all but the zero before the decimal point. Insert the zero if it is missing.
• '-' : trim trailing zeros and any trailing decimal point

sign : boolean, optional

Whether to show the sign for positive values.

pad_left : non-negative integer, optional

Pad the left side of the string with whitespace until at least that many characters are to the left of the decimal point.

exp_digits : non-negative integer, optional

Pad the exponent with zeros until it contains at least this many digits. If omitted, the exponent will be at least 2 digits.

min_digits : non-negative integer or None, optional

Minimum number of digits to print. This only has an effect for unique=True. In that case more digits than necessary to uniquely identify the value may be printed and rounded unbiased.

-- versionadded:: 1.21.0

Returns

rep : string

The string representation of the floating point value

See Also

format_float_positional

Examples

>>> np.format_float_scientific(np.float32(np.pi))
'3.1415927e+00'
>>> s = np.float32(1.23e24)
>>> np.format_float_scientific(s, unique=False, precision=15)
'1.230000071797338e+24'
>>> np.format_float_scientific(s, exp_digits=4)
'1.23e+0024'

Returns

print_opts : dict

Dictionary of current print options with keys

• precision : int
• threshold : int
• edgeitems : int
• linewidth : int
• suppress : bool
• nanstr : str
• infstr : str
• formatter : dict of callables
• sign : str

For a full description of these options, see set_printoptions.

See Also

set_printoptions, printoptions, set_string_function

Examples

>>> from numpy.testing import assert_equal
>>> with np.printoptions(precision=2):
...     np.array([2.0]) / 3
array([0.67])

The as-clause of the with-statement gives the current print options:

>>> with np.printoptions(precision=2) as opts:
...      assert_equal(opts, np.get_printoptions())

See Also

set_printoptions, get_printoptions

Parameters

precision : int or None, optional

Number of digits of precision for floating point output (default 8). May be None if floatmode is not fixed, to print as many digits as necessary to uniquely specify the value.

threshold : int, optional

Total number of array elements which trigger summarization rather than full repr (default 1000). To always use the full repr without summarization, pass sys.maxsize.

edgeitems : int, optional

Number of array items in summary at beginning and end of each dimension (default 3).

linewidth : int, optional

The number of characters per line for the purpose of inserting line breaks (default 75).

suppress : bool, optional

If True, always print floating point numbers using fixed point notation, in which case numbers equal to zero in the current precision will print as zero. If False, then scientific notation is used when absolute value of the smallest number is < 1e-4 or the ratio of the maximum absolute value to the minimum is > 1e3. The default is False.

nanstr : str, optional

String representation of floating point not-a-number (default nan).

infstr : str, optional

String representation of floating point infinity (default inf).

sign : string, either '-', '+', or ' ', optional

Controls printing of the sign of floating-point types. If '+', always print the sign of positive values. If ' ', always prints a space (whitespace character) in the sign position of positive values. If '-', omit the sign character of positive values. (default '-')

formatter : dict of callables, optional

If not None, the keys should indicate the type(s) that the respective formatting function applies to. Callables should return a string. Types that are not specified (by their corresponding keys) are handled by the default formatters. Individual types for which a formatter can be set are:

• 'bool'
• 'int'
• 'timedelta' : a numpy.timedelta64
• 'datetime' : a numpy.datetime64
• 'float'
• 'longfloat' : 128-bit floats
• 'complexfloat'
• 'longcomplexfloat' : composed of two 128-bit floats
• 'numpystr' : types numpy.string_ and numpy.unicode_
• 'object' : np.object_ arrays

Other keys that can be used to set a group of types at once are:

• 'all' : sets all types
• 'int_kind' : sets 'int'
• 'float_kind' : sets 'float' and 'longfloat'
• 'complex_kind' : sets 'complexfloat' and 'longcomplexfloat'
• 'str_kind' : sets 'numpystr'

floatmode : str, optional

Controls the interpretation of the precision option for floating-point types. Can take the following values (default maxprec_equal):

• 'fixed': Always print exactly precision fractional digits,

  even if this would print more or fewer digits than necessary to specify the value uniquely.

• 'unique': Print the minimum number of fractional digits necessary

  to represent each value uniquely. Different elements may have a different number of digits. The value of the precision option is ignored.

• 'maxprec': Print at most precision fractional digits, but if

  an element can be uniquely represented with fewer digits only print it with that many.

• 'maxprec_equal': Print at most precision fractional digits,

  but if every element in the array can be uniquely represented with an equal number of fewer digits, use that many digits for all elements.

legacy : string or False, optional

If set to the string '1.13' enables 1.13 legacy printing mode. This approximates numpy 1.13 print output by including a space in the sign position of floats and different behavior for 0d arrays. This also enables 1.21 legacy printing mode (described below).

If set to the string '1.21' enables 1.21 legacy printing mode. This approximates numpy 1.21 print output of complex structured dtypes by not inserting spaces after commas that separate fields and after colons.

If set to False, disables legacy mode.

Unrecognized strings will be ignored with a warning for forward compatibility.

New in version 1.14.0.

Changed in version 1.22.0.

See Also

get_printoptions, printoptions, set_string_function, array2string

Notes

formatter is always reset with a call to set_printoptions.

Use printoptions as a context manager to set the values temporarily.

Examples

Floating point precision can be set:

>>> np.set_printoptions(precision=4)
>>> np.array([1.123456789])
[1.1235]

Long arrays can be summarised:

>>> np.set_printoptions(threshold=5)
>>> np.arange(10)
array([0, 1, 2, ..., 7, 8, 9])

Small results can be suppressed:

>>> eps = np.finfo(float).eps
>>> x = np.arange(4.)
>>> x**2 - (x + eps)**2
array([-4.9304e-32, -4.4409e-16,  0.0000e+00,  0.0000e+00])
>>> np.set_printoptions(suppress=True)
>>> x**2 - (x + eps)**2
array([-0., -0.,  0.,  0.])

A custom formatter can be used to display array elements as desired:

>>> np.set_printoptions(formatter={'all':lambda x: 'int: '+str(-x)})
>>> x = np.arange(3)
>>> x
array([int: 0, int: -1, int: -2])
>>> np.set_printoptions()  # formatter gets reset
>>> x
array([0, 1, 2])

To put back the default options, you can use:

>>> np.set_printoptions(edgeitems=3, infstr='inf',
... linewidth=75, nanstr='nan', precision=8,
... suppress=False, threshold=1000, formatter=None)

Also to temporarily override options, use printoptions as a context manager:

>>> with np.printoptions(precision=2, suppress=True, threshold=5):
...     np.linspace(0, 10, 10)
array([ 0.  ,  1.11,  2.22, ...,  7.78,  8.89, 10.  ])

Parameters

f : function or None

Function to be used to pretty print arrays. The function should expect a single array argument and return a string of the representation of the array. If None, the function is reset to the default NumPy function to print arrays.

repr : bool, optional

If True (default), the function for pretty printing (__repr__) is set, if False the function that returns the default string representation (__str__) is set.

See Also

set_printoptions, get_printoptions

Examples

>>> def pprint(arr):
...     return 'HA! - What are you going to do now?'
...
>>> np.set_string_function(pprint)
>>> a = np.arange(10)
>>> a
HA! - What are you going to do now?
>>> _ = a
>>> # [0 1 2 3 4 5 6 7 8 9]

We can reset the function to the default:

>>> np.set_string_function(None)
>>> a
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

repr affects either pretty printing or normal string representation. Note that __repr__ is still affected by setting __str__ because the width of each array element in the returned string becomes equal to the length of the result of __str__().

>>> x = np.arange(4)
>>> np.set_string_function(lambda x:'random', repr=False)
>>> x.__str__()
'random'
>>> x.__repr__()
'array([0, 1, 2, 3])'