Документ взят из кэша поисковой машины. Адрес оригинального документа : http://xmm.vilspa.esa.es/sas/6.0.0/doc/cifbuild.ps.gz Дата изменения: Thu Mar 18 22:58:02 2004 Дата индексирования: Tue Oct 2 04:06:35 2012 Кодировка: Поисковые слова: optical telescope

XMM-Newton Science Analysis System Page: 1
cifbuild
March 18, 2004
Abstract
Construct CCF Calibration or Master Index Files.
1 Instruments/Modes
Instrument Mode
2 Use
pipeline processing yes
interactive analysis yes
3 Description
The XMM-Newton calibration data base is a collection of algorithms ( described in the Calibration
Handbook [1]), and Current Calibration File (CCF) constituents [2]. The latter contain the numerical
values driving the calibration algorithms.
The SAS tasks access the calibration data base through the Calibration Access Layer (CAL, cal). The
CAL is pointed to the correct set of CCF constituents through a CCF Index File (CIF).
cifbuild is used to generate the CIF appropriate to a given observation and analysis date.
Details on how to use a CIF in conjunction with the SAS, and what environment variables must be used,
can be found in the CAL documentation (see documentation of cal).
3.1 Where to nd the CCF constituents
Information about the CCF constituents and where to download them can be found on the CCF web
pages.
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 2
3.2 Generation of the Calibration Index File
As described in detail below 3.4 (see also [2]) the list of calibration datasets comprising a CIF is ruled by
two dates: the observation date and the analysis date.
By default cifbuild reads the observation date from the Observation Data File (ODF) pointed to via the
SAS ODF environment variable.
If an ODF is not available the observation date can be specied with the parameters withobservationdate
and observationdate.
The analysis date is given with the parameter analysisdate, and it defaults to now. Note that the
analysis date can be any date (in the past or in the future): it is used to retrieve the CCF constituents
applicable at the specied point in time.
For instance, to generate the CIF applicable on 2010-01-01 say analysisdate=2010-01-01. What CCF
constituents would one have used on 2005-01-01? Use analysisdate=2005-01-01.
The analysis and observation dates used in the creation of the CIF are recorded in the two block attributes
OBSVDATE and ANALDATE respectively. (See 7.)
Note that it is possible to use an analysis date earlier than the observation date. This is agged with a
warning, and may lead to an inconsistent calibration.
3.2.1 Using the CCF constituents
cifbuild can build a CIF by examining the CCF constituents found in a number of directories specied
by the user. The list of directories (use the character : as a separator) should be specied through the
environment variable SAS CCFPATH. Alternatively, the same information can be specied on the command
line (see the parameters withccfpath and ccfpath).
3.2.1.1 Advanced usage Normally a valid CCF constituent will have the CATEGORY attribute set to
XMMCCF. However, it is possible to instruct cifbuild to accept constituents with a dierent category via
the parameter category. For instance, the SOC distributes CCF constituents tuned to the output of the
science simulator. These datasets have the CATEGORY attribute set to SCISIMCCF.
The category can also be ignored altogether with the parameter ignorecategory.
If the parameter append is true, then cifbuild appends to the CIF set pointed to by calindexset any
other CCF constituent that is not already in that CIF. With this mechanism it is possible to build a CIF
incrementally, giving priority to a certain category of constituents (see example 8).
3.2.2 Using a Master Index File
cifbuild can also be used to generate a CIF based on the contents of the Master Index File (MIF). The
MIF contains the list of all CCF constituents released from the start of the mission until the date specied
in the SUBDATE attribute. The generation of a CIF in this case requires that the user specify the MIF to
be used with the parameters withmasterindexset and masterindexset.
The latest version of the MIF is available from the CCF area at the XMM-Newton Science Operation
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 3
Centre.
3.2.3 Examples
In reference to the examples below, see also the CAL documentation (see documentation of cal) on how
to specify a CIF.
Note: in the following examples we use the Bourne shell syntax to specify environment variables. C shell
users should convert that to setenv VARIABLE value.
1. This are the recommended steps for people who have access to a local collection of CCF
constituents:
(a) export SAS ODF=/path/to/odf dir 1
(b) export SAS CCFPATH=/path/to/ccfstore1:/path/to/ccfstore2
(c) cifbuild
This creates the le ccf.cif (the default value of calindexset) in the current directory.
The CCF constituents are searched among the les in the two directories specied in the
environment variable SAS CCFPATH. The observation date is taken from the active ODF as
indicated by the variable SAS ODF. The analysis date defaults to now (the default value of
analysisdate).
If the usecanonicalname had been set to true, the name of the CIF would have been of
the form rrrr ppppppooll.cif, where rrrr is the revolution number, and ppppppooll is
the observation identier.
2. This is the recommended mode of operation for those who want to generate a CIF from a
MIF. It is not necessary to have access to any of the CCF constituents.
cifbuild --withmasterindexset=yes --masterindexset=XMM CALINDEX 0123.CCF
The CIF is built from the list of CCF constituents specied in XMM CALINDEX 0123.CCF.
3. cifbuild --withccfpath=yes
--ccfpath="/path/to/ccfstore1/:/path/to/ccfstore2"
--fullpath=yes
This creates the le ccf.cif (the default value of calindexset) in the current directory.
The CCF constituents are searched among the les in the two directories specied with
ccfpath. The observation date is taken from the active ODF as indicated by the variable
SAS ODF. The analysis date defaults to now (the default value of analysisdate). The CIF
contains the full path to the CCF constituents.
To use the CIF set the environemnt variable SAS CCF to be ccf.cif. If you set SAS CCF to
be the absolute path to the CIF, then the latter can be used from any other directory.
4. cifbuild --withccfpath=yes --ccfpath=/path/to/ccfstore
The CIF ccf.cif contains the base name of the CCF constituents found in /path/to/ccfstore.
To use the CIF place it in /path/to/ccfstore and set the environemnt variable SAS CCF
to be /path/to/ccfstore.
5. cifbuild --withccfpath=yes --ccfpath=/path/to/ccfstore
--calindexset=/path/to/ccfstore/myobservation.cif
As in 4, but now the CIF is called myobservation.cifand is written directly to the directory
/path/to/ccfstore.
1 If you generated a summary le with the task odngest, then you can also say export SAS ODF=/path/to/summary file.
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 4
To use the CIF set the environment variable SAS CCF to be /path/to/ccfstore/myobservation.cif.
6. cifbuild --withccfpath=yes
--ccfpath="/path/to/ccfstore1/:/path/to/ccfstore2"
--withobservationdate=yes --observationdate="2000-01-13T00:00:00"
--fullpath=yes
As in 3, but now the observation date is specied to be Midnight January 13, 2000.
7. cifbuild --withccfpath=yes --ccfpath="/path/to/ccfstore1/:/path/to/ccfstore2"
--analysisdate="2000-03-19T00:00:00" --fullpath=yes
As in 3, but the observation date is taken from the active ODF, but the CIF is built as if
the analysis was being performed on March 19, 2000.
8. cifbuild --calindexset=ccf.cif --category=SCISIMCCF --ccfpath=/path/to/ccfstore/
--withccfpath=yes
cifbuild --calindexset=ccf.cif --withccfpath=yes --ccfpath=/path/to/ccfstore/
--append=yes
This builds a CIF that contains constituents of category SCISIMCCF if they exist, other-
wise constituents of category XMMCCF are used.
3.3 Generation of a Master Index File
This section is not of interest for the general user. There is no reason to do this outside the XMM-Newton
Science Operations Centre.
By setting the parameter masterindex to yes cifbuild can be instructed to generate a MIF.
In this mode of operations the command line value of fullpath is ignored.
All CCF constituents found in the directories specied via ccfpath (or SAS CCFPATH) are listed in the
output calibration index set (calindexset).
3.4 Excerpts from the Current calibration File Interface Control Document
This section is taken verbatim from [2].
3.5 File Naming Convention
The constituents of the current calibration le are named as follows:
scope calname issue.ccf
where:
scope indicates the scope of the calibration le (at most 5 characters long). The list of scope
identiers is given in table 1.
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 5
calname is the calibration data type identier (at most 17 characters long).
issue is the le issue number (integer  0 and  9999, zero padded).
File names are not case sensitive. In this document they are type set with uppper and lower case letters
for readability.
xmm general les or les shared by more than one instrument
om Optical Monitor les
xrt1, xrt2, xrt3 X-ray Telescope les
emos1, emos2 European Photon Imaging Camera MOS les
epn European Photon Imaging Camera PN les
rgs1, rgs2 Re ection Grating Spectrometer les
erm EPIC Radiation Monitor les
Table 1: Allowed scope identiers
3.6 Membership of the Current Calibration File
Here we address the issue of how to determine what calibration les make up the current calibration le
for a given observation time.
Each calibration le has a validity start date and a validity end date. These are indicated by the FITS
keywords VALDATE and EVALDATE. A missing EVALDATE is taken to mean no end of validity.
Given the naming convention above, a calibration le can be labeled with a quadruplet of the form
fFname; Issue; T start ; T end g, where Fname  scope calname, and T end is optional.
New issues of a calibration le can enter the archive with any T start , any T end , and increasing issue
numbers.
In the simplest case (no end of validity date), a new version of the calibration le | call it fFname; Issue 0 ; T 0
start g,
will have T start < T 0
start and Issue < Issue 0 (gure 1).
A more complex situation is illustrated in gure 2. Here new versions are introduced to improve on past
calibrations.
In gure 3 we show an example where a CCF constituent has an end of validity date. In this case
at the time T the situation is the same as shown in gure 2, whereas at the time T1 the constituent
xmm ExampleTwo 005.ccf is no longer applicable.
Within this scheme, at any time T the applicable issue of the calibration le Fname is obtained by
selecting among all les fFname; Issue; T start  T ; T end  Tg the one with the higher issue number.
Should it become necessary, a new Fname can be introduced in the archive, as illustrated in gure 4.
With this scheme the number of constituents in the current calibration le is not xed, and can be
determined only when the time T is specied.
3.7 See also
Other SAS tasks to manipulate calibration index les are:
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 6
Calibration
Files
time
T
1 2 3
1 2
issue number
xmm_ExampleTwo
xmm_ExampleOne
Figure 1: Current calibration le with two les. At the time T the current calibration le consists of
xmm ExampleOne 0001.ccf and xmm ExampleTwo 0002.ccf
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 7
Calibration
Files
time
T
5 6
1 2 3
1 2
xmm_ExampleTwo
xmm_ExampleOne
Figure 2: Current calibration le with two les: update. At the time T the current calibration le consists
of xmm ExampleOne 0001.ccf and xmm ExampleTwo 0005.ccf
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 8
Calibration
Files
time
T
5
1 2 3
ccf-xmm-ExampleTwo
1 2 ccf-xmm-ExampleOne
T1
Figure 3: Current calibration le with two les: update. At the time T the current calibration le consists
of xmm ExampleOne 0001.ccf and xmm ExampleTwo 0005.ccf. At the time T1 the current calibration
le consists of xmm ExampleOne 0001.ccf and xmm ExampleTwo 0003.ccf.
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 9
Calibration
Files
time
T T1
1 2 3
1 2 3
1 2
xmm_ExampleThree
xmm_ExampleTwo
xmm_ExampleOne
Figure 4: Current calibration le with three les. At the time T1 the current calibration le consists of
xmm ExampleOne 0002.ccf and xmm ExampleTwo 0003.ccf and xmm ExampleThree 0002.ccf
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 10
 cifdi : list the dierence between two CIFs.
 cifremove: remove CCF constituents from a CIF.
 cinsert: insert CCf constituents into a CIF.
4 Parameters
This section documents the parameters recognized by this task (if any).
Parameter Mand Type Default Constraints
calindexset no e ccf.cif
Name of the output calibration index set.
withccfpath no b no
Use the directories listed in ccfpath? Set to no means use SAS CCFPATH.
usecanonicalname no b no yes j no
Autogenerate the CIF name based on the ODF identier? If set to yes, if the observation date is
read from an ODF, and if withmasterindex is set to no, the name of the CIF will be of the form
rrrr ppppppooll.cif, where rrrr is the revolution number, and ppppppooll is the observation identi-
er.
ccfpath no s .
Colon-separated list of directories where CCF constituents are to be looked for.
recurse no b no
Recursively look for CCF constituents in any subdirectory found in ccfpath or in SAS CCFPATH?
leglob no s *.ccfj*.CCF
File name glob patterns to match CCF constituents. The delimiter is j.
fullpath no b no
Write in the calibration index set the full path names of the CCF constituents? The valu of this param-
eter is ignored if withmasterindexset is set to true.
withobservationdate no b no
Use the user-specied observation date? Otherwise will read the data from the active ODF (environment
variable SAS ODF).
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 11
observationdate no w now
Date when the observation was made.
analysisdate no w now
Date when the analysis is performed.
category no s XMMCCFjSCISIMCCF
Category of constituents to look for. Use * for any category.
ignorecategory no b no
Pay no attention to the CATEGORY attribute?
masterindex no b no
Create a master calibration index set (aka MIF)?
withmasterindexset no no b
Make use of the master index set (aka MIF) instead of looking directly at the CCF constituents?
masterindexset no ccf.mif e
Name of the MIF to be used to evaluate the calibration index set (aka CIF).
append no no b
Append CCF constituents to an existing calindexset?
5 Errors
This section documents warnings and errors generated by this task (if any). Note that warnings and
errors can also be generated in the SAS infrastructure libraries, in which case they would not be docu-
mented here. Refer to the index of all errors and warnings available in the HTML version of the SAS
documentation.
NoMatchingCcfConstituents (warning)
cifbuild did not nd any CCF constituent matching the specied selection criteria.
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 12
corrective action: None.
PossibleInconsistentCalibration (warning)
The user specied analysisdate < observationdate. The resulting Calibration Index
File may contain a set of CCF constituents that are not consistent and lead to the wrong
calibration being applied.
corrective action: None.
MissingAttribute (warning)
cifbuild expects to nd a number of attributes in each CCF constituent. One or more of
these attributes were not found.
corrective action: If a critical attribute is missing the constituent may be discarded at a
later stage.
InvalidCcfConstituent (warning)
cifbuild could not recognize a dataset as a valid CCF constituent.
corrective action: The dataset is ignroed.
TableNotFound (error)
cifbuild was asked to open a calibration index le, but the required table was not found.
NoCcfPath (error)
The environment variable SAS CCFPATH is not set, and no CCF search path was given on
the command line. See withccfpath.
6 Input Files
1. Calibration Master Index File: this is available in the CCF. Its format is the same as the
CIF (see below).
2. CCF constituents [2].
7 Output Files
1. Calibration index le (either a CIF or a MIF)
A binary table CALINDEX with the following columns:
 TELESCOP, character(4): copied from the CCF constituent
 SCOPE, character(6): calibration scope
 TYPEID, character(32): calibration type
 ISSUE, integer: issue number
 VALDATE, character(19): start of validity date (yyyy:dd:mmZhh:mm:ss)
 VALDATE-END, character(19): end of validity date (yyyy:dd:mmZhh:mm:ss). An empty
value means that the constituent has no end of validity date.
 FNAME, character(256): name of the constituent
 DATE, character(19): creation date (yyyy:dd:mmZhh:mm:ss)
 FSIZE, integer: constituent size in bytes
 SUBDATE, character(19): submission date (yyyy:dd:mmZhh:mm:ss)
 EXTSEQU, character(32): extension sequence
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 13
 EXTSEQID, character(256): extension sequence identiers
 MD5, character(32): MD5 signature of the constituent
 CREATOR, character(64): copied from the CCF constituent
Two attributes are used to record the dates used in the creation of the CIF:
 OBSVDATE: the observation date.
 ANALDATE: the analysis date.
8 Algorithm
if(not withmasterindexfile) {
foreach(directory is SAS_CCFPATH or in ccfpath) {
foreach(file matching glob pattern) {
if(is_a_ccf_file) {
extract CCF attributes
add to list organized by scope-type
}
}
foreach(scope-type) {
select constituent with:
VALDATE <= observationdate
SUBDATE <= analysisdate
EVALDATE >= observationdate
highest ISSUE
write selected constituet to CIF
}
} else { // use masterindexfile
foreach(scope-type in MIF) {
select constituent with:
VALDATE <= observationdate
SUBDATE <= analysisdate
highest ISSUE
}
}
9 Comments
References
[1] Christian Erd, Phillipe Gondoin, David Lumb, Rudi Much, Uwe Lammers, and Giuseppe Vacanti.
Calibration Access and Data Handbook. Technical Report XMM-PS-GM-20, ESA/SSD, Jan 14 2000.
Found at the URL: http://xmm.vilspa.esa.es/docs/documents/CAL-MAN-0001-2-1.ps.gz.
[2] ESA. Interface control document for the XMM current calibration le. Technical Report XMM-GEN-
ICD-0005, ESA/SSD, Dec 2001.
xmmsas 20040318 1831-6.0.0