Data related procedures¶
The commands in this section are all related to the data structures within SPEX. They deal with spectral data and responses, simulation of data, etc.
Data¶
Loading spectral data and responses in SPEX is done with the data command. Data can be added
by loading a .res and .spo file that contain the response and spectral information for an
instrument. The Fortran API procedure is:
call spex%data(resfile,spofile,ier)
where resfile is the response file, spofile the spectrum file, and ier the output
error condition.
module subroutine spex_io_data(this,resname,sponame,ier)
class(sapi), intent(inout) :: this
character*(*), intent(in) :: resname !! Input .res file name
character*(*), intent(in) :: sponame !! Input .spo file name
integer, intent(out) :: ier !! Error status
end subroutine
Note that this command needs the full filename (and if necessary the path to the file) including the extension. This is the only difference with the SPEX syntax. Example:
call spex%data('xifu.res','xifu.spo',ier)
Data delete¶
Deleting a loaded spectrum and response is done in SPEX with the data delete instrument #i
command. In the Fortran API, the procedure is:
call spex%data_del(ins,ier)
where ins is the instrument number to be deleted and ier the output error condition.
module subroutine spex_io_data_del(this, ins, status)
class(sapi), intent(inout) :: this
integer, intent(in) :: ins !! Instrument number
integer, intent(inout) :: status !! Error status
end subroutine
Example:
call spex%data_del(1,ier)
Data save¶
Simulated spectra can be saved as a .spo file. In SPEX, this is done using the
data save #i <spofile> command. In the Fortran API, the command is:
call spex%data_save(ins,sponame,overwrite,ier)
where ins is the instrument number of the data to be saved, spofile is the name of
the output .spo file. Again note that you should give the full file name, including the .spo
extension. The overwrite logical overwrites an existing file if true.
module subroutine spex_io_data_save_spo(this,ins,sponame,overwrite,status)
class(sapi), intent(inout) :: this
integer, intent(in) :: ins !! Instrument number
character*(*), intent(in) :: sponame !! Output spectrum file name (.spo)
logical, intent(in) :: overwrite !! Overwrite existing file (true/false)
integer, intent(inout) :: status !! Error status
end subroutine
For example:
call spex%data_save(1,'sim.spo',.true.,ier)
Binning and data selection¶
Unlike some other fitting packages, SPEX rebins the spectra within the program. The easiest binning
method is to just rebin with a certain integer factor. This is the bin command in SPEX. In
addition, SPEX contains a binning method based on the bin statistics (vbin) and an optimal
binning algorithm (obin) which takes the instrument resolution into account.
Binning with factor
Binning with an integer factor is done with the bin command:
call spex%bin(in,ir,r1reb,r2reb,freb,unit,status)
The in parameter is the instrument number, the ir parameter the
region number, r1reb and r2reb are the lower and upper boundary of the
energy interval to be rebinned, freb is the rebinning factor, unit
the physical unit of the energy range, and status is the output error condition.
module subroutine spex_io_bin(this,in,ir,r1reb,r2reb,freb,unit,status)
class(sapi), intent(inout) :: this
integer, intent(in) :: in !! Instrument number
integer, intent(in) :: ir !! Region number
real(dp), intent(in) :: r1reb !! Lower rebinning boundary
real(dp), intent(in) :: r2reb !! Upper rebinning boundary
integer, intent(in) :: freb !! Factor binning
character*(*), intent(in) :: unit !! Unit of provided boundaries
integer, intent(out) :: status !! Error status
end subroutine
In this example, we bin the spectrum with a factor of 5 between 0.3 and 10 keV:
call spex%bin(1,1,0.3,10.,5,'kev',status)
Variable binning
Variable binning is done with the vbin command:
call spex%vbin(in,ir,r1,r2,unit,ivarbin,snlim,status)
The in parameter is the instrument number, the ir parameter the
region number, r1 and r2 are the lower and upper boundary of the
energy interval to be rebinned, unit the physical unit of the energy range,
ivarbin is the minimum number of bins to be added, snlim is the
minimum signal to noise and status is the output error condition.
module subroutine spex_io_vbin(this,in,ir,r1,r2,unit,ivarbin,snlim,status)
class(sapi), intent(inout) :: this
integer, intent(in) :: in !! Instrument number
integer, intent(in) :: ir !! Region number
real(dp), intent(in) :: r1 !! Lower rebinning boundary
real(dp), intent(in) :: r2 !! Upper rebinning boundary
character*(*), intent(in) :: unit !! Unit of provided boundaries
integer, intent(in) :: ivarbin !! Minimum number of bins to be added
real(dp), intent(in) :: snlim !! Minimum S/N ratio to be achieved
integer, intent(out) :: status !! Error status
end subroutine
In this example, we bin the spectrum with a minimum factor of 3 and a minimum signal-to-noise ratio of 25 between 0.3 and 10 keV:
call spex%vbin(1,1,0.3,10.,3,25.,'kev',status)
Optimal binning
The optimal binning algorithm bins based on the instrument resolution and statistics:
call spex%obin(in,ir,r1reb,r2reb,unit,status)
The in parameter is the instrument number, the ir parameter the
region number, r1reb and r2reb are the lower and upper boundary of the
energy interval to be rebinned, unit the physical unit of the energy range,
and status is the output error condition.
module subroutine spex_io_obin(this,in,ir,r1reb,r2reb,unit,status)
class(sapi), intent(inout) :: this
integer, intent(in) :: in !! Instrument number
integer, intent(in) :: ir !! Region number
real(dp), intent(in) :: r1reb !! Lower rebinning boundary
real(dp), intent(in) :: r2reb !! Upper rebinning boundary
character*(*), intent(in) :: unit !! Unit of provided boundaries
integer, intent(out) :: status !! Error status
end subroutine
In this example, we optimally bin the spectrum between 0.3 and 10 keV:
call spex%obin(1,1,0.3,10.,'kev',status)
Data selection¶
Selecting data is done using the use and ignore commands. By default, the bin selection
in the .spo file is loaded, which should use all the good bins.
Use function
call spex%use(in,ir,r1,r2,unit,status)
The in parameter is the instrument number, the ir parameter the
region number, r1 and r2 are the lower and upper boundary of the
energy interval to be used, unit the physical unit of the energy range,
and status is the output error condition.
module subroutine spex_io_use(this,in,ir,r1,r2,unit,status)
class(sapi), intent(inout) :: this
integer, intent(in) :: in !! Instrument number
integer, intent(in) :: ir !! Region number
real(dp), intent(in) :: r1 !! Lower range boundary
real(dp), intent(in) :: r2 !! Upper range boundary
character*(*), intent(in) :: unit !! Unit of provided boundaries
integer, intent(out) :: status !! Status error
end subroutine
Example:
call spex%use(1,1,0.3,10.,'kev')
Ignore function
call spex%ignore(in,ir,r1,r2,unit,status)
The in parameter is the instrument number, the ir parameter the
region number, r1 and r2 are the lower and upper boundary of the
energy interval to be ignored, unit the physical unit of the energy range,
and status is the output error condition.
Example:
call spex%ignore(1,1,0.0,0.3,'kev')
call spex%ignore(1,1,10.,100.,'kev')
Systematic errors¶
If needed, the error bars on the source and background spectrum can be enlarged by the syserr
command:
call spex%syserr(in,ir,r1,r2,unit,serr,berr,status)
The in parameter is the instrument number, the ir parameter the
region number, r1 and r2 are the lower and upper boundary of the
energy interval to be changed, unit the physical unit of the energy range,
serr is the systematic error on the source to be added, berr is the
systematic error on the background, and status is the output error condition.
module subroutine spex_io_syserr(this,in,ir,r1,r2,unit,serr,berr,status)
class(sapi), intent(inout) :: this
integer, intent(in) :: in !! Instrument number
integer, intent(in) :: ir !! Region number
real(dp), intent(in) :: r1 !! Lower range boundary
real(dp), intent(in) :: r2 !! Upper range boundary
character*(*), intent(in) :: unit !! Unit of provided boundaries
real(dp), intent(in) :: serr !! Systematic error source spectrum
real(dp), intent(in) :: berr !! Systematic error background spectrum
integer, intent(out) :: status !! Error status
end subroutine
Example:
call spex%syserr(1,1,0.1,10.,'kev',0.1,0.1,status)
Warning
To use this function, you need to know what you are doing statistically. In many cases, this function would produce wrong results.
Other commands¶
Setting instrument normalisations¶
During spectral fitting, instrument normalisations can be set and freed to account for cross-calibration issues between instruments:
call spex%set_inst_norm(is,ir,norm,ier)
Where is is the instrument number, ir the region number,
norm the instrument normalisation, and ier the error code.
The Fortran interface:
module subroutine spex_io_set_inst_norm(this, is, ir, norm, ier)
class(sapi), intent(inout) :: this
integer, intent(in) :: is !instrument number
integer, intent(in) :: ir !region number
real, intent(in) :: norm !instrument normalisation
integer, intent(out) :: ier !error status
end subroutine
The normalisation can also be fixed or freed:
call spex%set_inst_free(is,ir,free,ier)
Where is is the instrument number, ir the region number,
free is a logical (.true. is free), and ier is the error code.
The Fortran interface:
module subroutine spex_io_set_inst_norm_free(this, is, ir, free, ier)
class(sapi), intent(inout) :: this
integer, intent(in) :: is !instrument number
integer, intent(in) :: ir !region number
logical, intent(in) :: free !instrument normalisation free=.true./frozen=.false.
integer, intent(out) :: ier !error status
end subroutine
Delete all instruments (reset)¶
Example:
call spex%reset_data()
The Fortran interface:
module subroutine spex_io_reset(this)
class(sapi), intent(inout) :: this
end subroutine