ASDF_PARSE

The ASDF_PARSE function takes an ASDF (Advanced Scientific Data Format) file and reads it into an IDL variable containing all of the data references in a nested hierarchy. The ASDF file format consists of a YAML header followed by zero or more binary data blocks. Binary data can also be stored separately in external files that are linked to the main ASDF file.

This routine is written in the IDL language. Its source code can be found in the file asdf_parse.pro in the lib/datatypes subdirectory of the IDL distribution.

Tip: The result of ASDF_PARSE is a nested hierarchy of ASDF and YAML objects, arrays, and scalar values. If you print out the result, the output will automatically be printed in YAML format.

Examples

Create a simple ASDF file, then read it back into IDL:

a = ASDF_File('mydata', randomu(seed, 100, 50))

ASDF_Write, 'myfile.asdf', a

af = ASDF_Parse('myfile.asdf')

help, af

help, af['mydata']

help, af['mydata', 'data']

IDL prints:

AF              ASDF_FILE  <ID=28  NELEMENTS=3>  TAG='!core/asdf-1.1.0' GLOBAL_TAGS=1

<Expression>    ASDF_NDARRAY  <ID=27>  float32 [50,100] internal

<Expression>    FLOAT     = Array[100, 50]

Syntax

Result = ASDF_PARSE(Filename)

Return Value

The result is a nested hierarchy of ASDF objects, IDL arrays, and IDL scalar values. See below for the rules on converting ASDF data into IDL datatypes.

Arguments

Filename

Filename must be a string containing the file path to the ASDF file.

Keywords

None

Conversion Rules

When converting ASDF files into IDL variables, the following rules are used:

ASDF Item	IDL Variable Type	Notes
Main Document	ASDF_File	Optional global TAG property
Mapping	YAML_Map	Optional ANCHOR, TAG properties
!!set	YAML_Map	Mapping of keys with !NULL values
ASDF !core/ndarray-1.0.0	ASDF_NDArray	Array dimensions will be reversed
Sequence of mixed types	YAML_Sequence	Optional ANCHOR, TAG properties
Sequence of same types¹	Array	Boolean, LONG64, DOUBLE, DCOMPLEX
!!omap	YAML_Sequence	Sequence of ASDF_Maps
Scalar value with unknown tag³	YAML_Value	TAG and VALUE properties
Scalar value with an anchor²	YAML_Value	ANCHOR, VALUE properties, optional TAG
Alias (reference)	YAML_Alias	ALIAS property
Quoted string	String
~, null, Null, NULL	!NULL
false, False, FALSE, true, True, TRUE	Boolean
Integer from –2⁶³ to 2⁶³–1	LONG64
Integers larger than +/–2⁶³	BigInteger
Floating-point number	DOUBLE
!!binary with base64	Byte array
!!python/complex or !core/complex-1.0.0	DCOMPLEX

¹A sequence with both integers and floating-point values will be returned as an IDL array of type DOUBLE.

²A YAML scalar with an anchor will be returned as a YAML_Value object. The VALUE property will contain the scalar value as a string, and will not be converted to one of the other scalar types.

³A YAML scalar with an unknown tag will be returned as a YAML_Value object. The VALUE property will contain the scalar value as a string, and will not be converted to one of the other scalar types.

Conformance

See YAML_PARSE for information on IDL's conformance to the YAML standard.

Additional Examples

You can construct ASDF files from regular IDL arrays, scalars, hashes, or lists. Using hashes or lists allows you to create a nested hierarchy of data. ASDF_Write will automatically search for IDL arrays within the nested hierarchy and will write them out as ASDF ndarray blocks. For example:

cal = OrderedHash()

cal['title'] = 'Calibration Data'

cal['date'] = 2023

cal['telescope'] = 'JWST'

cal['calibration'] = findgen(10)

file = ASDF_File('Calibration', cal)

Add another data block to the same file using array indexing, and then write out the data to a file:

file['Image'] = bindgen(3, 100, 50)

ASDF_Write, 'calibration.asdf', file

Parse the file and access the data using array indexing:

IDL> file = ASDF_Parse('calibration.asdf')

IDL> help, file['Calibration']

<Expression>    YAML_MAP  <ID=209  NELEMENTS=4>

IDL> help, file['Calibration', 'title']

<Expression>    STRING    = 'Calibration Data'

IDL> help, file['Calibration', 'calibration']

<Expression>    ASDF_NDARRAY  <ID=217>  float32 [10] inline

IDL> help, file['Calibration', 'calibration', 'data']

<Expression>    DOUBLE    = Array[10]

The calibration data only has 10 elements, so it was immediately read in during ASDF_Parse.

The Image data is stored in an internal data block, and is automatically read from the file when the actual array is accessed:

IDL> help, file['Image', 'data']

<Expression>    BYTE      = Array[3, 100, 50]

You can Also construct Structured arrays by using an array of IDL Struct:

                NormalStruct = create_struct("internal1", 4, "internal2", 5.5, /PRESERVE_CASE)
OuterStruct = create_struct("nestedStruct", NormalStruct, "internal", 11, /PRESERVE_CASE)

arrOfStructs = replicate(OuterStruct, 10000)
file = asdf_file('Struct', arrOfStructs)

tmpfile = qa_filepath(/supply_name, ext='.asdf', /tmp)
ASDF_WRITE, tmpfile, file
af = ASDF_PARSE(tmpfile)

print, af