Source code: ana2fits.pro

Description

This procedure saves the content of one or more ANA structures into one FITS file. The FITS file will contain up to 6 extensiona per ANA, where the first contains the results, and the fit components as header keywords. The resulting FITS file can be converted into one or more ANA structures with the procedure FITS2ANA.

It is possible to call this procedure multiple times with the same filepath_out, if in these cases the EXTENSION keyword is set, the windows will be appended to the existing FITS file. However, one needs to MAKE SURE THAT THE HEADER KEYWORD "NWIN" IS CORRECTLY SET. See description of n_windows for more details.

The structure and keywords will be the same as a SPICE level 3 FITS file except that it won't have any of the level 2 keywords.

Syntax

ana2fits, ana, filepath_out=filepath_out, TYPE_XDIM1=TYPE_XDIM1 [, data_id=data_id] [n_windows=n_windows] [, winno=winno]
  [, EXT_DATA_PATH=EXT_DATA_PATH]
  [, /IS_EXTENSION] [, LEVEL=LEVEL] [, VERSION=VERSION] [, CREATOR=CREATOR]
  [, PROC_STEPS=PROC_STEPS] [, PROJ_KEYWORDS=PROJ_KEYWORDS]
  [, XDIM1=XDIM1] [, INPUT_DATA=INPUT_DATA] [, FIT=FIT]
  [, RESULT=RESULT] [, RESIDUAL=RESIDUAL] [, WEIGHTS=WEIGHTS] [, INCLUDE=INCLUDE]
  [, CONST=CONST] [, FILENAME_ANA=FILENAME_ANA] [, DATASOURCE=DATASOURCE]
  [, DEFINITION=DEFINITION] [, MISSING=MISSING] [, LABEL=LABEL] [, HISTORY=HISTORY]
  [, PROGENITOR_DATA=PROGENITOR_DATA] [, HEADER_INPUT_DATA=HEADER_INPUT_DATA]
  [, /SAVE_XDIM1] [, /NO_SAVE_DATA] [, /PRINT_HEADERS]
  [, /SAVE_NOT]
  [, headers_results=headers_results] [, headers_data=headers_data]
  [, headers_xdim1=headers_xdim1] [, headers_weights=headers_weights]
  [, headers_include=headers_include] [, headers_constants=headers_constants]

OUTPUTS:

This procedure saves one or more ANA structures as FITS files.

Arguments

ana

The name and path of an ANA file or an ANA object. If this is not provided, then all of the optional inputs must be provided. If more than one ANA should be saved into one FITS file, then 'ana' must be provided as an array of either file paths or objects.

filepath_out

Full path and filename of the resulting FITS file.

TYPE_XDIM1

CTYPE of the absorbed dimension (e.g. 'WAVE'). A string array, or a scalar, in which case the same value will be used for all windows.

Keywords

IS_EXTENSION

If set, then the first ANA's result array will be an extension, i.e. this should be set if the FITS file already exists and data should be appended. If not set, the first ANA's result array will be the primary header.

SAVE_XDIM1

If set, then the XDIM1 cube will be saved into the FITS file. Default is not to save it. This cube can be recalculated using the WCS parameters given either in HEADER_INPUT_DATA. This keyword can also be an array of zeros and ones, setting/unsetting this feature separately for each window.

NO_SAVE_DATA

If set, then the data cube is not saved, only the header. It is then assumed, that HEADER_INPUT_DATA contains a link to the data. This is the same as not providing INPUT_DATA nor PROGENITOR_DATA. This keyword can also be an array of zeros and ones, setting/unsetting this feature separately for each window.

PRINT_HEADERS

If set, then all headers created will be printed to the terminal.

SAVE_NOT

If set, then the FITS file will not be saved. The optional outputs are created though.

Optional Inputs

n_windows

Total number of windows that will be included in this FITS file. By default, this will be the number of 'ana' structures provided, or 1 in case ana is not provided. But if you call this procedure mutliple times with the same filepath_out and EXTENSION keyword set, the procedure can not know what the final total number of windows will be, and thus the header keyword 'NWIN' in the result extension will have the wrong number. This will cause problems when reading the FITS file with FITS2ANA. It is therefore highly recommended to provide this number, when it is planned to add windows to the FITS file in different sessions.

winno

Window number (starting at 0) of the first 'ana' provided within this study in this FITS file. Default is zero. If you call this procedure mutliple times with the same filepath_out and EXTENSION keyword set, you can define here what the index of the currently provided first 'ana' should be. This will be set in the header keyword 'WINNO' in the result extension. A wrong number in this keyword won't create any problems when reading the FITS file with FITS2ANA.

HEADER_INPUT_DATA

A pointer array or string array, containing the headers of the data extensions as string arrays. One string array per ANA provided. Can be a string array, if only one ANA is provided. This is used to describe the data. WCS parameters should correspond with INPUT_DATA, or with PROGENITOR_DATA respectively.

PROGENITOR_DATA

A pointer array of Data Arrays or a data array. Up to 7-dimensional. Absorbed dimensions (e.g. spectra) does not have to be along the first dimension. If these data arrays are provided, they will be saved into the XDIM1 extensions instead of INPUT_DATA. One data array per ANA provided. Can be a data array, if only one ANA is provided.

data_id

A string vector of same length as 'ana', or if 'ana' is not provided scalar string. These strings are used to identify the data, i.e. they will be used in the extension names of the FITS file. Each dataset will get 7 extensions, which all have the same ID, but the extension name will be 'data_id'+' '+extension_type (='results', 'data', 'lambda', 'residuals', 'weights', 'includes', 'constants'). Default is the dataset numbers.

EXT_DATA_PATH

A string array or a string. This contains the relative path to the external extension, which contains the data cube. If this is provided the data is not saved in the new FITS file, but the header is. The header keyword DATAEXT in the headers will get EXT_DATA_PATH as a prefix to point to the external extension. See also Appendix VII aobut External Extensions in https://arxiv.org/abs/2011.12139

LEVEL

Number or string. The data level. If not provided this keyword will not be in the header.

VERSION

Number or string. The version number of this file. If not provided this keyword will not be in the header.

CREATOR

String. The name of the creator of this FITS file. If not provided this keyword will not be in the header.

PROJ_KEYWORDS

A list or array of hashes with entries ('name',xxx1, 'value',xxx2, 'comment',xxx3} where, xxx2 can be a string or a number. These are additional project-related keywords that should be added to the header. This can also be a pointer array, if each window should get their own sets of keywords. It must then be of the same size as the RESULT pointer array or the ANA array.

PROC_STEPS

A list, each element stands for one processing step, i.e. gets a new number. Each processing step consists of an array of hashes with entries ('name',xxx1, 'value',xxx2, 'comment',xxx3} where, xxx2 can be a string or a number.
The name can be any of the following:
PRSTEP|PRPROC|PRPVER|PRMODE|PRPARA|PRREF|PRLOG|PRENV|PRVER|PRHSH|PRBRA|PRLIB
PRSTEP should be included. The name and the comment will get the processing step number added. This can also be a pointer array, if each window should get their own sets of keywords. It must then be of the same size as the RESULT pointer array or the ANA array.

OPTIONAL INPUTS/OUTPUTS:

• All of the following optional inputs MUST BE PROVIDED if 'ANA' is not provided. If 'ANA' is provided, they will be overwritten and can be used as OPTIONAL OUTPUT.

RESULT

The array to contain the result parameter values (and the Chi^2) values. This may also be a pointer array, if more than one window should be saved at a time.

FIT

The component fit structure This may also be a pointer array, if more than one window should be saved at a time. It must then be of the same size as the RESULT pointer array.

• All of the following optional inputs MAY BE PROVIDED if 'ANA' is not provided. If not provided, it is assumed they contain only default values. If 'ANA' is provided, they will be overwritten and can be used as OPTIONAL OUTPUT.

HISTORY

A string array.

INPUT_DATA

Data Array. Up to 7-dimensional data array, with absorbed dimension (e.g. spectra) along the first dimension. This is ignored if PROGENITOR_DATA is provided. This may also be a pointer array, if more than one window should be saved at a time. It must then be of the same size as the RESULT pointer array.

XDIM1

Array of same size as the input data to xcfit_block. It contains the values of the absorbed dimension for each point (e.g wavelength). This may also be a pointer array, if more than one window should be saved at a time. It must then be of the same size as the RESULT pointer array.in the data array.

WEIGHTS

Weights to use in the fitting process. This may also be a pointer array, if more than one window should be saved at a time. It must then be of the same size as the RESULT pointer array.

INCLUDE

Array to keep the INCLUDE status of each component at each point. This may also be a pointer array, if more than one window should be saved at a time. It must then be of the same size as the RESULT pointer array.

CONST

Array to keep the CONST status of each parameter at each point. This may also be a pointer array, if more than one window should be saved at a time. It must then be of the same size as the RESULT pointer array.

• The following optional inputs WILL BE IGNORED. If 'ANA' is provided, they will be overwritten and can be used as OPTIONAL OUTPUT.

RESIDUAL

Array to contain the residual. Same size as INPUT_DATA, this will be ignored and not saved into the FITS file.

FILENAME_ANA

The filename of the ANA-file.

DATASOURCE

A string.

DEFINITION

A string.

MISSING

The MISSING value, used to flag missing data points, and parameter values at points where the fit has been declared as "FAILED". This is assumed to be NAN.

LABEL

A string.

OPTIONAL OUTPUTS:

headers_results

A pointer array, containing the headers of the results extensions as string arrays. One string array per ANA provided.

headers_data

A pointer array, containing the headers of the data extensions as string arrays. One string array per ANA provided. May be empty strings if this extension was not saved.

headers_xdim1

A pointer array, containing the headers of the xdim1 extensions as string arrays. One string array per ANA provided. May be empty strings if this extension was not saved.

headers_weights

A pointer array, containing the headers of the weights extensions as string arrays. One string array per ANA provided. May be empty strings if this extension was not saved.

headers_include

A pointer array, containing the headers of the include extensions as string arrays. One string array per ANA provided. May be empty strings if this extension was not saved.

headers_constants

A pointer array, containing the headers of the constants extensions as string arrays. One string array per ANA provided. May be empty strings if this extension was not saved.