chandra/ds9 (the windows version) faq page
john kolena
7/25/2009

basic stuff: what Chandra does....  downloading/installing the ds9 image processor


0) what is Chandra anyway?

Chandra is one of NASA's great observatories (along with Hubble, Spitzer, the now-defunct Compton).
It is an X-ray telescope in an elliptical orbit around Earth that carries it from an altitude of about 2 earth
radii (at closest) to an altitude of about 20 earth radii (at farthest).

Chandra consists of 4 nested pairs of grazing incidence paraboloid/hyperboloid mirrors,
each of which is 83 cm (33 in) long.
Chandra has a focal length of 10 m; the plate scale for images is 0.5 ''/pixel.
The field of view is 1.0 degree (diameter).

Chandra instruments include:
1) what does Chandra do?

For each photon it detects, Chandra measures its
2) what information can Chandra display easily?
In order to output the above, a fast internet connection is required because the generation of images,
spectra, and light curves is done back at the Chandra servers and then sent back to your computer.

3) what can you do with the images, light curves, and spectra?

just a sampling of things:

4) how do I download and install ds9 on my computer?

Go to the official ds9 installation page.

The directions are straightforward and easy to follow.

5) I've installed ds9 on my computer...now how do I open it?

The installation process may have created a desktop icon.  If so, double click on it.
If not (which is more likely), go to (via My Computer or Explore) the folder
C:/Program Files/ds9 

This is the default installation directory.  If you selected another directory during installation, go to it instead.
In this directory should be a ds9 icon (as of 2007 it is a yellow sunburst symbol superimposed on a circular teal background).
Double click on it.
finding images.... loading images into ds9


 11) I've installed and opened the ds9 software...how do I load a Chandra image?

a) Under the Analysis menu, select Virtual Observatory
b) in the pop-up Virtual Obsevatory window, click in the Chandra-Ed Archive Server box
c) the Chandra-Ed box should turn green, and a third ds9 window opens with the Chandra-Ed image directlory
d) in this third window, select an image from the list, and double-click on the image title
e) there will be an authentication message and an acknowledgement that the image successfully loaded in the original ds9 window;

(if you wish to load a different image from the Chandra-Ed directory at a later time, return to this third ds9 window,
and click on the left-pointing blue arrow at the upper left.... this will return you to the list of images in the Chandra-Ed Archive)


12) what if the image (ObsId) that I want to load doesn't appear in the list of images in the Chandra-Ed Archive?

a) go to the bottom section of the Archive page entitled "Search the Chandra Public Archive"
b) click on the link titled "Unofficial Chanda Archive Search"

from this link, you can search for observations by ObsId, RA, Dec, Title, Observer or Object Name.

However, my experience is that the search capabilities are somewhat limited.

To obtain the entire Chandra image list, ordered by ObsId number, leave all fields blank.

Searching by ObsId or by Observer works reliably. 

However, searching by Name does not seem to work at all (or, more likely, I haven't figured out how to use it).

Searching by sky coordinates (RA/Dec) requires you to input an RA AND a Dec AND a size in order to work properly.
size here represents the radius of the search region centered on the RA/Dec value that you input.
If either the RA or Dec  is left blank, the entire image list is returned.

Searching by Title Key (aka Title Keyword) works only if the name object you are interested in happens to be in the title of the observation.
For example, if you type Kepler into the Title Key box, you retrieve ObsId 115 and 116, although 115 is actually Tycho, whereas 116 is Kepler.
It does not retrieve ObsId 4650, whose title is "Untangling the Dynamics of Kepler's Supernova Remnant"

c) If the search returns one or more records AND the description under Title is itself a link,
then click on that link to load the corresponding Chandra image. 
Be sure to click only on the link under Title and not on any other links in that same row.

SIDE NOTE:
If the search returns one or more records but the description under Title is NOT in link form,
this means that there is not an image file available in the Chandra archive;
therefore this ObsId is not able to be analyzed with Chandra Ed Analysis Tools.

alternatively, click on the ObsId link and you will see what files related to this ObsId are available;
there may be an .evts file, a .pha file, but notice that there is no .img file.

Point source objects, grating observations, & observations in CC (continuous capture mode) are not likely to have an associated image file.

d)  Once you have loaded an observation you searched via the method above, it will be added to the Chandra-Ed Archive list in the future.


13) how else can I search for an object (and its image) by name?

Alternative search capabilities can be found at

a) the Chandra Data Archive Observation Search Page
(you can also access this via the ChaSeR link in the second line of that The UnOfficial Chandra Archive Search page)

type in the colloquial name of the object in the Target Name box.
If an appropriate ObsId is returned, note the ObsId number, and then return to step (a) in questions (4) above and follow that procedure to search by ObsId.

b) the HEASARC search page

the advantage of using HEASARC is that you can search for data from other satellite missions (not only in the x-ray, but also in other parts of the spectrum)

Once you've filled in the Object Name in #1 and checked the appropriate mission/catalogs boxes in #2,
make sure that the Archived data and observations box is checked under #3 (it's probably the only one you want checked),
and then click on the Start Search button at top or bottom.

A new page opens that lists the relevant observations.

14) What if I want to search for objects of a certain type, such as a quasar or a neutron star?

Go to the Chandra Data FTP Archive .

The images are located in the science directory, but not in a very user-friendly manner.  In the science directory, there is a subdirectory for each cycle (or calendar year) that Chandra has been operating.  The sub-directories are titled ao<nn> (where the number nn stands for the Chandra operating year, with 00 standing for the year beginning in mid-1999 when Chandra began observations).  Within each ao<nn> sub-directory are further sub-drectories (each named cat<i>) which contain objects of homogeneous type.  <i> types are 0 Non-celestial (Engineering) Observation
1 Solar System    
2 Normal Stars and White Dwarfs    
3 White Dwarf Binaries and Cataclysmic Variables    
4 Black Hole and Neutron Star Binaries    
5 Supernovae, Supernova Remnants, and Isolated Neutron Stars    
6 Normal Galaxies    
7 Active Galaxies and Quasars    
8 Clusters of Galaxies    
9 Extragalactic Diffuse Emission and Surveys and Galactic Diffuse Emission and Surveys

Therefore, the cat1 sub-directory contains observations of only Solar System objects.

Archived data and observations
Within each category sub-directory are the observations sorted by ObsId number. 
So you still don't know the specific object associated with an observation unless
(a) you open the image and read the FITS header
or
(b) you go back to Chandra Data Archive Observation Search Page



learning how to use the ds9 image processor.... basic tools


21) ok, I've opened an image that I want to analyze, but the number of commands seems overwhelming... where do I start?

yes, there are a lot of command choices, but relatively few will be used initially...

first of all, note that the Menu titles at the top (File, Edit, View, ...) are duplicated by the top row of boxes;
you can either click on the Menu titles or click on the equivalent box to see the sub-Menu commands;
however, the complete list of sub-menu commands is available only by clicking on the menus at the top;
clicking on the equivalent box generally gives only a subset of the sub-menu commands


22) how do I learn the basic image processing features of ds9?

a) if you have some experience in image processing, my learn how to use ds9 in an hour or less! 
(the core of a presentation that I made at a 2006 AAPT meeting) provides a quick and dirty guide to the basic features of ds9

b) for a more leisurely paced and more thorough guide, go to
Learning to Use the ds9 Imaging System and 
Education Activities To Accompany Chandra Data Analysis Software
at the official Chandra-Ed site.

in both of the above cases, you will learn
some basic image processing commands,
how to generate light curves,
how to generate spectra,
how to find periodicities in light curve data via power spectra,
how to find (and align) an optical or infrared image that matches the x-ray image,
how to create sub-regions of the image for analysis

c) if you want to know more about some of the more commly used commands, follow the links below:

for qualitative analysis:
"contrast" and "bias"
"color"
"value" & counting photons
"scale"
"horizontal cut" and "vertical cut" (each now called "graphs" and under the View menu) & "pixel table"  (under Analysis menu)
"contours" and "coordinate grid" (both under the Analysis menu)
how to create, resize, ... "regions"

for quantitative analysis:
"counts in region" sums up the x-ray counts in a region (under the Analysis menu, then under Chandra-Ed Analysis Tools at the bottom on the menu)
"radial profile plot"  (also under the Analysis menu, then under Chandra-Ed Analysis Tools at the bottom on the menu)
"quick energy spectrum plot"  (under the Analysis menu, then under Chandra-Ed Analysis Tools at the bottom on the menu)
"quick light curve plot"  (under the Analysis menu, then under Chandra-Ed Analysis Tools at the bottom on the menu)

for more details about the Chandra-Ed Analysis Tools,


24) these green circles keep popping up... what are they and how do i get rid of them?

The green circles are produced by an inadvertent mouse click in the image space of ds9.
The interior of the green circle defines a "region" (see question      below) that is useful for data analysis.

To delete one or more green regions:
click on the Region button in the top row of boxes;

to delete all the green regions, click on the del all box in second row of boxes in the ds9 window

to delete a specific green region, select the region by clicking on it (corner marks will appear);
then either
(a) press the Delete key on the keyboard
or
(b) click on the del box in the second row of boxes in the ds9 window


25) what do the green circles represent?

Each green circle defines a "region."  Many ds9 commands (particular the Chandra-Ed Analysis Tools) operate on the last selected region (rather than the entire image space).


27)  why do some of the secondary ds9 windows disappear when I move my mouse around?

Actually the windows don't disappear, but instead, they move behind the main ds9 window.
The ds9 window (labeled SAOImage ds9 ) has a preference for remaining in front of the other windows.
If the problem persists, move the main ds9 image to the side (by left-clicking-and-dragging on the top bar of the window) in order to uncover the other windows.


28) how can I find out more about the image (when it was taken, how long the exposure was, etc.)

click on the File menu, and then select Display Fits Header


"TIMEDEL" is the time resolution of the image
"EXPTIME" or "EXPOSURE" is the length of image exposure in seconds
what the ds9 interface is really doing.... how not to crash ds9


31) so what exactly is happening when I click on a link in the Chandra-Ed image archive?

The image is being retrieved from the Chandra-Ed image archive and displayed in the ds9 window on your computer.
This is why is may take a few seconds (or more) for the image to pop up on you computer.
The image does not actually reside on your computer unless you save it. 
To do so, select Save As from the File menu at the top.


32) how is ds9 able to produce a light curve or a spectrum for an image I've opened in ds9 when the image doesn't even reside on my computer?

When you select a command option such as the Quick light curve plot or Quick energy spectrum plot (under the Analysis menu, then under Chandra-Ed Analysis Tools), ds9 sends the command back to the Chandra servers where the command is executed on the image in the Chandra servers, and then the result (the light curve or the spectrum) is sent back to (and displayed on) your computer.  In other words, the powerful processing software required to extract and produce the light curve or spectrum from the original Chandra data isn't actually part of the ds9 software on your computer.


35) OK, so the processing power is all back at the Chandra servers in Cambridge, MA, which means my computer doesn't have to do the hard work to produce a spectrum or light curve.  But doesn't that mean that I need a fast and stable internet connection to make all this work?

Good point!  And that's why ds9 will sometimes spontaneously close, hang, or do other weird things.


36) How can I keep the crash/hang problems to a minimum?

a) Faster internet connections always yield better results.

b) Reliability is probably inversely proportional to the number of people trying to access the image archive at the same time that you are.
(Therefore, be careful when you are using ds9 in your classroom with multiple students trying to connect or when running a teacher workshop where multiple computers are trying to access the servers simultaneously.  You will also find that these problems can occur in single-use situations.)

(In my experience, in multiple-user ds9 situations, the failure/hang rate after a Chandra-Ed Analysis Tools  request (for example, a light curve or a spectrum) ranges from 10 - 50%.)

c) After a command request, it's best not to do anything else on your computer. 
Don't switch to another window, don't move your mouse, don't type on the keyboard.... just be patient and wait.

d) Keep the number of ds9 windows open to a minimum.  After acquiring a spectrum, for example, close the spectrum (if you don't need it further) before acquiring another spectrum or light curve. 

(Although, I have had as many as 15 ds9 windows open on my computer simultaneously before crashing.)
the Chandra-Ed Analysis Tools: light curves and spectra


41) where can I find the Chandra-Ed Analysis Tools (ChEAT)?

The ChEAT menu can be found at the very bottom of the ds9 Analysis menu (immediately below the Clear Analysis Commands tab)
However, the ChEAT will only be visible if Virtual Observatory has been opened AND an image has been loaded into ds9;
    see question 11 above.

42) what's special about the ChEAT?

The ChEAT are ds9 processor's most powerful tools. 
A short description of each of the tools can be accessed by selecting the Overview of Chandra-Ed Analysis Tools tab.
The tools that I use most commonly are:

a)  Quick Light Curve Plot   or   FTOOLS/Light Curve   (number of photons collected vs time);
       Quick Light Curve Plot has options for what is plotted along the horizontal axis; FTOOLS/Light Curve does not.

b)  Quick Energy Spectrum Plot (number of photons collected vs photon energy);
       the horizontal axis (energy) is in units of ev (electron volts);
       photon energy = hc/l  (h = Planck's constant; c = speed of light; l = wavelength of light), or
       in SI units:   energy = 1240. ev-nm/l      (nm  =  nanometer)

c)  Energy Cut  displays a new image created using only photons in a specified energy range (in units of keV);
       this is useful if you want to display an image in the light of a single spectral line

d)  CIAO/Sherpa Spectral Fit produces a best fit to the spectrum returned by  Quick Energy Spectrum Plot;
       user must select from different models (each defined by a different function f of energy) used to fit the data:
       (1) power law:   f(E) a   E-n
            the parameter n (often called the spectral index) is returned by the fit;            
             synchrotron radiation (radiation by electric charges moving in a magnetic field) obeys a power law;
             For this type of energy source, a plot of log flux vs log energy would be linear with slope  -n .

       (2) blackbody:   f(E) a   E3 (eE/kT - 1)-1      (k = Boltzmann constant; T = temperature);
             the parameter  kT  is returned by the fit;
             blackbody radiation results from emission by an opaque object in thermal equilibrium;
             the radiation characteristics are determined entirely by the object's temperature.

       (3) bremsstrahlung:   f(E) a   (kT)-1/2 e-E/kT       (k = Boltzmann constant; T = temperature);
             the parameter  kT  is returned by the fit;


46) how can I manipulate (zoom in, ...) the pop-up windows for spectra and light curves?

a) you can zoom in on a region of the spectrum window by left-clicking-and-dragging followed by a left click;
     a right-click reverse the process; multiple zoom-ins are allowed

b) you can save the plot data in .dat form (a unix extension) by selecting File, Save Data;
     the plot can be reopened in a plot window only;
     multiple plots can be opened in the same window;
     you can distinguish different curves  by coloring different plots via the Color menu at the top of the Plot window

c) you can save the data (ordered pairs) in .dat form that can then be opened in a spreadsheet
useful physics info related to spectra

51) how can I identify x-ray spectral lines in the spectrum?

a) here is a table of x-ray emission lines (in order of increasing wavelength or decreasing energy)

b) here is an interactive spreadsheet of x-ray emission lines (courtesy of Harlan Devore);
       type in the energy of the line you are searching for

c) here is the full searchable database of x-ray emission lines


52) what do those spectral line symbols (such as the Ne X 4 --> 1 line at 0.9828 kev) mean?

Ne X means Neon ionized 9 times, i.e., Neon with 9 electrons removed.
(the ionization is one less than the Roman numeral value.)

A neutral neon atom has 10 electrons, so this means that only 1 neon electron remains in Ne X and is the electron responsible for producing the emission line in dropping from level 4 to level 1.   In general, the strongest lines are those that involve a drop to the ground state and that originate in a not very high excited state.


55) can I tell anything from the smooth (continuous) part of the spectrum?
miscellany


70) can ds9 load and analyze any FITS image?

ds9 should be able to load any FITS image, even those not from Chandra

Of course, many of the features (for example, RA & Dec coordinates, the Chandra Analysis Tools)
will not be operative because you will not be using the images stored in the Chandra image archive
nor will you be using


71) how can I find out about other projects that can be done with ds9?

visit my Chandra Resources page

in particular, check out
investigating supernova remnants
light curves, power spectra, and periodicities

also, check out Tycho’s Supernova Remnant - a ds9 activity  by Pam Perry




vnc issues


85) how to reinitialize a vnc connection

if your vnc screen shows a completely gray background, here is how to reinitialize the connection....

a) suppose that your session is number 8 on   basho.rutgers.edu

login into basho.rutgers.edu with
username = vastro8
password = your usual basho.rutgers.edu:8 password

(in all of the following, you will need to replace "8" by whatever session number you are using)

b) in the main directory there should be a file named    vncRestart8.sh

execute the file by typing:

./vncRestart8.sh

a typical (good) response to this command is:
Killing Xvnc process ID 1966
rm: cannot remove `.X8-lock': No such file or directory
rm: cannot remove `X8': No such file or directory
 
New 'X' desktop is basho.rutgers.edu:8
 
Starting applications specified in /home/vastro8/.vnc/xstartup
Log file is /home/vastro8/.vnc/basho.rutgers.edu:8.log


c) if the response is "Permission Denied" , change the permissions to allow you to execute the file by typing:

chmod uog+x vncRestart8.sh


d) in order to check that you have execute privileges, type

ls -l  vncRestart8.sh

the response should look like

-rwxrwxr-x    1 vastro8  vastro8        76 Jun  1  2005 vncRestart8.sh

if the x's are showing in the response line above, go back and repeat step (c)
Disclaimer

The answers, directions, views etc. expressed on this page (and my other Chandra resource pages)
are mine alone and not those of the Chandra X-ray Observatory staff, the Harvard Smithsonian Observatory,
or NASA.

They didn't pay me to write this.
They don't even acknowledge that these pages exist.

need more help, have suggestions? modifications?
write me at kolena@gmail.com