doc: add sbp_extract.org

Add document to explain the surface brightness profile extraction
procedure and track some of the notes/caveats.

1 files changed, 55 insertions, 0 deletions

diff --git a/doc/sbp_extract.org b/doc/sbp_extract.org
new file mode 100644
index 0000000..efd525e
--- /dev/null
+++ b/doc/sbp_extract.org
@@ -0,0 +1,55 @@
+#+TITLE: Surface Brightness Profile Extraction
+#+AUTHOR: Weitian LI <liweitianux@live.com>
+#+DATE: 2016-06-03
+
+
+* NOTE: how =dmextract= calculate the area of extraction region
+The =dmextract= can take either *events* file or binned *image* file as the input file.  However, the extracted SBP may be *different*, mainly due to the area calculation.
+
+Above all, let's have a look at how the SBP quantities are calculated ([fn:dmextract]):
+#+BEGIN_EXAMPLE
+MEAN_SRC_EXP = TOTAL_SRC_EXP / EXP_AREA
+SUR_BRI = COUNTS / AREA ~ AREA^{-1}
+FLUX = COUNTS / EXPOSURE / MEAN_SRC_EXP ~ EXP_AREA
+SUR_FLUX = FLUX / AREA ~ EXP_AREA / AREA
+#+END_EXAMPLE
+where =AREA= is the area of the source extraction region, while the =EXP_AREA= is the area of the exposure map with respect to the source extraction region.
+Note we explicit distinguish these two areas, as we'll see below that it is responsible for the different extraction results.
+Also note that we ignored the background contribution here for simplicity.
+
+For both the two cases, the *excluded point sources* (i.e., =[exclude sky=region(???.reg)]=) are taken into account, and they are also *excluded* when calculating the extraction region (i.e., the =AREA= column/values of the produced HISTOGRAM file by =dmextract=).
+Therefore, no extra procedure is required in order to subtract the areas of these excluded point sources from the surface brightness extraction region.
+The excluded regions corresponding to the point sources are recorded in the FITS header using the keyword =DSVAL?=, so =dmextract= can properly handle this.
+
+** Image file as the input
+Using the already binned *image* file as the input file is *recommended*, and it is simper than the events file case, e.g.,
+#+BEGIN_SRC sh
+$ dmextract infile="img_c7_e700-7000.fits[bin sky=@sbprofile.reg]" \
+            outfile="sbprofile.fits" \
+            exp="expmap_c7_e700-7000.fits" \
+            opt=generic
+#+END_SRC
+
+Generally, the image file is as such generated:
+#+BEGIN_SRC sh
+$ dmcopy infile="evt2_c7_clean.fits[energy=700:7000]\
+                                   [sky=region(skyfov.fits[ccd_id=7])]\
+                                   [bin sky=1]" \
+         outfile="img_c7_e700-7000.fits"
+#+END_SRC
+where we use the *ACIS-S* (=ccd_id=7=) observation as an example, and the =skyfov.fits= contains the FoV/region of each CCD chip.
+Also note that the =skyfov.fits= should be generated by the CIAO tool =skyfov= with the parameter =aspect= specified, otherwise, the produced =skyfov.fits= dose not precisely describe the CCD chip regions, due to the ignorant of aspect solution.
+
+As the =skyfov.fits= is incorporated to generate the image, the regions that describe the CCD geometries are also recorded into the FITS header using the same set of keywords =DSVAL?=, similar to the case of excluded point sources.
+
+Therefore, when =dmextract= calculate the area of the source extraction region, the regions that *beyond the CCD edges* are excluded as well.  So the =AREA= is exact the *valid* area of the extraction region with both the point source regions and out-of-CCD regions excluded.
+
+The exposure map is generated by the CIAO tool =fluximage= and has the identical dimensions as that of the input image.  So the =EXP_AREA= is the same as =AREA=.
+Thus the final =SUR_FLUX= is independent of the area of the extraction region, which is what we want.
+As a result, it is recommended to bin the events file into an image, and then extract SBP from the image.
+
+** Event file as the input
+
+
+* References
+[fn:dmextract] CIAO =dmextract= help: http://cxc.cfa.harvard.edu/ciao/ahelp/dmextract.html