The ASDF_FILE function creates a new ASDF_File object, which can be used to construct an ASDF file. The object contains the appropriate ASDF header, along with a nested hierarchy of variables. These variables can include objects of type ASDF_NDArray, YAML_Map, YAML_Sequence, Hash, List, or regular IDL arrays or scalars. ASDF_File is a subclass of YAML_Stream_Map, and inherits all of the methods and properties of that class.

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

Note: Calling ASDF_PARSE will automatically return an ASDF_File object. You can then access all of the nested variables using array indexing.

Note: Printing an ASDF_File object will automatically call YAML_SERIALIZE and the output will be in YAML format. To output a full ASDF file, call ASDF_WRITE.

Example


Create an ASDF file containing a single variable:

file = ASDF_File('mydata', findgen(100,50))
help, file['mydata']

IDL prints:

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

Note that the array was automatically converted into an ASDF_NDArray object when added to the ASDF_File. The dimensions are also reported in reverse order, since Python ndarrays are row-major, not column major like IDL.

 

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

file['moredata'] = bindgen(3, 100, 50)
ASDF_Write, 'myfile.asdf', file

 

If you parse an ASDF file, then the data will be returned as an ASDF_File. For example, using the file above:

a = ASDF_Parse('myfile.asdf')
help, a, a['mydata'], a['moredata']

IDL prints:

A               ASDF_FILE  <ID=15  NELEMENTS=4>  TAG='!core/asdf-1.1.0' GLOBAL_TAGS=1
<Expression>    ASDF_NDARRAY  <ID=13>  float32 [50,100] internal
<Expression>    ASDF_NDARRAY  <ID=14>  uint8 [50,100,3] internal

You can access the data using either array indexing, or by retrieving the ASDF_NDArray and accessing the data property:

help, a['mydata','data']
arr = a['mydata']
help, arr.data

In both cases, IDL prints:

<Expression>    FLOAT     = Array[100, 50]

Tip: IDL does not read the data from the file until the data is accessed. Once the data has been accessed then the array is cached within the ASDF_NDArray and is immediately available for further manipulation.

Syntax


Result = ASDF_File(Key1, Value1, Key2, Value2, ... Keyn, Valuen)

Return Value


Returns a reference to a newly-created object.

Arguments


Keyn

Each Key argument can be a scalar string or number.

Valuen

Each Value argument can be a variable or expression of type ASDF_NDArray, YAML_Map, YAML_Sequence, YAML_Value, YAML_Alias, Hash, List, or a regular IDL array or scalar.

Note: If you pass in a regular IDL array, the array will be automatically stored inside a new ASDF_NDArray object within the ASDF_File. The original data will be unchanged.

Note: If you pass in a container (such as a YAML_Map/Sequence, or a Hash or List), then any IDL arrays within the container will be automatically converted to ASDF_NDArray objects. This will modify the original container.

Keywords


None

Properties


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

COMMENTS

Set this property to a string or string array containing the global comments for this stream. By default, this property is automatically set to the standard ASDF header comments and should not normally be changed:

IDL> a = ASDF_File()
IDL> a.comments
#ASDF 1.0.0
#ASDF_STANDARD 1.5.0
%YAML 1.1

GLOBAL_TAGS

Set this property to a string or string array containing the global %TAG values for this stream. By default, this property is automatically set to the standard ASDF tag and should not normally be changed:

IDL> a = ASDF_File()
IDL> print, a.global_tags
! tag:stsci.edu:asdf/

Note: You can have a maximum of four global tags.

TAG

Set this property to a string containing the local tag value for this stream. By default, this property is automatically set to the standard ASDF tag and should not normally be changed:

IDL> a = ASDF_File()
IDL> print, a.tag
!core/asdf-1.1.0

Methods and Additional Information

See YAML_Stream.

Variable Information


HELP

The HELP procedure provides general information:

IDL> stream = ASDF_File('mydata', findgen(100,50))
IDL> help, stream
STREAM          ASDF_FILE  <ID=3  NELEMENTS=3>  TAG='!core/asdf-1.1.0' GLOBAL_TAGS=1

PRINT and Implied Print

The PRINT procedure and Implied Print serialize the output in YAML format. Using the stream from above:

IDL> print, stream
IDL> stream

In both cases IDL prints:

#ASDF 1.0.0
#ASDF_STANDARD 1.5.0
%YAML 1.1
%TAG ! tag:stsci.edu:asdf/
--- !core/asdf-1.1.0
asdf_library: !core/software-1.0.0 {author: The ASDF Developers,homepage: 'http://github.com/asdf-format/asdf',name: asdf,version: 2.14.3}
history:
  extensions:
    - !core/extension_metadata-1.0.0
      extension_class: asdf.extension.BuiltinExtension
      software: !core/software-1.0.0 {name: asdf,version: 2.14.3}
mydata: !core/ndarray-1.0.0
  shape: [50,100]
  byteorder: little
  datatype: float32
  source: 0

Note: While this is a valid ASDF header, it is missing the actual data block. To output a full ASDF file, use ASDF_WRITE.

Version History


8.9

Introduced

See Also


ASDF_NDARRAY, ASDF_PARSE, ASDF_WRITE