pydicom.valuerep.DSdecimal¶

Store value for an element with VR DS as decimal.Decimal.

Parameters:

val (str | int | float | Decimal) – Value to store as a DS.
auto_format (bool) – If True, automatically format the string representation of this number to ensure it satisfies the constraints in the DICOM standard. Note that this will lead to loss of precision for some numbers.

Notes

If constructed from an empty string, returns the empty string, not an instance of this class.

__init__(val: str | int | float | Decimal, auto_format: bool = False, validation_mode: int | None = None) → None[source]¶: Store the original string if one given, for exact write-out of same value later. E.g. if set '1.23e2', Decimal would write '123', but DS will use the original.

Methods

`__init__`(val[, auto_format, validation_mode])	Store the original string if one given, for exact write-out of same value later.
`adjusted`()	Return the adjusted exponent of the number.
`as_integer_ratio`()	Return a pair of integers, whose ratio is exactly equal to the original Decimal and with a positive denominator.
`as_tuple`()	Return a tuple representation of the number.
`canonical`()	Return the canonical encoding of the argument.
`compare`(other[, context])	Compare self to other.
`compare_signal`(other[, context])	Identical to compare, except that all NaNs signal.
`compare_total`(other[, context])	Compare two operands using their abstract representation rather than their numerical value.
`compare_total_mag`(other[, context])	Compare two operands using their abstract representation rather than their value as in compare_total(), but ignoring the sign of each operand.
`conjugate`()	Return self.
`copy_abs`()	Return the absolute value of the argument.
`copy_negate`()	Return the negation of the argument.
`copy_sign`(other[, context])	Return a copy of the first operand with the sign set to be the same as the sign of the second operand.
`exp`([context])	Return the value of the (natural) exponential function e**x at the given number.
`fma`(other, third[, context])	Fused multiply-add.
`from_float`()	Class method that converts a float to a decimal number, exactly.
`is_canonical`()	Return True if the argument is canonical and False otherwise.
`is_finite`()	Return True if the argument is a finite number, and False if the argument is infinite or a NaN.
`is_infinite`()	Return True if the argument is either positive or negative infinity and False otherwise.
`is_nan`()	Return True if the argument is a (quiet or signaling) NaN and False otherwise.
`is_normal`([context])	Return True if the argument is a normal finite non-zero number with an adjusted exponent greater than or equal to Emin.
`is_qnan`()	Return True if the argument is a quiet NaN, and False otherwise.
`is_signed`()	Return True if the argument has a negative sign and False otherwise.
`is_snan`()	Return True if the argument is a signaling NaN and False otherwise.
`is_subnormal`([context])	Return True if the argument is subnormal, and False otherwise.
`is_zero`()	Return True if the argument is a (positive or negative) zero and False otherwise.
`ln`([context])	Return the natural (base e) logarithm of the operand.
`log10`([context])	Return the base ten logarithm of the operand.
`logb`([context])	For a non-zero number, return the adjusted exponent of the operand as a Decimal instance.
`logical_and`(other[, context])	Return the digit-wise 'and' of the two (logical) operands.
`logical_invert`([context])	Return the digit-wise inversion of the (logical) operand.
`logical_or`(other[, context])	Return the digit-wise 'or' of the two (logical) operands.
`logical_xor`(other[, context])	Return the digit-wise 'exclusive or' of the two (logical) operands.
`max`(other[, context])	Maximum of self and other.
`max_mag`(other[, context])	Similar to the max() method, but the comparison is done using the absolute values of the operands.
`min`(other[, context])	Minimum of self and other.
`min_mag`(other[, context])	Similar to the min() method, but the comparison is done using the absolute values of the operands.
`next_minus`([context])	Return the largest number representable in the given context (or in the current default context if no context is given) that is smaller than the given operand.
`next_plus`([context])	Return the smallest number representable in the given context (or in the current default context if no context is given) that is larger than the given operand.
`next_toward`(other[, context])	If the two operands are unequal, return the number closest to the first operand in the direction of the second operand.
`normalize`([context])	Normalize the number by stripping the rightmost trailing zeros and converting any result equal to Decimal('0') to Decimal('0e0').
`number_class`([context])	Return a string describing the class of the operand.
`quantize`(exp[, rounding, context])	Return a value equal to the first operand after rounding and having the exponent of the second operand.
`radix`()	Return Decimal(10), the radix (base) in which the Decimal class does all its arithmetic.
`remainder_near`(other[, context])	Return the remainder from dividing self by other.
`rotate`(other[, context])	Return the result of rotating the digits of the first operand by an amount specified by the second operand.
`same_quantum`(other[, context])	Test whether self and other have the same exponent or whether both are NaN.
`scaleb`(other[, context])	Return the first operand with the exponent adjusted the second.
`shift`(other[, context])	Return the result of shifting the digits of the first operand by an amount specified by the second operand.
`sqrt`([context])	Return the square root of the argument to full precision.
`to_eng_string`([context])	Convert to an engineering-type string.
`to_integral`([rounding, context])	Identical to the to_integral_value() method.
`to_integral_exact`([rounding, context])	Round to the nearest integer, signaling Inexact or Rounded as appropriate if rounding occurs.
`to_integral_value`([rounding, context])	Round to the nearest integer without signaling Inexact or Rounded.

Attributes

`imag`
`real`
`auto_format`

adjusted()¶: Return the adjusted exponent of the number. Defined as exp + digits - 1.

as_integer_ratio()¶: Return a pair of integers, whose ratio is exactly equal to the original Decimal and with a positive denominator. The ratio is in lowest terms. Raise OverflowError on infinities and a ValueError on NaNs.

as_tuple()¶: Return a tuple representation of the number.

canonical()¶: Return the canonical encoding of the argument. Currently, the encoding of a Decimal instance is always canonical, so this operation returns its argument unchanged.

compare(other, context=None)¶

Compare self to other. Return a decimal value:

a or b is a NaN ==> Decimal(‘NaN’) a < b ==> Decimal(‘-1’) a == b ==> Decimal(‘0’) a > b ==> Decimal(‘1’)

compare_signal(other, context=None)¶: Identical to compare, except that all NaNs signal.

compare_total(other, context=None)¶

Compare two operands using their abstract representation rather than their numerical value. Similar to the compare() method, but the result gives a total ordering on Decimal instances. Two Decimal instances with the same numeric value but different representations compare unequal in this ordering:

>>> Decimal('12.0').compare_total(Decimal('12'))
Decimal('-1')

Quiet and signaling NaNs are also included in the total ordering. The result of this function is Decimal(‘0’) if both operands have the same representation, Decimal(‘-1’) if the first operand is lower in the total order than the second, and Decimal(‘1’) if the first operand is higher in the total order than the second operand. See the specification for details of the total order.

This operation is unaffected by context and is quiet: no flags are changed and no rounding is performed. As an exception, the C version may raise InvalidOperation if the second operand cannot be converted exactly.

compare_total_mag(other, context=None)¶

Compare two operands using their abstract representation rather than their value as in compare_total(), but ignoring the sign of each operand.

x.compare_total_mag(y) is equivalent to x.copy_abs().compare_total(y.copy_abs()).

This operation is unaffected by context and is quiet: no flags are changed and no rounding is performed. As an exception, the C version may raise InvalidOperation if the second operand cannot be converted exactly.

conjugate()¶: Return self.

copy_abs()¶: Return the absolute value of the argument. This operation is unaffected by context and is quiet: no flags are changed and no rounding is performed.

copy_negate()¶: Return the negation of the argument. This operation is unaffected by context and is quiet: no flags are changed and no rounding is performed.

copy_sign(other, context=None)¶

Return a copy of the first operand with the sign set to be the same as the sign of the second operand. For example:

>>> Decimal('2.3').copy_sign(Decimal('-1.5'))
Decimal('-2.3')

This operation is unaffected by context and is quiet: no flags are changed and no rounding is performed. As an exception, the C version may raise InvalidOperation if the second operand cannot be converted exactly.

exp(context=None)¶: Return the value of the (natural) exponential function e**x at the given number. The function always uses the ROUND_HALF_EVEN mode and the result is correctly rounded.

fma(other, third, context=None)¶

Fused multiply-add. Return self*other+third with no rounding of the intermediate product self*other.

>>> Decimal(2).fma(3, 5)
Decimal('11')

from_float()¶

Class method that converts a float to a decimal number, exactly. Since 0.1 is not exactly representable in binary floating point, Decimal.from_float(0.1) is not the same as Decimal(‘0.1’).

>>> Decimal.from_float(0.1)
Decimal('0.1000000000000000055511151231257827021181583404541015625')
>>> Decimal.from_float(float('nan'))
Decimal('NaN')
>>> Decimal.from_float(float('inf'))
Decimal('Infinity')
>>> Decimal.from_float(float('-inf'))
Decimal('-Infinity')

is_canonical()¶: Return True if the argument is canonical and False otherwise. Currently, a Decimal instance is always canonical, so this operation always returns True.

is_finite()¶: Return True if the argument is a finite number, and False if the argument is infinite or a NaN.

is_infinite()¶: Return True if the argument is either positive or negative infinity and False otherwise.

is_nan()¶: Return True if the argument is a (quiet or signaling) NaN and False otherwise.

is_normal(context=None)¶: Return True if the argument is a normal finite non-zero number with an adjusted exponent greater than or equal to Emin. Return False if the argument is zero, subnormal, infinite or a NaN.

is_qnan()¶: Return True if the argument is a quiet NaN, and False otherwise.

is_signed()¶: Return True if the argument has a negative sign and False otherwise. Note that both zeros and NaNs can carry signs.

is_snan()¶: Return True if the argument is a signaling NaN and False otherwise.

is_subnormal(context=None)¶: Return True if the argument is subnormal, and False otherwise. A number is subnormal if it is non-zero, finite, and has an adjusted exponent less than Emin.

is_zero()¶: Return True if the argument is a (positive or negative) zero and False otherwise.

ln(context=None)¶: Return the natural (base e) logarithm of the operand. The function always uses the ROUND_HALF_EVEN mode and the result is correctly rounded.

log10(context=None)¶: Return the base ten logarithm of the operand. The function always uses the ROUND_HALF_EVEN mode and the result is correctly rounded.

logb(context=None)¶: For a non-zero number, return the adjusted exponent of the operand as a Decimal instance. If the operand is a zero, then Decimal(‘-Infinity’) is returned and the DivisionByZero condition is raised. If the operand is an infinity then Decimal(‘Infinity’) is returned.

logical_and(other, context=None)¶: Return the digit-wise ‘and’ of the two (logical) operands.

logical_invert(context=None)¶: Return the digit-wise inversion of the (logical) operand.

logical_or(other, context=None)¶: Return the digit-wise ‘or’ of the two (logical) operands.

logical_xor(other, context=None)¶: Return the digit-wise ‘exclusive or’ of the two (logical) operands.

max(other, context=None)¶: Maximum of self and other. If one operand is a quiet NaN and the other is numeric, the numeric operand is returned.

max_mag(other, context=None)¶: Similar to the max() method, but the comparison is done using the absolute values of the operands.

min(other, context=None)¶: Minimum of self and other. If one operand is a quiet NaN and the other is numeric, the numeric operand is returned.

min_mag(other, context=None)¶: Similar to the min() method, but the comparison is done using the absolute values of the operands.

next_minus(context=None)¶: Return the largest number representable in the given context (or in the current default context if no context is given) that is smaller than the given operand.

next_plus(context=None)¶: Return the smallest number representable in the given context (or in the current default context if no context is given) that is larger than the given operand.

next_toward(other, context=None)¶: If the two operands are unequal, return the number closest to the first operand in the direction of the second operand. If both operands are numerically equal, return a copy of the first operand with the sign set to be the same as the sign of the second operand.

normalize(context=None)¶: Normalize the number by stripping the rightmost trailing zeros and converting any result equal to Decimal(‘0’) to Decimal(‘0e0’). Used for producing canonical values for members of an equivalence class. For example, Decimal(‘32.100’) and Decimal(‘0.321000e+2’) both normalize to the equivalent value Decimal(‘32.1’).

number_class(context=None)¶

Return a string describing the class of the operand. The returned value is one of the following ten strings:

‘-Infinity’, indicating that the operand is negative infinity.

‘-Normal’, indicating that the operand is a negative normal number.

‘-Subnormal’, indicating that the operand is negative and subnormal.

‘-Zero’, indicating that the operand is a negative zero.

‘+Zero’, indicating that the operand is a positive zero.

‘+Subnormal’, indicating that the operand is positive and subnormal.

‘+Normal’, indicating that the operand is a positive normal number.

‘+Infinity’, indicating that the operand is positive infinity.

‘NaN’, indicating that the operand is a quiet NaN (Not a Number).

‘sNaN’, indicating that the operand is a signaling NaN.

quantize(exp, rounding=None, context=None)¶

Return a value equal to the first operand after rounding and having the exponent of the second operand.

>>> Decimal('1.41421356').quantize(Decimal('1.000'))
Decimal('1.414')

Unlike other operations, if the length of the coefficient after the quantize operation would be greater than precision, then an InvalidOperation is signaled. This guarantees that, unless there is an error condition, the quantized exponent is always equal to that of the right-hand operand.

Also unlike other operations, quantize never signals Underflow, even if the result is subnormal and inexact.

If the exponent of the second operand is larger than that of the first, then rounding may be necessary. In this case, the rounding mode is determined by the rounding argument if given, else by the given context argument; if neither argument is given, the rounding mode of the current thread’s context is used.

radix()¶: Return Decimal(10), the radix (base) in which the Decimal class does all its arithmetic. Included for compatibility with the specification.

remainder_near(other, context=None)¶

Return the remainder from dividing self by other. This differs from self % other in that the sign of the remainder is chosen so as to minimize its absolute value. More precisely, the return value is self - n * other where n is the integer nearest to the exact value of self / other, and if two integers are equally near then the even one is chosen.

If the result is zero then its sign will be the sign of self.

rotate(other, context=None)¶: Return the result of rotating the digits of the first operand by an amount specified by the second operand. The second operand must be an integer in the range -precision through precision. The absolute value of the second operand gives the number of places to rotate. If the second operand is positive then rotation is to the left; otherwise rotation is to the right. The coefficient of the first operand is padded on the left with zeros to length precision if necessary. The sign and exponent of the first operand are unchanged.

same_quantum(other, context=None)¶

Test whether self and other have the same exponent or whether both are NaN.

This operation is unaffected by context and is quiet: no flags are changed and no rounding is performed. As an exception, the C version may raise InvalidOperation if the second operand cannot be converted exactly.

scaleb(other, context=None)¶: Return the first operand with the exponent adjusted the second. Equivalently, return the first operand multiplied by 10**other. The second operand must be an integer.

shift(other, context=None)¶: Return the result of shifting the digits of the first operand by an amount specified by the second operand. The second operand must be an integer in the range -precision through precision. The absolute value of the second operand gives the number of places to shift. If the second operand is positive, then the shift is to the left; otherwise the shift is to the right. Digits shifted into the coefficient are zeros. The sign and exponent of the first operand are unchanged.

sqrt(context=None)¶: Return the square root of the argument to full precision. The result is correctly rounded using the ROUND_HALF_EVEN rounding mode.

to_eng_string(context=None)¶

Convert to an engineering-type string. Engineering notation has an exponent which is a multiple of 3, so there are up to 3 digits left of the decimal place. For example, Decimal(‘123E+1’) is converted to Decimal(‘1.23E+3’).

The value of context.capitals determines whether the exponent sign is lower or upper case. Otherwise, the context does not affect the operation.

to_integral(rounding=None, context=None)¶: Identical to the to_integral_value() method. The to_integral() name has been kept for compatibility with older versions.

to_integral_exact(rounding=None, context=None)¶: Round to the nearest integer, signaling Inexact or Rounded as appropriate if rounding occurs. The rounding mode is determined by the rounding parameter if given, else by the given context. If neither parameter is given, then the rounding mode of the current default context is used.

to_integral_value(rounding=None, context=None)¶: Round to the nearest integer without signaling Inexact or Rounded. The rounding mode is determined by the rounding parameter if given, else by the given context. If neither parameter is given, then the rounding mode of the current default context is used.