Jump to: Description · Example · Parameters · Bugs · See Also

AHELP for CIAO 4.17

mkosip

Synopsis

Generate an OSIP calibration file.

Syntax

mkosip  [osip_mode] [obspar] [p2resp_file] [fracresp_goal]
[order_bounds_table] [energy_grid] [ccdids] [high_limit_clip]
[low_limit_clip] [fracresp_high] [resample_factor]
[moments_full_distribution] [verbose] [n_threads]

Description

This tool generates CALDB files using an algorithm for order-sorting with the Chandra gratings used in conjunction with the ACIS detectors. The OSIP tabulates ENERG LO and ENERG HI vs ENERGY and the enclosed energy fraction within those limits, FRACRESP, for each detector element and location. These values are used by tg_resolve_events to assign events to orders by determining whether the CCD energy falls between the low and high limits and by mkgarf to apply the FRACRESP factor to the effective area for each position in the spectrum.

OSIP values are computed from the CCD response vs energy for every calibration cell of every CCD. The CCD response used is after all corrections (gain, CTI); it is effectively determined from response matrices (RMF) as computed by mkacisrmf. There are approximately 1000 calibration cells per CCD (nominally on a 32x32 pixel grid), and 6 CCDs in the ACIS-S array. Computation for ACIS-I (4 CCDs) is lower priority, but there are some observations using HETG or LETG with ACIS-I. There are also multiple epochs of distinct CCD calibrations, primarily due to different operating temperatures. There are two modes of OSIP generation to support: Normal Mode and Custom Mode.

Normal Mode: We usually contstruct the OSIP for a given minimum FRACRESP goal. For each cell, we compute the ENERG LO and ENERG HI limits vs energy by requiring a minimum specified FRACRESP, such as 98.5% enclosed energy.

Custom Mode: Alternatively, we can compute FRACRESP from a priori given ENERG LO and ENERG HI limits (vs energy). This mode can be useful for custom analysis when there are either confusing sources to avoid, or if there excess background in some regions of energy-dispersion space.

**TBD** - spec is currently here https://space.mit.edu/cxc/docs/osip_data_alg_icd-1.0.pdf https://cxc.harvard.edu/ciao/threads/ispec.html

Output format

The output OSIP is a standard FITS CALDB file with CALDB type osip and contains one extension. The AXAF_OSIP extension contains a order-sorted engery bouds and enclosed energy fraction vs CCD calibration region. Grids in the output products are required to be monotonic and in ascending order but are not necessarily uniform.

Example

mkosip
p2resp_file=$CALDB/data/chandra/acis/p2_resp/acisD2000-01-29p2_respN0008
.fits
gain_file=$CALDB/data/chandra/acis/det_gain/acisD2000-01-29gain_ctiN0008
.fits n_threads=10 ccdids=ACIS-4 verbose=4 energy_grid=253:1740:2

Generate the CALDB files for a combination of response file and gain file, limiting the analysis to the ACIS-4 chip. Use 10 parallel threads, and print detailed diagnostic data about the energy limits calculation. Further limit the calculation to two energy bins in the 253->1740 eV range.

Parameters

name	type	ftype	def	min	max	reqd
osip_mode	string		compute_limits			no
obspar	file	input				no
p2resp_file	file	input				no
fracresp_goal	real		0.985			no
order_bounds_table	file	input				no
energy_grid	string		253:1740:20;1750:1890:10;1900:4990:20;5000:12000:10			no
ccdids	string		ACIS-456789			no
high_limit_clip	real		1.3			no
low_limit_clip	real		.8			no
fracresp_high	string		fracresp_goal			no
resample_factor	integer		8
moments_full_distribution	boolean		no
verbose	integer		1	0	5
n_threads	integer		1

Detailed Parameter Descriptions

Parameter=osip_mode (string not required default=compute_limits)

The processing mode. Either compute_limits or compute_fracresp

NOTE: Only compute_limits, which is the default mode, is currently supported.

For compute limits, we use the fracresp goal and compute the corresponding energy bounds (ENERG LO, ENERG HI)

For compute fracresp, we read an order bounds table and compute the FRACRESP.

Parameter=obspar (file not required filetype=input)

observational paramater file

NOTE: This is currently unsupported.

A file that contains observational parameters, which includes the date and instrumental configuration required to resolve to a specific CALDB file.

Ignored if a named p2 resp file is given by the p2resp file parameter.

Parameter=p2resp_file (file not required filetype=input)

The CALDB file p2_resp

explicit CALDB file of type p2_resp.

Ignored if the epoch or OBSPAR file is specified

Parameter=fracresp_goal (real not required default=0.985)

lower limit for each energy

If osip mode is compute fracresp, try to reach or exceed this value of the enclosed energy fraction at each energy. It might not be feasible to reach this goal, in which case the clipping parameters (see below) will be imposed.

This parameter is ignored if the mode is compute limits and an order bounds table is given.

Parameter=order_bounds_table (file not required filetype=input)

A table of order limits vs energy

A table of order limits vs energy. That is, ENERG LO/ENERGY and ENERG HI/ENERGY (required if osip mode is compute fracresp).

NOTE: a CCD detected energy divided by the first-order equivalent photon energy (i.e., from the high-resolution diffracted position) is equivalent to a real-valued diffraction order.)

Parameter=energy_grid (string not required default=253:1740:20;1750:1890:10;1900:4990:20;5000:12000:10)

A custom table of energies

default to internally defined grid. If specified, formatted string for required energy grid, in the format: "e_min:e_max:num_bins". Multiple ranges with different bin sizes can be concatenated using ";". Energies are in eV units. The default grid is comprised of 60 energies with variable spacing, designed to have finer grids over regions of rapidly changing spectral response. Computation time will scale with the number of energy grid bins.

Parameter=ccdids (string not required default=ACIS-456789)

list of CCDs to process

CCDs are identified by integers from 0-9.

Parameter=high_limit_clip (real not required default=1.3)

maximum allowed ratio of ENERG HI/ENERGY

prevents the order-sorting region from becoming too wide, at the expense of possibly not meeting the fracresp goal.

Parameter=low_limit_clip (real not required default=.8)

minimum allowed ratio of ENERG LO/ENERGY

This prevents the order-sorting region from becoming too wide, at the expense of possibly not meeting the fracresp goal.

Parameter=fracresp_high (string not required default=fracresp_goal)

Allow high-side fractional encluded energy to be higher than fracresp goal.

Allow the initial high-side fractional enclosed energy to be higher than the general goal set by fracresp goal. This is used to set the high limit as if the response were a symmetric gaussian. The low limit then follows until fracresp goal is reached, as long as the limit is greater than the low limit clip value. This is to help obtain a higher FRACRESP by extending the limit on the Gaussian-like high energy side of the CCD response

Parameter=resample_factor (integer default=8)

RMF resample factor

The redistribution curve from the RMF will be resampled and interpolated using this factor

Parameter=moments_full_distribution (boolean default=no)

Calculate the moments on the full distribution

Indicates whether to calculate the moments on the full energy range

Parameter=verbose (integer default=1 min=0 max=5)

verbosity level

Displays verbosity level from 0 to 5, all messages are dumped in "logfile". Level 0: no display except error message. Level 1-3: all message of verbose=0 plus warning messages. Level 4: all message of verbose=0 - 3 plus more detailed logs to be used for debugging or logging. Level 5: all messages of verbose=0-4 plus ascii plots for detailed debugging.

Parameter=n_threads (integer default=1)

number of threads to use in parallel processing

When greater than 1, the tool will enable multithreading to speed up processing. This is the number of threads the tool should use.

Bugs

See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.

Refer to the CIAO bug pages for an up-to-date listing of known issues.