--- title: "NumericArray" language: "en" type: "Symbol" summary: "NumericArray[array, type] creates a numeric array of the specified type. NumericArray[array, type, method] uses method to convert numbers into type." keywords: - array - raw array - byte array - numeric array - number array - integer 8 - integer 16 - int8 - int16 - char - unsigned char - unsigned int - signed int - bit16 - real32 - real64 - complex array - complex 64 - complex 128 - single precision complex - double precision complex - single precision - double precision - typed array - type array - packed array - compact array - MNumericArray canonical_url: "https://reference.wolfram.com/language/ref/NumericArray.html" source: "Wolfram Language Documentation" related_guides: - title: "Binary Data" link: "https://reference.wolfram.com/language/guide/BinaryData.en.md" - title: "Encoding and Decoding Data for Neural Networks" link: "https://reference.wolfram.com/language/guide/NetEncoderDecoder.en.md" - title: "List Manipulation" link: "https://reference.wolfram.com/language/guide/ListManipulation.en.md" --- [EXPERIMENTAL] # NumericArray NumericArray[array, type] creates a numeric array of the specified type. NumericArray[array, type, method] uses method to convert numbers into type. ## Details and Options * ``NumericArray`` provides the most compact representation of ``array`` to reduce memory usage and enhance speed of execution. * The input ``array`` can be a full list of any depth containing machine‐sized integers and machine‐sized approximate real and complex numbers. * Possible settings for ``type`` include: | | | | --- | --- | | "Integer8" | signed 8-bit integers from $-128$ through 127 | | "UnsignedInteger8" | integers 0 through 255 | | "Integer16" | signed 16-bit integers from $-2^{15}$ through $2^{15}-1$ | | "UnsignedInteger16" | integers 0 through 65535 | | "Integer32" | signed 32-bit integers from $-2^{31}$ through $2^{31}-1$ | | "UnsignedInteger32" | integers 0 through $2^{32}-1$ | | "Integer64" | signed 64-bit integers from $-2^{63}$ through $2^{63}-1$ | | "UnsignedInteger64" | integers 0 through $2^{64}-1$ | | "Real32" | single-precision real (32-bit) | | "Real64" | double-precision real (64-bit) | | "ComplexReal32" | single-precision complex | | "ComplexReal64" | double-precision complex | * ``NumericArray[array, type]`` clips values to the range supported by ``type`` and rounds reals to integers, if necessary. * Other conversion ``method`` settings include: | | | | --------------- | ------------------------------------------------- | | "Check" | checks values to be compatible with type | | "Coerce" | coerces to type | | "Round" | rounds reals to integers | | "ClipAndCheck" | clips to the range and checks for compatible type | | "ClipAndCoerce" | clips to the range and coerces to type | | "ClipAndRound" | clips to the range and rounds reals to integers | * For complex numbers, the method is applied separately to real and imaginary parts. * ``NumericArray`` is treated as a raw object by functions like ``AtomQ`` and for purposes of pattern matching. * ``Normal[NumericArray[…]]`` yields the list of values in the numeric array. * Functions such as ``Length``, ``Equal`` and ``First`` work with ``NumericArray`` objects. * Functions such as ``Part``, ``Take`` and ``Drop`` can be used to take or drop parts of a ``NumericArray`` object. * Functions such as ``ListPlot``, ``ArrayPlot`` and ``BarChart`` can visualize a ``NumericArray`` object. --- ## Examples (26) ### Basic Examples (2) Create a vector of byte size integers: ```wl In[1]:= NumericArray[Range[100], "UnsignedInteger8"] Out[1]= RawArray["UnsignedInteger8", {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100}] ``` --- Convert a matrix of reals to a numeric array: ```wl In[1]:= NumericArray[RandomReal[1, {5, 5}], "Real64"] Out[1]= RawArray["Real64", {{0.811420775441924, 0.9534189704822713, 0.25485076689409847, 0.30753315014716653, 0.9302909648576219}, {0.6957676231968468, 0.2527441940448971, 0.7426736969244108, 0.7117429766065946, 0.9055001251083981}, {0.995784559 ... 9, 0.3243733152005248}, {0.030762059085189586, 0.5607865416286868, 0.3780849879539294, 0.07562708699696685, 0.08583862063208847}, {0.48533961158514116, 0.6268784851030069, 0.5613448285736222, 0.010671060470677896, 0.4050112787049527}}] ``` Convert back to a regular list: ```wl In[2]:= Normal[%] Out[2]= {{0.811421, 0.953419, 0.254851, 0.307533, 0.930291}, {0.695768, 0.252744, 0.742674, 0.711743, 0.9055}, {0.995785, 0.747707, 0.569719, 0.912808, 0.324373}, {0.0307621, 0.560787, 0.378085, 0.0756271, 0.0858386}, {0.48534, 0.626878, 0.561345, 0.0106711, 0.405011}} ``` ### Scope (20) #### Basic Uses (6) Create a numeric array from a list using a specific type: ```wl In[1]:= NumericArray[{1, 2, 3, 4}, "Real32"] Out[1]= RawArray["Real32", {1., 2., 3., 4.}] ``` --- Specify the conversion method to fit numbers in the desired type: ```wl In[1]:= NumericArray[{1, 2, 3, $MaxMachineNumber}, "Real32", "ClipAndCoerce"] Out[1]= RawArray["Real32", {1., 2., 3., 3.4028234663852886*^38}] ``` --- Create a 2D numeric array: ```wl In[1]:= NumericArray[{{1, 2}, {3, 4}}, "UnsignedInteger8"] Out[1]= RawArray["UnsignedInteger8", {{1, 2}, {3, 4}}] ``` --- Convert ``ByteArray`` to ``NumericArray`` : ```wl In[1]:= ba = ByteArray[{1, 2, 3, 4}]; In[2]:= NumericArray[ba, "UnsignedInteger8"] Out[2]= RawArray["UnsignedInteger8", {1, 2, 3, 4}] ``` --- Convert ``SparseArray`` to ``NumericArray`` : ```wl In[1]:= s = SparseArray[{{1, 1} -> 1, {2, 2} -> 2, {3, 3} -> 3, {4, 4} -> 4}] Out[1]= SparseArray[Automatic, {4, 4}, 0, {1, {{0, 1, 2, 3, 4}, {{1}, {2}, {3}, {4}}}, {1, 2, 3, 4}}] In[2]:= NumericArray[s, "UnsignedInteger8"] Out[2]= RawArray["UnsignedInteger8", {{1, 0, 0, 0}, {0, 2, 0, 0}, {0, 0, 3, 0}, {0, 0, 0, 4}}] ``` --- Convert ``SymmetrizedArray`` to ``NumericArray`` : ```wl In[1]:= s = SymmetrizedArray[{{i_, i_, i_, i_} -> 1, {i_, i_, j_, j_} :> i + j}, {4, 4, 4, 4}, {Symmetric[{1, 2, 3, 4}]}] Out[1]= SymmetrizedArray[StructuredArray`StructuredData[{4, 4, 4, 4}, {{{1, 1, 1, 1} -> 1, {1, 1, 2, 2} -> 3, {1, 1, 3, 3} -> 4, {1, 1, 4, 4} -> 5, {2, 2, 2, 2} -> 1, {2, 2, 3, 3} -> 5, {2, 2, 4, 4} -> 6, {3, 3, 3, 3} -> 1, {3, 3, 4, 4} -> 7, {4, 4, 4, 4} -> 1}, Symmetric[{1, 2, 3, 4}]}]] In[2]:= NumericArray[s, "UnsignedInteger8"] Out[2]= RawArray["UnsignedInteger8", {{{{1, 0, 0, 0}, {0, 3, 0, 0}, {0, 0, 4, 0}, {0, 0, 0, 5}}, {{0, 3, 0, 0}, {3, 0, 0, 0}, {0, 0, 0, 0}, {0, 0, 0, 0}}, {{0, 0, 4, 0}, {0, 0, 0, 0}, {4, 0, 0, 0}, {0, 0, 0, 0}}, {{0, 0, 0, 5}, {0, 0, 0, 0}, {0, 0 ... {{{0, 0, 0, 5}, {0, 0, 0, 0}, {0, 0, 0, 0}, {5, 0, 0, 0}}, {{0, 0, 0, 0}, {0, 0, 0, 6}, {0, 0, 0, 0}, {0, 6, 0, 0}}, {{0, 0, 0, 0}, {0, 0, 0, 0}, {0, 0, 0, 7}, {0, 0, 7, 0}}, {{5, 0, 0, 0}, {0, 6, 0, 0}, {0, 0, 7, 0}, {0, 0, 0, 1}}}}] ``` #### NumericArray Types (3) ##### Integers (1) --- Create an 8-bit unsigned integer numeric array: ```wl In[1]:= NumericArray[{0, 1, 2}, "UnsignedInteger8"]//Normal Out[1]= {0, 1, 2} ``` For a larger integer, use a larger integer type: ```wl In[2]:= NumericArray[{0, 1000, 2000}, "UnsignedInteger16"]//Normal Out[2]= {0, 1000, 2000} ``` Clip large values into a smaller integer type: ```wl In[3]:= NumericArray[{0, 1000, 2000}, "UnsignedInteger8", "ClipAndCoerce"]//Normal Out[3]= {0, 255, 255} ``` Real numbers can be rounded when converted into an integer type: ```wl In[4]:= NumericArray[{.1, 1.1, 2.1}, "UnsignedInteger8", "Round"]//Normal Out[4]= {0, 1, 2} ``` ##### Reals (1) --- Create a 32-bit real numeric array: ```wl In[1]:= NumericArray[{.1, 1.1, 2.1}, "Real32"]//Normal Out[1]= {0.1, 1.1, 2.1} ``` Coerce exact numbers into reals: ```wl In[2]:= NumericArray[{1 / 3, 2 / 3}, "Real32", "Coerce"]//Normal Out[2]= {0.333333, 0.666667} ``` ##### Complexes (1) --- Create a complex numeric array: ```wl In[1]:= NumericArray[{1 + 2I}, "ComplexReal32"]//Normal Out[1]= {1.  + 2. I} ``` Coerce exact real and imaginary parts of a complex number into reals: ```wl In[2]:= NumericArray[{1 / 3 + 2 / 3I}, "ComplexReal32", "Coerce"]//Normal Out[2]= {0.333333  + 0.666667 I} ``` #### Converting between NumericArray Objects (2) Convert an ``"Integer8"`` array to ``"Real32"`` : ```wl In[1]:= na = NumericArray[{-100, 0, 5, 120}, "Integer8"] Out[1]= RawArray["Integer8", {-100, 0, 5, 120}] In[2]:= NumericArray[na, "Real32"] Out[2]= RawArray["Real32", {-100., 0., 5., 120.}] ``` --- If numbers cannot be represented in the new type, specify a conversion method: ```wl In[1]:= na = NumericArray[{-100, 0, 5, 120}, "Integer8"] Out[1]= RawArray["Integer8", {-100, 0, 5, 120}] In[2]:= NumericArray[na, "UnsignedInteger8", "ClipAndCoerce"] Out[2]= RawArray["UnsignedInteger8", {0, 0, 5, 120}] ``` #### Operating on a NumericArray (9) ##### Array Properties (3) --- ``ByteCount`` of a numeric array: ```wl In[1]:= na = NumericArray[{1, 2, 3, 4}, "UnsignedInteger8"]; ByteCount[na] Out[1]= 100 ``` --- ``Dimensions`` : ```wl In[1]:= na = NumericArray[{1, 2, 3, 4}, "UnsignedInteger8"]; Dimensions[na] Out[1]= {4} ``` --- ``ArrayDepth`` : ```wl In[1]:= na = NumericArray[{1, 2, 3, 4}, "UnsignedInteger8"]; ArrayDepth[na] Out[1]= 1 ``` ##### Structural Operations (6) --- Flatten a numeric array: ```wl In[1]:= na = NumericArray[{{1, 2}, {3, 4}}, "UnsignedInteger8"] Out[1]= RawArray["UnsignedInteger8", {{1, 2}, {3, 4}}] In[2]:= Flatten[na] Out[2]= RawArray["UnsignedInteger8", {1, 2, 3, 4}] ``` --- ``Normal`` converts a numeric array to a ``List`` : ```wl In[1]:= na = NumericArray[{1, 2, 3, 4}, "UnsignedInteger8"]; Normal[na] Out[1]= {1, 2, 3, 4} ``` --- Apply ``Join`` to numeric array objects: ```wl In[1]:= na = NumericArray[{1, 2, 3, 4}, "UnsignedInteger8"]; Join[na, na] Out[1]= RawArray["UnsignedInteger8", {1, 2, 3, 4, 1, 2, 3, 4}] ``` --- Use ``Part`` to take a part of a numeric array: ```wl In[1]:= NumericArray[Range[100], "UnsignedInteger8"][[1]] Out[1]= 1 ``` --- Use ``Take`` to take a part of a numeric array: ```wl In[1]:= na = NumericArray[{1, 2, 3, 4}, "UnsignedInteger8"]; Take[na, {2, 3}] Out[1]= RawArray["UnsignedInteger8", {2, 3}] ``` --- Apply ``Drop`` to elements of a numeric array: ```wl In[1]:= na = NumericArray[{1, 2, 3, 4}, "UnsignedInteger8"]; Drop[na, 2] Out[1]= RawArray["UnsignedInteger8", {3, 4}] ``` ### Properties & Relations (2) Byte count of a ``NumericArray`` is less than the equivalent list of random integers: ```wl In[1]:= ByteCount[r = RandomInteger[255, {10, 10}]] Out[1]= 944 In[2]:= ByteCount[NumericArray[r, "UnsignedInteger8"]] Out[2]= 196 ``` --- ``Normal`` can convert a ``NumericArray`` to a normal expression: ```wl In[1]:= Normal[NumericArray[Range[10], "UnsignedInteger8"]] Out[1]= {1, 2, 3, 4, 5, 6, 7, 8, 9, 10} ``` ### Possible Issues (2) Some conversion methods may not give numbers suitable for the new type: ```wl In[1]:= na = NumericArray[{-100, 0, 5, 120.5}, "Real32"] Out[1]= RawArray["Real32", {-100., 0., 5., 120.5}] In[2]:= NumericArray[na, "Integer8", "ClipAndCoerce"] ``` NumericArray::nconvss: The argument NumericArray[Type: Real32 Dimensions: {4} ] cannot be converted to a NumericArray of type Integer8 using the method ClipAndCoerce. ```wl Out[2]= NumericArray[RawArray["Real32", {-100., 0., 5., 120.5}], "Integer8", "ClipAndCoerce"] ``` Use a conversion that yields numbers supported by the new type: ```wl In[3]:= NumericArray[na, "Integer8", "ClipAndRound"] Out[3]= RawArray["Integer8", {-100, 0, 5, 120}] ``` --- The default conversion method will fail when the input array contains numbers that are out of range for the specified type. Try to store $-129$ in an ``"Integer8"`` numeric array: ```wl In[1]:= NumericArray[{-129}, "Integer8"] ``` NumericArray::nconvsa: The argument {-129} cannot be automatically converted to a NumericArray of type Integer8. Try using one of the following conversion methods: "Round", "ClipAndCoerce" or "ClipAndRound". ```wl Out[1]= NumericArray[{-129}, "Integer8"] ``` Use the ``"ClipAndCoerce"`` method to automatically clip to the smallest ``"Integer8"`` : ```wl In[2]:= NumericArray[{-129}, "Integer8", "ClipAndCoerce"] Out[2]= RawArray["Integer8", {-128}] ``` ## See Also * [`List`](https://reference.wolfram.com/language/ref/List.en.md) * [`ByteArray`](https://reference.wolfram.com/language/ref/ByteArray.en.md) * [`Normal`](https://reference.wolfram.com/language/ref/Normal.en.md) * [`NumericArrayType`](https://reference.wolfram.com/language/ref/NumericArrayType.en.md) * [`NumericArrayQ`](https://reference.wolfram.com/language/ref/NumericArrayQ.en.md) * [`SparseArray`](https://reference.wolfram.com/language/ref/SparseArray.en.md) * [`Image`](https://reference.wolfram.com/language/ref/Image.en.md) * [`Audio`](https://reference.wolfram.com/language/ref/Audio.en.md) * [`NumericArray`](https://reference.wolfram.com/language/ref/compiledtype/NumericArray.en.md) * [`PackedArray`](https://reference.wolfram.com/language/ref/compiledtype/PackedArray.en.md) ## Related Guides * [Binary Data](https://reference.wolfram.com/language/guide/BinaryData.en.md) * [Encoding and Decoding Data for Neural Networks](https://reference.wolfram.com/language/guide/NetEncoderDecoder.en.md) * [List Manipulation](https://reference.wolfram.com/language/guide/ListManipulation.en.md) ## History * [Introduced in 2019 (12.0)](https://reference.wolfram.com/language/guide/SummaryOfNewFeaturesIn120.en.md)