Quantity

class astropy.units.Quantity(value, unit=None, dtype=None, copy=True, order=None, subok=False, ndmin=0)

Bases: numpy.ndarray

A Quantity represents a number with some associated unit.

See also: https://docs.astropy.org/en/stable/units/quantity.html

Parameters

valuenumber, ndarray, Quantity object (sequence), str

The numerical value of this quantity in the units given by unit. If a Quantity or sequence of them (or any other valid object with a unit attribute), creates a new Quantity object, converting to unit units as needed. If a string, it is converted to a number or Quantity, depending on whether a unit is present.

unitUnitBase instance, str

An object that represents the unit associated with the input value. Must be an UnitBase object or a string parseable by the units package.

dtype~numpy.dtype, optional

The dtype of the resulting Numpy array or scalar that will hold the value. If not provided, it is determined from the input, except that any integer and (non-Quantity) object inputs are converted to float by default.

copybool, optional

If True (default), then the value is copied. Otherwise, a copy will only be made if __array__ returns a copy, if value is a nested sequence, or if a copy is needed to satisfy an explicitly given dtype. (The False option is intended mostly for internal use, to speed up initialization where a copy is known to have been made. Use with care.)

order{‘C’, ‘F’, ‘A’}, optional

Specify the order of the array. As in array. This parameter is ignored if the input is a Quantity and copy=False.

subokbool, optional

If False (default), the returned array will be forced to be a Quantity. Otherwise, Quantity subclasses will be passed through, or a subclass appropriate for the unit will be used (such as Dex for u.dex(u.AA)).

ndminint, optional

Specifies the minimum number of dimensions that the resulting array should have. Ones will be pre-pended to the shape as needed to meet this requirement. This parameter is ignored if the input is a Quantity and copy=False.

Raises

TypeError

If the value provided is not a Python numeric type.

TypeError

If the unit provided is not either a Unit object or a parseable string unit.

Notes

Quantities can also be created by multiplying a number or array with a Unit. See https://docs.astropy.org/en/latest/units/

Attributes Summary

cgs	Returns a copy of the current Quantity instance with CGS units.
equivalencies	A list of equivalencies that will be applied by default during unit conversions.
flat	A 1-D iterator over the Quantity array.
info	Container for meta information like name, description, format.
isscalar	True if the value of this quantity is a scalar, or False if it is an array-like object.
si	Returns a copy of the current Quantity instance with SI units.
unit	A UnitBase object representing the unit of this quantity.
value	The numerical value of this instance.

Methods Summary

all([axis, out, keepdims])	Returns True if all elements evaluate to True.
any([axis, out, keepdims])	Returns True if any of the elements of a evaluate to True.
argmax([axis, out])	Return indices of the maximum values along the given axis.
argmin([axis, out])	Return indices of the minimum values along the given axis of a.
argsort([axis, kind, order])	Returns the indices that would sort this array.
choose(choices[, out, mode])	Use an index array to construct a new array from a set of choices.
decompose([bases])	Generates a new Quantity with the units decomposed.
diff([n, axis])
dot(b[, out])	Dot product of two arrays.
dump(file)	Dump a pickle of the array to the specified file.
dumps()	Returns the pickle of the array as a string.
ediff1d([to_end, to_begin])
fill(value)	Fill the array with a scalar value.
insert(obj, values[, axis])	Insert values along the given axis before the given indices and return a new Quantity object.
item(*args)	Copy an element of an array to a standard Python scalar and return it.
itemset(*args)	Insert scalar into an array (scalar is cast to array’s dtype, if possible)
mean([axis, dtype, out, keepdims])	Returns the average of the array elements along given axis.
nansum([axis, out, keepdims])
put(indices, values[, mode])	Set a.flat[n] = values[n] for all n in indices.
round([decimals, out])	Return a with each element rounded to the given number of decimals.
searchsorted(v[, side, sorter])	Find indices where elements of v should be inserted in a to maintain order.
std([axis, dtype, out, ddof, keepdims])	Returns the standard deviation of the array elements along given axis.
take(indices[, axis, out, mode])	Return an array formed from the elements of a at the given indices.
to(unit[, equivalencies, copy])	Return a new Quantity object with the specified unit.
to_string([unit, precision, format, subfmt])	Generate a string representation of the quantity and its unit.
to_value([unit, equivalencies])	The numerical value, possibly in a different unit.
tobytes([order])	Construct Python bytes containing the raw data bytes in the array.
tofile(fid[, sep, format])	Write array to a file as text or binary (default).
tolist()	Return the array as an a.ndim-levels deep nested list of Python scalars.
tostring([order])	A compatibility alias for tobytes, with exactly the same behavior.
trace([offset, axis1, axis2, dtype, out])	Return the sum along diagonals of the array.
var([axis, dtype, out, ddof, keepdims])	Returns the variance of the array elements, along given axis.

Attributes Documentation

cgs

Returns a copy of the current Quantity instance with CGS units. The value of the resulting object will be scaled.

equivalencies

A list of equivalencies that will be applied by default during unit conversions.

flat

A 1-D iterator over the Quantity array.

This returns a QuantityIterator instance, which behaves the same as the flatiter instance returned by flat, and is similar to, but not a subclass of, Python’s built-in iterator object.

info

Container for meta information like name, description, format. This is required when the object is used as a mixin column within a table, but can be used as a general way to store meta information.

isscalar

True if the value of this quantity is a scalar, or False if it is an array-like object.

Note

This is subtly different from numpy.isscalar in that numpy.isscalar returns False for a zero-dimensional array (e.g. np.array(1)), while this is True for quantities, since quantities cannot represent true numpy scalars.

si

Returns a copy of the current Quantity instance with SI units. The value of the resulting object will be scaled.

unit

A UnitBase object representing the unit of this quantity.

value

The numerical value of this instance.

See also

to_value

Get the numerical value in a given unit.

Methods Documentation

all(axis=None, out=None, keepdims=False)

Returns True if all elements evaluate to True.

Refer to numpy.all for full documentation.

See also

numpy.all

equivalent function

any(axis=None, out=None, keepdims=False)

Returns True if any of the elements of a evaluate to True.

Refer to numpy.any for full documentation.

See also

numpy.any

equivalent function

argmax(axis=None, out=None)

Return indices of the maximum values along the given axis.

Refer to numpy.argmax for full documentation.

See also

numpy.argmax

equivalent function

argmin(axis=None, out=None)

Return indices of the minimum values along the given axis of a.

Refer to numpy.argmin for detailed documentation.

See also

numpy.argmin

equivalent function

argsort(axis=- 1, kind=None, order=None)

Returns the indices that would sort this array.

Refer to numpy.argsort for full documentation.

See also

numpy.argsort

equivalent function

choose(choices, out=None, mode='raise')

Use an index array to construct a new array from a set of choices.

Refer to numpy.choose for full documentation.

See also

numpy.choose

equivalent function

decompose(bases=[])

Generates a new Quantity with the units decomposed. Decomposed units have only irreducible units in them (see astropy.units.UnitBase.decompose).

Parameters

basessequence of UnitBase, optional

The bases to decompose into. When not provided, decomposes down to any irreducible units. When provided, the decomposed result will only contain the given units. This will raises a UnitsError if it’s not possible to do so.

Returns

newqQuantity

A new object equal to this quantity with units decomposed.

diff(n=1, axis=- 1)

dot(b, out=None)

Dot product of two arrays.

Refer to numpy.dot for full documentation.

See also

numpy.dot

equivalent function

Examples

>>> a = np.eye(2)
>>> b = np.ones((2, 2)) * 2
>>> a.dot(b)
array([[2.,  2.],
       [2.,  2.]])

This array method can be conveniently chained:

>>> a.dot(b).dot(b)
array([[8.,  8.],
       [8.,  8.]])

dump(file)

Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.

Parameters

filestr or Path

A string naming the dump file.

Changed in version 1.17.0: pathlib.Path objects are now accepted.

dumps()

Returns the pickle of the array as a string. pickle.loads or numpy.loads will convert the string back to an array.

Parameters

None

ediff1d(to_end=None, to_begin=None)

fill(value)

Fill the array with a scalar value.

Parameters

valuescalar

All elements of a will be assigned this value.

Examples

>>> a = np.array([1, 2])
>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([1.,  1.])

insert(obj, values, axis=None)

Insert values along the given axis before the given indices and return a new Quantity object.

This is a thin wrapper around the numpy.insert function.

Parameters

objint, slice or sequence of ints

Object that defines the index or indices before which values is inserted.

valuesarray_like

Values to insert. If the type of values is different from that of quantity, values is converted to the matching type. values should be shaped so that it can be broadcast appropriately The unit of values must be consistent with this quantity.

axisint, optional

Axis along which to insert values. If axis is None then the quantity array is flattened before insertion.

Returns

outQuantity

A copy of quantity with values inserted. Note that the insertion does not occur in-place: a new quantity array is returned.

Examples

>>> import astropy.units as u
>>> q = [1, 2] * u.m
>>> q.insert(0, 50 * u.cm)
<Quantity [ 0.5,  1.,  2.] m>

>>> q = [[1, 2], [3, 4]] * u.m
>>> q.insert(1, [10, 20] * u.m, axis=0)
<Quantity [[  1.,  2.],
           [ 10., 20.],
           [  3.,  4.]] m>

>>> q.insert(1, 10 * u.m, axis=1)
<Quantity [[  1., 10.,  2.],
           [  3., 10.,  4.]] m>

item(*args)

Copy an element of an array to a standard Python scalar and return it.

Parameters

*argsArguments (variable number and type)

• none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.

• int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.

• tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.

Returns

zStandard Python scalar object

A copy of the specified element of the array as a suitable Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
       [1, 3, 6],
       [1, 0, 1]])
>>> x.item(3)
1
>>> x.item(7)
0
>>> x.item((0, 1))
2
>>> x.item((2, 2))
1

itemset(*args)

Insert scalar into an array (scalar is cast to array’s dtype, if possible)

There must be at least 1 argument, and define the last argument as item. Then, a.itemset(*args) is equivalent to but faster than a[args] = item. The item should be a scalar value and args must select a single item in the array a.

Parameters

*argsArguments

If one argument: a scalar, only used in case a is of size 1. If two arguments: the last argument is the value to be set and must be a scalar, the first argument specifies a single array element location. It is either an int or a tuple.

Notes

Compared to indexing syntax, itemset provides some speed increase for placing a scalar into a particular location in an ndarray, if you must do this. However, generally this is discouraged: among other problems, it complicates the appearance of the code. Also, when using itemset (and item) inside a loop, be sure to assign the methods to a local variable to avoid the attribute look-up at each loop iteration.

Examples

>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
       [1, 3, 6],
       [1, 0, 1]])
>>> x.itemset(4, 0)
>>> x.itemset((2, 2), 9)
>>> x
array([[2, 2, 6],
       [1, 0, 6],
       [1, 0, 9]])

mean(axis=None, dtype=None, out=None, keepdims=False)

Returns the average of the array elements along given axis.

Refer to numpy.mean for full documentation.

See also

numpy.mean

equivalent function

nansum(axis=None, out=None, keepdims=False)

put(indices, values, mode='raise')

Set a.flat[n] = values[n] for all n in indices.

Refer to numpy.put for full documentation.

See also

numpy.put

equivalent function

round(decimals=0, out=None)

Return a with each element rounded to the given number of decimals.

Refer to numpy.around for full documentation.

See also

numpy.around

equivalent function

searchsorted(v, side='left', sorter=None)

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted

See also

numpy.searchsorted

equivalent function

std(axis=None, dtype=None, out=None, ddof=0, keepdims=False)

Returns the standard deviation of the array elements along given axis.

Refer to numpy.std for full documentation.

See also

numpy.std

equivalent function

take(indices, axis=None, out=None, mode='raise')

Return an array formed from the elements of a at the given indices.

Refer to numpy.take for full documentation.

See also

numpy.take

equivalent function

to(unit, equivalencies=[], copy=True)

Return a new Quantity object with the specified unit.

Parameters

unitUnitBase instance, str

An object that represents the unit to convert to. Must be an UnitBase object or a string parseable by the units package.

equivalencieslist of equivalence pairs, optional

A list of equivalence pairs to try if the units are not directly convertible. See Equivalencies. If not provided or [], class default equivalencies will be used (none for Quantity, but may be set for subclasses) If None, no equivalencies will be applied at all, not even any set globally or within a context.

copybool, optional

If True (default), then the value is copied. Otherwise, a copy will only be made if necessary.

See also

to_value

get the numerical value in a given unit.

to_string(unit=None, precision=None, format=None, subfmt=None)

Generate a string representation of the quantity and its unit.

The behavior of this function can be altered via the numpy.set_printoptions function and its various keywords. The exception to this is the threshold keyword, which is controlled via the [units.quantity] configuration item latex_array_threshold. This is treated separately because the numpy default of 1000 is too big for most browsers to handle.

Parameters

unitUnitBase, optional

Specifies the unit. If not provided, the unit used to initialize the quantity will be used.

precisionnumeric, optional

The level of decimal precision. If None, or not provided, it will be determined from NumPy print options.

formatstr, optional

The format of the result. If not provided, an unadorned string is returned. Supported values are:

• ‘latex’: Return a LaTeX-formatted string

subfmtstr, optional

Subformat of the result. For the moment, only used for format=”latex”. Supported values are:

• ‘inline’: Use $ ... $ as delimiters.

• ‘display’: Use $\displaystyle ... $ as delimiters.

Returns

lstr

A string with the contents of this Quantity

to_value(unit=None, equivalencies=[])

The numerical value, possibly in a different unit.

Parameters

unitUnitBase instance or str, optional

The unit in which the value should be given. If not given or None, use the current unit.

equivalencieslist of equivalence pairs, optional

A list of equivalence pairs to try if the units are not directly convertible (see Equivalencies). If not provided or [], class default equivalencies will be used (none for Quantity, but may be set for subclasses). If None, no equivalencies will be applied at all, not even any set globally or within a context.

Returns

valuendarray or scalar

The value in the units specified. For arrays, this will be a view of the data if no unit conversion was necessary.

See also

to

Get a new instance in a different unit.

tobytes(order='C')

Construct Python bytes containing the raw data bytes in the array.

Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.

New in version 1.9.0.

Parameters

order{‘C’, ‘F’, None}, optional

Order of the data for multidimensional arrays: C, Fortran, or the same as for the original array.

Returns

sbytes

Python bytes exhibiting a copy of a’s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]], dtype='<u2')
>>> x.tobytes()
b'\x00\x00\x01\x00\x02\x00\x03\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x02\x00\x01\x00\x03\x00'

tofile(fid, sep='', format='%s')

Write array to a file as text or binary (default).

Data is always written in ‘C’ order, independent of the order of a. The data produced by this method can be recovered using the function fromfile().

Parameters

fidfile or str or Path

An open file object, or a string containing a filename.

Changed in version 1.17.0: pathlib.Path objects are now accepted.

sepstr

Separator between array items for text output. If “” (empty), a binary file is written, equivalent to file.write(a.tobytes()).

formatstr

Format string for text file output. Each entry in the array is formatted to text by first converting it to the closest Python type, and then using “format” % item.

Notes

This is a convenience function for quick storage of array data. Information on endianness and precision is lost, so this method is not a good choice for files intended to archive data or transport data between machines with different endianness. Some of these problems can be overcome by outputting the data as text files, at the expense of speed and file size.

When fid is a file object, array contents are directly written to the file, bypassing the file object’s write method. As a result, tofile cannot be used with files objects supporting compression (e.g., GzipFile) or file-like objects that do not support fileno() (e.g., BytesIO).

tolist()

Return the array as an a.ndim-levels deep nested list of Python scalars.

Return a copy of the array data as a (nested) Python list. Data items are converted to the nearest compatible builtin Python type, via the item function.

If a.ndim is 0, then since the depth of the nested list is 0, it will not be a list at all, but a simple Python scalar.

Parameters

none

Returns

yobject, or list of object, or list of list of object, or …

The possibly nested list of array elements.

Notes

The array may be recreated via a = np.array(a.tolist()), although this may sometimes lose precision.

Examples

For a 1D array, a.tolist() is almost the same as list(a), except that tolist changes numpy scalars to Python scalars:

>>> a = np.uint32([1, 2])
>>> a_list = list(a)
>>> a_list
[1, 2]
>>> type(a_list[0])
<class 'numpy.uint32'>
>>> a_tolist = a.tolist()
>>> a_tolist
[1, 2]
>>> type(a_tolist[0])
<class 'int'>

Additionally, for a 2D array, tolist applies recursively:

>>> a = np.array([[1, 2], [3, 4]])
>>> list(a)
[array([1, 2]), array([3, 4])]
>>> a.tolist()
[[1, 2], [3, 4]]

The base case for this recursion is a 0D array:

>>> a = np.array(1)
>>> list(a)
Traceback (most recent call last):
  ...
TypeError: iteration over a 0-d array
>>> a.tolist()
1

tostring(order='C')

A compatibility alias for tobytes, with exactly the same behavior.

Despite its name, it returns bytes not strs.

Deprecated since version 1.19.0.

trace(offset=0, axis1=0, axis2=1, dtype=None, out=None)

Return the sum along diagonals of the array.

Refer to numpy.trace for full documentation.

See also

numpy.trace

equivalent function

var(axis=None, dtype=None, out=None, ddof=0, keepdims=False)

Returns the variance of the array elements, along given axis.

Refer to numpy.var for full documentation.

See also

numpy.var

equivalent function