The ASDF_NDARRAY function creates a new ASDF_NDArray object, which can be used to convert an IDL array for storage in an ASDF file. An ASDF_NDArray object will automatically be returned from the ASDF_PARSE function for every "ndarray" within the ASDF file.

Tip: ASDF_NDArray objects that are returned from ASDF_Parse are "lazy loading". The actual array data is not loaded into memory until the data is accessed using bracket notation or the dot operator.

Examples


Create an ASDF_NDArray containing a random float array of dimensions 5 x 3:

seed=1 & x = ASDF_NDArray(randomu(seed, 5, 3))
help, x

IDL prints:

X           ASDF_NDARRAY  <ID=1>  float32 [3,5] internal

Notice that the dimensions of the IDL array are reported in reverse order in the ASDF_NDArray, since Python numpy arrays are row major instead of column major like IDL. Note also that by default the array is marked as "internal", indicating that it will be stored inside the ASDF file in a data block.

Syntax


Result = ASDF_NDArray( [Data] )

Return Value


Returns a reference to the newly-created ASDF_NDArray.

Arguments


Data

Set this argument to an IDL array containing the data. You can also set the data using array indexing with the "data" key, or using dot notation. For example, all of the following are equivalent:

mydata = findgen(100)
a = ASDF_NDArray(mydata)
 
a = ASDF_NDArray()
a['data'] = mydata
 
a = ASDF_NDArray()
a.data = mydata

Note: If Data is a scalar, then a 1-element array will be stored.

Keywords


None

Properties


All properties can be set and retrieved using the dot "." operator.

ANCHOR

Set this property to a string containing the YAML anchor associated with this ASDF_NDArray. Do not include the "&"; it will be added automatically when serializing to YAML.

COMPRESSION

Set this property to a string giving the compression method for the data within the ASDF file. Valid values are:

  • none: Indicates that no compression should be used when writing out the data.

  • zlib: Indicates that zlib compression should be used when writing out the data.

Note: Other compression methods are available within the ASDF standard such as bzp2 and lz4. These are not currently supported in IDL. Attempting to retrieve data that was compressed using one of these formats will throw an error. If you attempt to write out data using one of these formats, then zlib will be used instead.

DATA

Set this property to an IDL scalar or array containing the data. To retrieve the data you can use either array notation, such as a['data'], or dot notation, such as a.data.

Note: If Data is a scalar, then a 1-element array will be stored.

STORAGE

Set this property to a string giving the desired storage method for the data within the ASDF file. Valid values are:

  • inline: Indicates that the data should be stored directly within the YAML tree structure. This should only be used for small arrays. This is the default for scalars and arrays of 10 or fewer elements.

  • internal: Store the data within an ASDF block at the end of the same ASDF file. This is the default for arrays of more than 10 elements.

  • external: Store the data in an external file. When the ASDF file is written out, a new external file will automatically be created with . See ASDF_WRITE for details.

Note: If you read in an ASDF file using ASDF_Parse, then any ASDF_NDArray objects will be automatically marked as inline, internal, or external depending upon how they were stored within the file. You can get the STORAGE property to examine this value, or you can set the STORAGE property to a different value to change the storage method when the data is written back out to a new ASDF file.

Variable Information


HELP

The HELP procedure provides general information:

IDL> x = ASDF_NDArray(bindgen(6,2))
IDL> help, x
X               ASDF_NDARRAY  <ID=63>  uint8 [2,6] internal

PRINT and Implied Print

The PRINT procedure and Implied Print serialize the output in YAML format:

IDL> x = ASDF_NDArray(bindgen(6,2))
IDL> print, x
!core/ndarray-1.0.0
shape: [2,6]
byteorder: little
datatype: uint8
source: 0

Additional Examples


Create an ASDF_NDArray containing a random float array of dimensions 5 x 3:

seed=1 & x = ASDF_NDArray(randomu(seed, 5, 3))
help, x
print, x

IDL prints:

X           ASDF_NDARRAY  <ID=1>  float32 [3,5] internal
!core/ndarray-1.0.0
shape: [3,5]
byteorder: little
datatype: float32
source: 0

Notice that the dimensions of the IDL array are reported in reverse order in the ASDF_NDArray, since Python numpy arrays are row major instead of column major like IDL. Note also that by default the array is marked as "internal", indicating that it will be stored inside the ASDF file in a data block.

You can access the original array using either array indexing with the "data" key, or by using the dot operator:

help, x['data']
help, x.data

Tip: ASDF_NDArray objects that are returned from ASDF_Parse are "lazy loading". The actual array data is not loaded into memory until the data is accessed using bracket notation or the dot operator.

Now create an ASDF_File containing this object and write it out:

file = ASDF_File('mydata', x)
ASDF_WRITE, 'mydata.asdf', file

We can read the data back in using ASDF_PARSE and access the array data using nested array indexing and the "data" key:

result = ASDF_PARSE('mydata.asdf')
print, result['mydata', 'data']

IDL prints:

0.417022     0.997185     0.720325     0.932557  0.000114381
0.128124     0.302333     0.999041     0.146756     0.236089
0.0923386     0.396581     0.186260     0.387911     0.345561

Version History


8.9

Introduced

See Also


ASDF_FILE, ASDF_PARSE, ASDF_WRITE