Quantity¶

class
astropy.units.
Quantity
(value, unit=None, dtype=None, copy=True, order=None, subok=False, ndmin=0)[source]¶ 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
(sequence), orstr
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 aunit
attribute), creates a newQuantity
object, converting tounit
units as needed. If a string, it is converted to a number orQuantity
, depending on whether a unit is present. unitastropy:unitlike
An object that represents the unit associated with the input value. Must be an
UnitBase
object or a string parseable by theunits
package. dtype
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 (nonQuantity) 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 givendtype
. (TheFalse
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 aQuantity
andcopy=False
. subokbool, optional
If
False
(default), the returned array will be forced to be aQuantity
. Otherwise,Quantity
subclasses will be passed through, or a subclass appropriate for the unit will be used (such asDex
foru.dex(u.AA)
). ndmin
int
, optional Specifies the minimum number of dimensions that the resulting array should have. Ones will be prepended to the shape as needed to meet this requirement. This parameter is ignored if the input is a
Quantity
andcopy=False
.
 valuenumber,
 Raises
Notes
Quantities can also be created by multiplying a number or array with a
Unit
. See https://docs.astropy.org/en/latest/units/Unless the
dtype
argument is explicitly specified, integer or (nonQuantity) object inputs are converted tofloat
by default.Attributes Summary
Returns a copy of the current
Quantity
instance with CGS units.A list of equivalencies that will be applied by default during unit conversions.
A 1D iterator over the Quantity array.
Container for meta information like name, description, format.
True if the
value
of this quantity is a scalar, or False if it is an arraylike object.Returns a copy of the current
Quantity
instance with SI units.A
UnitBase
object representing the unit of this quantity.The numerical value of this instance.
Methods Summary
all
([axis, out, keepdims, where])Returns True if all elements evaluate to True.
any
([axis, out, keepdims, where])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.
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])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 scalar Quantity and return it.
itemset
(*args)Insert scalar into an array (scalar is cast to array’s dtype, if possible)
mean
([axis, dtype, out, keepdims, where])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 alln
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, where])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, where])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 1D iterator over the Quantity array.
This returns a
QuantityIterator
instance, which behaves the same as theflatiter
instance returned byflat
, and is similar to, but not a subclass of, Python’s builtin 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 arraylike object.Note
This is subtly different from
numpy.isscalar
in thatnumpy.isscalar
returns False for a zerodimensional 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.

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, *, where=True)[source]¶ 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, *, where=True)[source]¶ 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)[source]¶ 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)[source]¶ Return indices of the minimum values along the given axis.
Refer to
numpy.argmin
for detailed documentation.See also
numpy.argmin
equivalent function

argsort
(axis= 1, kind=None, order=None)[source]¶ 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')[source]¶ 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=[])[source]¶ Generates a new
Quantity
with the units decomposed. Decomposed units have only irreducible units in them (seeastropy.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.
 basessequence of
 Returns
 newq
Quantity
A new object equal to this quantity with units decomposed.
 newq

dump
(file)[source]¶ Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.
 Parameters
 file
str
or Path A string naming the dump file.
Changed in version 1.17.0:
pathlib.Path
objects are now accepted.
 file

dumps
()[source]¶ Returns the pickle of the array as a string. pickle.loads will convert the string back to an array.
 Parameters
 None

fill
(value)[source]¶ 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)[source]¶ 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
 obj
int
,slice
or sequence ofint
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 ofvalues
must be consistent with this quantity. axis
int
, optional Axis along which to insert
values
. Ifaxis
is None then the quantity array is flattened before insertion.
 obj
 Returns
 out
Quantity
A copy of quantity with
values
inserted. Note that the insertion does not occur inplace: a new quantity array is returned.
 out
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)[source]¶ Copy an element of an array to a scalar Quantity and return it.
Like
item()
except that it always returns aQuantity
, not a Python scalar.

itemset
(*args)[source]¶ 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 thana[args] = item
. The item should be a scalar value andargs
must select a single item in the arraya
. 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 anndarray
, if you must do this. However, generally this is discouraged: among other problems, it complicates the appearance of the code. Also, when usingitemset
(anditem
) inside a loop, be sure to assign the methods to a local variable to avoid the attribute lookup 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, *, where=True)[source]¶ Returns the average of the array elements along given axis.
Refer to
numpy.mean
for full documentation.See also
numpy.mean
equivalent function

put
(indices, values, mode='raise')[source]¶ Set
a.flat[n] = values[n]
for alln
in indices.Refer to
numpy.put
for full documentation.See also
numpy.put
equivalent function

round
(decimals=0, out=None)[source]¶ 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)[source]¶ 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, *, where=True)[source]¶ 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')[source]¶ 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)[source]¶ Return a new
Quantity
object with the specified unit. Parameters
 unitastropy:unitlike
An object that represents the unit to convert to. Must be an
UnitBase
object or a string parseable by theunits
package. equivalencies
list
oftuple
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 forQuantity
, but may be set for subclasses) IfNone
, 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)[source]¶ 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 thethreshold
keyword, which is controlled via the[units.quantity]
configuration itemlatex_array_threshold
. This is treated separately because the numpy default of 1000 is too big for most browsers to handle. Parameters
 unitastropy:unitlike, optional
Specifies the unit. If not provided, the unit used to initialize the quantity will be used.
 precisionnumber, optional
The level of decimal precision. If
None
, or not provided, it will be determined from NumPy print options. format
str
, optional The format of the result. If not provided, an unadorned string is returned. Supported values are:
‘latex’: Return a LaTeXformatted string
 subfmt
str
, 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
str
A string with the contents of this Quantity

to_value
(unit=None, equivalencies=[])[source]¶ The numerical value, possibly in a different unit.
 Parameters
 unitastropy:unitlike, optional
The unit in which the value should be given. If not given or
None
, use the current unit. equivalencies
list
oftuple
, 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 forQuantity
, but may be set for subclasses). IfNone
, no equivalencies will be applied at all, not even any set globally or within a context.
 Returns
See also
to
Get a new instance in a different unit.

tobytes
(order='C')[source]¶ 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 is produced in Corder by default. This behavior is controlled by the
order
parameter.New in version 1.9.0.
 Parameters
 order{‘C’, ‘F’, ‘A’}, optional
Controls the memory layout of the bytes object. ‘C’ means Corder, ‘F’ means Forder, ‘A’ (short for Any) means ‘F’ if
a
is Fortran contiguous, ‘C’ otherwise. Default is ‘C’.
 Returns
 s
bytes
Python bytes exhibiting a copy of
a
’s raw data.
 s
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')[source]¶ 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 object 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. sep
str
Separator between array items for text output. If “” (empty), a binary file is written, equivalent to
file.write(a.tobytes())
. format
str
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.
 fidfile object or
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 filelike objects that do not supportfileno()
(e.g., BytesIO).

tolist
()[source]¶ 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
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 aslist(a)
, except thattolist
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 0d array >>> a.tolist() 1

tostring
(order='C')[source]¶ A compatibility alias for
tobytes
, with exactly the same behavior.Despite its name, it returns
bytes
notstr
s.Deprecated since version 1.19.0.

trace
(offset=0, axis1=0, axis2=1, dtype=None, out=None)[source]¶ Return the sum along diagonals of the array.
Refer to
numpy.trace
for full documentation.See also
numpy.trace
equivalent function