Source code: ana2fits.pro

Description

This procedure saves the content of one or more ANA structures into a level P FITS file. The FITS file will contain up to 6 extensions 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.

The input can be either an ANA structure (see also mk_analysis() documentation), or an array of such structures, or the input can be provided as separate data cubes, see this paragraph for more details.

It is strongly recommended that the input HEADER_INPUT_DATA is provided. This is needed to get the WCS parameters of the original data. The WCS is required to recreate the XDIM1 cube, which contains the values of the absorbed dimension (i.e. the wavelength) for each pixel of the data cube. This, in turn, is required for the CFIT routines. Without this cube, any adjustments to the fit components or further fitting won't be possible.

By default, the original data cube is not saved into the level P FITS file, but referenced to as an external extension. See also Solarnet recommendations. The keyword DATA_EXT_PATH must be provided if the data is not saved in this FITS file. This saves disk space, but makes the user of the level P FITS file dependent on having the original data available. The data cube can be saved into the FITS file by setting the keyword SAVE_DATA.

It is possible to call this procedure multiple times with the same filepath_out. The windows will then be appended to the existing FITS file, if the keyword IS_EXTENSION is set, otherwise the FITS file will be overwritten. However, one needs to MAKE SURE THAT THE HEADER KEYWORDS "N_WINDOWS" AND "WINNO" ARE CORRECTLY SET. See description of N_WINDOWS and WINNO for more details.

The structure and keywords will be the same as a SPICE level 3 FITS file.

Syntax

ana2fits, ANA, FILEPATH_OUT=FILEPATH_OUT  
  [, n_windows=n_windows] [, winno=winno]  
  [, data_id=data_id] [, XTYPE1=XTYPE1] [, XDIMEN1=XDIMEN1]  
  [, DATA_EXT_PATH=DATA_EXT_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_RESIDUALS] [, /SAVE_DATA] [, /PRINT_HEADERS]
  [, /SAVE_NOT]
  [, headers_results=headers_results] [, headers_data=headers_data]
  [, headers_weights=headers_weights] [, headers_include=headers_include] 
  [, headers_constants=headers_constants] [, headers_residuals=headers_residuals]

OUTPUTS:

This procedure saves one or more ANA structures into one FITS file.

Arguments

ANA

An ANA object. (see also mk_analysis() documentation) If this is not provided, then at the least RESULTS and FIT must be provided. If more than one ANA should be saved into one FITS file, then 'ana' must be provided as an array of objects.

FILEPATH_OUT

Full path and filename of the resulting FITS file.

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_DATA

If set, the data cube is saved into the data extension. The default is not to save it and to use the external extension mechanism instead. See the description of DATA_EXT_PATH for more details. This keyword can also be an array of zeros and ones, setting/unsetting this feature separately for each window.

SAVE_RESIDUALS

If set, the residuals will be saved into the FITS file. The default is not to save it. This cube can be recalculated using the original data and the fit parameter. To save the residuals can be useful in case the original data may not be available when reading the file. This keyword can also be an array of zeros and ones, setting/unsetting this feature separately for each window.

PRINT_HEADERS

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

SAVE_NOT

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

Semi-Optional Inputs

HEADER_INPUT_DATA

Strongly recommended.
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. These parameters will be used to create the WCS structure of the data cube and the WCS keywords in the header. They will also be used to recreate the XDIM1 cube. This header will be saved into the data extension even if the data is not saved.

DATA_EXT_PATH

Required if SAVE_DATA is NOT set, otherwise recommended.
A string array or a string. This contains the relative path to and the name of the file that contains the original data cube from which the P-level data was calculated. The extension name of the original data cube MUST NOT be included. This name will be taken from DATA_ID. The path and extension name will be used in the header keyword PARENTXT. In case the data cube is not saved into the FITS file, but linked to an external extension, the header keyword DATAEXT in the headers will point to the external extension. See also Appendix VII about External Extensions in https://solarnet-metadata.readthedocs.io/en/latest/generated/appendix-7.html

XTYPE1

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

XDIMEN1

The dimension number(s), counting left to right starting with 1, of dimensions that was absorbed/removed during the fitting process (for SPICE Level 3 P files XDIMEN1=3). An array of integers, or a scalar, in which case the same value will be used for all windows. The default is the dimension number that corresponds to XTYPE1 found in HEADER_INPUT_DATA.

n_windows

Total number of windows that will be included in this FITS file. By default, this will be the number of 'ana' structures or the number of RESULT pointers provided, or 1 in case RESULT is an array.
BUT if you call this procedure multiple times with the same FILEPATH_OUT and IS_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 may have the wrong number. This will NOT cause any problems when reading the FITS file with FITS2ANA. But you may want to have the correct number in the header.

WINNO

Window number (starting at 0) of the first 'ana' provided within this study in this FITS file. If you call this procedure multiple times with the same FILEPATH_OUT and IS_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. But you may want to have the correct number in the header. The default is the dataset indices.

Optional Inputs

DATA_ID

A string vector of the same length as 'ana', or if 'ana' is not provided, the same number of windows provided. 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 up to 6 extensions, which all have the same ID, but the extension name will be 'data_id'+' '+extension_type (='results', 'data', 'xdim1', 'weights', 'includes', 'constants'). The default is the value of the keyword 'EXTNAME' from HEADER_INPUT_DATA. If this header is provided, then the data extension will have this EXTNAME (without 'data') as its extension name. If this is not provided, then the default is the window index.

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 DATA extensions instead of INPUT_DATA if the keyword SAVE_DATA is set. One data array per ANA provided. Can be a data array if only one ANA is provided.

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.

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.

RESIDUAL

Array to contain the residual. Same size as INPUT_DATA. 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.

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 can be calculated by using the WCS structure of the data cube and is thus not saved in 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_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.

headers_residuals

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