User:RiverWalker88/JS9Rough
JS9 is a web-based astronomical image analysis software. It was first introduced in the 2020 season to add an additional hands-on component to the astronomy event. This addition also prompted the possible permission of internet access for teams only to access the JS9 software. The JS9 website specifically made for Science Olympiad can be found at js9.si.edu/nso/nso.html.
Opening Files
The JS9 software opens FITS files (files with the *.fits extension). Most files that will be used for JS9 questions will use the *_evt2.fits extension, which includes X-Ray event data. Files can be opened locally or remotely, or you can open the example files on the NSO JS9 page.
Open Example
When the JS9 site specifically developed for Science Olympiad is opened, there are six example links at the top of the site. Selecting one of these links will open one of the example images. These images are good to start with when first working with JS9 because they are good images, and you won't have to sort through a lot of images that aren't easily analyzable to find them.
Open Local
In the File > Open Local menu, you can upload and open a downloaded FITS file.
Open Remote
In the File > Open Remote menu, you can use a proxy or CORS server to open a FITS file remotely from a link.
Proxy Server
When this is selected, you can open a file from a link that does not support CORS (Cross-Origin Resource Sharing), such as the Unofficial Chandra Archive. This will not display directly in JS9, but JS9 servers will retrieve the information to display the file. This option is the most commonly used, as it allows for a wide variety of links directly from archives.
CORS Server
This option will directly retrieve the image from a site that supports CORS (such as dropbox) and display the image directly in JS9.
Finding FITS Files
A great way to learn JS9 is to practice with JS9. Many telescopes have a large archive of data that they have collected in the past.
The UnOfficial Chandra Archive
The UnOfficial Chandra Archive (The Unofficial Chandra Archive) is the most common place to get FITS files for a JS9 analysis. In comparison to other archives, it is easy to search for and get a link to open a file, and the Chandra X-Ray Center data is very useful for analysis. It contains quite a few objects, including many of the DSOs.
First, you will need to search for an image.
- If you have the Observation ID of an image (most Chandra Photo Album articles have an Observation ID at the bottom that tells you what FITS file was used to generate the image), you can enter that in the ObsID field, and search for the image.
- If you know the name of the object that you want to search for, you can enter that in the "Name" field. This will give you a list of all of the FITS files for objects within a certain range (default of 30′) from the object you specified.
- Troubleshooting: If the name you specified resulted in "Cannot lookup name...", it means that they have the object under a different name. You can search the object name you have and try to find alternate object names (most Wikipedia pages about objects have alternative names for them).
- Troubleshooting: If the name you specified resulted in "Search Results : Found 0 Matches", then the Chandra Archive does not contain the object you searched for.
- If you have the coordinates of the object, you can use the "RA" and "Dec" fields. Enter the Right Ascension in the RA field, in the form h:mm:ss.ss (for example, if the right ascension is 12h 29m 06.7s, you would enter 12:29:06.7). Then enter the Declination in the Dec field in the form ±dd:mm:ss.ss (for example, if the declination is +02° 03′ 09″, you would enter +02:03:09).
- If you know what type of object you want to observe, but don't have a specific object, you can search the "Title Key" field. This will search the proposal titles of all FITS files and list any files that have your search term in their name. For example, if I wanted to look at objects with Radio Lobes, I could enter "Radio Lobe" in the Title Key field.
Next, you will have to pick an image out of the list. You can take a look at the proposal titles to find out what each observer was specifically looking for, and you can use the "Exposure" column. Exposure tells you how long a telescope looked at an object (in the case of the UnOfficial Chandra Archive, the unit for exposure is kiloseconds). The exposure can be really useful in determining what image you want. There are some general statements that can be made about different exposures, although you'll have to experiment to figure out what exposure works best for your purposes.
- As a general rule of thumb, the higher exposure, the better the energy spectrum of an image. If you want to look at an object's spectrum, you will want a higher exposure.
- Images with an exposure of less than 20 (depending on the object and distance to the object, sometimes more) tend not to have been observed for long enough to easily discern the object and any analysis tends to be noisy.
- Another general rule of thumb, as exposure increases, the bright pixels stand out more. If you want to look at the structure of any object (except a galaxy cluster), you probably will want an exposure of 45-80 Ks. Anything over 100 tends to be somewhat "washed out", although this is highly dependent on the type of object and the distance to that object. You may want to look at images with exposure of over 100 anyway, though, you might be surprised by how good the object looks (and as a bonus, you'll probably have a fairly clean analysis).
- As implied earlier, galaxy clusters don't tend to "wash out" easily. You can get really high exposures on these and still have a clear image.
The final step to getting an image from the UnOfficial Chandra Archive is to get the link. To do this, click on the Observation ID of the image you would like to open, find the link that ends in *evt2.fits (or any other link for that matter, the X-Ray event file is generally the most useful, though). Right click on this link and copy the link location. Now, you can simply use the "Open Remote" function described above to open this link.
Other Data Archives
Most other data archives are not nearly as easy as the UnOfficial Chandra Archive, and may have files that can't be opened by JS9. Many of these files also do not contain the as much information as an x-ray event file, and so you won't be able to analyze them as deeply.
Here's a list of archives from other telescopes that you can get FITS files from:
- NRAO Science Data Archive (Wavelength: Radio)
- You can search for an object in this archive, select the images that you want to open in JS9, and get a temporary link to the file sent to an email of your choice.
- When looking through the images, only the .uvfits can be opened by JS9.
- The only analysis you can do on this file is "Counts in Regions". That said, you can still make measurements and look at the object, so it is still useful.
Viewing the Image
Zoom
Using the bar at the top, you can click on either of the magnifying glass icons to zoom in or out. Additionally, you can open the "Zoom" menu to get more options on zooming in or out on parts of your image.
Panning
In the "View" menu of JS9, select the "Panner" option. A separate window will appear that contains a small version of the image with a box around the current area you are viewing. Drag this box anywhere in this small version of the image to pan around the JS9 image.
Colormaps
JS9 displays images in false color based on data. In the "Color" menu, you will be given a dropdown of different color schemes to change the colormap of your image. This changes how different intensities of the image appear. Playing with different colormaps can give you an idea of which one works best for you.
Contrast and Bias
You can adjust the contrast and bias of an image to highlight different parts of the image of different intensities. To adjust the contrast (or make the range over which the color covers change) click on the image and drag your mouse up and down. To adjust the bias (or the intensity over which the contrast is centered), drag the mouse left and right. This can help you determine areas of high intensity, or a certain intensity.
Composite and Overlaid Images
If you have 2 or 3 images, you can overlay them. This is useful if you have two or three images in different wavelengths of a single object (e.g. created through an energy Event Filter), you can overlay them on top of each other to create a composite image.
- The first step is to put each image in a red, green, or blue colormap. Only images in these colormaps can be overlaid.
- Adjust each different image as you see fit. This may require zooming out or panning to make all of them aligned, or adjusting contrast and bias. You can switch between images in the "File" menu.
- Select "rgb mode" from the "Color" menu to overlay images in the red, green, and blue colormaps on top of each other.
Analysis
Analysis in JS9 is done through regions in an image. A region will be placed on an image, and all pixels inside the region will be analyzed using different analysis functions. All analysis functions can be found in the "Analysis" menu, or can be done through the JS9 console. To open the JS9 console, go to View > Console.
There are four different categories that analysis functions fall under, Client-Side Analysis, Server-Side Analysis, NSO Analysis, and ImExam Plugins. Client-Side Analysis and ImExam Plugins can be done from a browser, and the FITS file will not need to be uploaded to a JS9 server. NSO Analysis and Server-Side Analysis can only be run if the FITS file is uploaded to a JS9 server. If you use the "Open Remote" function to open your file, or you open an example file, the file should automatically upload to the remote server. However, if you open a file locally, the file doesn't automatically upload for some reason, or you leave for too long and the file gets deleted from the server, you can upload it using Analysis > "upload FITS to make tasks available" or running analysis uploadfits in the JS9 console. Note that if your image timed out and was deleted, you will have to use the JS9 console to re-upload it to the server.
Regions
Regions are geometric shapes that can be placed on an image. These regions indicate areas for analysis, or can be used to indicate areas of interest on the image. To insert a region, click on the region shape in the toolbar, or open the "Regions" menu and select the region that you would like to insert.
Clicking inside a region will toggle it into focus. You can then move or resize it, as you would a shape in a drawing program. Click outside the region to toggle it out of focus. Double clicking inside a region will open the configuration menu. You can view and change parameters in this menu, and then click apply to save your changes to the region.
Annulus
This region is a target-shape. It is considered by many functions as multiple regions, with each space between the lines as its own region. When you insert an annulus, it defaults in the center of your viewing field with two regions. To change the number of regions, double-click on the annulus to bring up the configuration menu. In the third field after the "Edit:" label (this is also the longest of the three fields), there will be three default values, one of them is 0". To add another region, you will need to add another value behind this, which will mark the radius of the next circle out (make sure to insert a comma between all values and quotation marks after each measurement, indicating arcseconds).
Box
This region is rectangular. It defaults as a square, but can be resized as a rectangle. You can manually change the width and height of this region by double-clicking to open the configuration menu and editing the 3rd and 4th boxes after the "Edit" label.
Circle
This region is circular. To change the radius of this region, double-click on it to open the configuration menu. Edit the 3rd text field after the "Edit" label.
Ellipse
This region is elliptical. It defaults as an ellipse with a horizontal radius about 1.5 times the vertical radius, centered on the viewing field. Ellipses can be stretched, compressed, or dilated to the desired shape. Alternatively, the two radii of the ellipse can be entered manually, by double-clicking on the region to open the configuration menu and entering the desired horizontal radius and vertical radius in the 3rd and 4th text fields after the "Edit" label.
Other Regions
The polygon region is a region that defaults to an equilateral triangle centered in the viewing window that can be stretched, compressed, or dilated.
The line region is a linear, one dimensional region. This region analyzes pixels that fall on this line. This line can be adjusted using its endpoints, or selected/moved by clicking on the line.
The point region is a single point region. This analyzes only pixels that fall on that point. This point can be moved or selected by clicking on it.
The text region is not used for analysis, but rather for annotating the image. This may be useful if a test requires you to submit a final image and asks you to indicate a certain point.
Client-Side Analysis
Client-Side Analysis is analysis that can be run in the web browser, and does not require requests to be made to a JS9 server. All functions in this section can be found in the Analysis menu under the grayed-out "Client-side Analysis" heading.
| Analysis | Location in Menu | JS9 Console Command | Description/Use | Screenshots |
|---|---|---|---|---|
| Coordinate Grid | Analysis > Coordinate Grid | N/A | This displays a coordinate grid over the image. | |
| Counts in Regions | Analysis > Counts in Regions
Note: This is the one under the Client-side analysis heading. |
analysis counts
|
The main purpose of this function is to count the photons (counts) in all of the regions in the image. However, it also tells you how many arcseconds are in each pixel on the image (arcseconds/pixel) which is a very useful conversion factor for getting between arcseconds and pixels. Additionally, this function give you information about the area of the region(s) you are using. | |
| Radial Profile | Analysis > Radial Profile
Note: This is the one under the Client-side analysis heading. |
analysis radialprofile
|
Radial Profile requires an annulus. This determines the flux in each region (in photons/square arcsecond) and plot the value for each region in the annulus on a graph of the surface brightness vs. the radius. This is identical to the Server-side analysis version. | |
| Gaussian Blur | Analysis > Blur, equivalent sigma | N/A | This blurs the image pixel values together using a Gaussian function. You will specify a radius (sigma) in the text field and the pixels will blur based on that radius. The lower the sigma that you enter, the less the pixels are blurred. To run this analysis, open the "Analysis" menu in the menu bar, and enter a value in the text field under the "Blur, equivalent sigma" heading, under the "Client-Side Analysis" heading. Then, push enter to blur the image. |
Server-Side Analysis
Server-Side Analysis is analysis that sends requests to a JS9 server, and the JS9 server will analyze the input data and send a result to the web browser. The Server-side analysis functions can be found in the Analysis menu under the grayed-out "Server-side analysis" heading.
| Analysis | Location in Menu | JS9 Console Command | Description/Use | Screenshots |
|---|---|---|---|---|
| FITS Headers | Analysis > FITS Headers | analysis fitshead
|
Displays all the headers in the FITS file. This can be useful for finding documentation of the FITS file, such as the name of the object being observed, the telescope and instrument, or the observation date, for example. Additionally, it does list the FITS headers that can be used in the Histogram Plot analysis. | |
| Counts in Regions | Analysis > Counts in Regions
Note: This is the one under the Server-side analysis heading. |
analysis counts
|
The main purpose of this function is to count the photons (counts) in all of the regions in the image. However, it also tells you how many arcseconds are in each pixel on the image (arcseconds/pixel) which is a very useful conversion factor for getting between arcseconds and pixels. Additionally, this function give you information about the area of the region(s) you are using. This is identical to the Client-side analysis version. | |
| Radial Profile | Analysis > Radial Profile
Note: This is the one under the Server-side analysis heading. |
analysis radialprofile
|
Radial Profile requires an annulus. This determines the flux in each region (in photons/square arcsecond) and plot the value for each region in the annulus on a graph of the surface brightness vs. the radius. This is identical to the Client-side analysis version. | |
| Energy Spectrum | Analysis > Energy Spectrum | analysis energyplot
|
This generates an energy spectrum of all regions. It displays a graph with energy (electron volts) on the x-axis and counts (photons) on the y-axis. This spectrum is extremely useful in an analysis, as it gives the peak wavelength of the X-Ray spectrum for temperature measurements, and displays X-Ray spectral emission lines of the object. You can then match these spectral lines to their corresponding element (a table of some common lines can be found here) and determine what elements are present in the object. This is very useful for classifying supernovae, as each class will have some specific spectral lines that appear for the specific elements it produces. | |
| Light Curve | Analysis > Light Curve
Note: This is the Light Curve under the Server-side analysis heading. |
analysis timeplot
|
This generates a light curve of all selected regions. It returns a plot display of the time (in seconds) on the x-axis and counts (photons) on the y-axis. There has also been some processing done to this plot, it is not the raw light curve. This is not the same as the light curve in NSO analysis. | |
| Histogram Plot | Analysis > Histogram Plot | analysis histplot
|
This generates a plot of a user-specified column in the FITS file of all regions. A FITS file is made up of several columns, each containing different data. To find a complete list of columns for a FITS file, go to File > display > FITS HDUs. The list item that says "EVENTS" (assuming you're using Chandra data) will have a list of cols, or columns. To generate a histogram plot, run the analysis. You should see a box. Enter the name of the column that you wish to be on the y-axis. Click "run" to generate the plot. A histogram of the "time" column will do the same thing as the Server-side analysis Light Curve function. A histogram of the "energy" column will generate an energy spectrum. The pi and pha columns will also generate an energy spectrum, although they do not contain the same scale as an energy spectrum. | |
| Event Filter | Analysis > Event Filter | analysis evfilter
|
This function will generate a new FITS file based on specified criteria. To generate the new FITS file, run the event filter analysis. You will be prompted to enter your criteria. To do this, you will have to specify a column name (see the above row for information on columns) and a range in that column to display in the format column=lower:upper. For example, pi=500:1500 will result in an image that only displays pixels that are between a pi value of 500 and 1500. You are able to analyze this image as you would any other image. You can switch back and forth between this image and the original image using the File menu. You can pair this function with the overlay function to get an image that shows different ranges in different colors.
|
NSO Analysis
NSO Analysis contains analysis functions that were specifically made as an addition for the Science Olympiad version of JS9. The following analysis functions can be found in the analysis menu of JS9 under the grayed-out "NSO Analysis" Heading. Note that this will only work if you are in the Science Olympiad specific JS9. NSO Analysis is also server-side, so you will have to upload your FITS file to the remote JS9 server to use these analysis functions.
| Analysis | Location in Menu | JS9 Console Command | Description/Use | Screenshots |
|---|---|---|---|---|
| Light Curve | Analysis > Light Curve
Note: This is the Light Curve under the NSO Analysis heading. |
analysis lcurve
|
This generates a light curve of a selected region, with time on the x-axis and counts/second on the y-axis. This gives you a raw light curve of the region. This light curve can be useful to see obvious outbursts or periodicity, but tends to be more difficult to look for more subtle periodicity, which is where the next couple of NSO Analysis functions come in. Note that this is not the same light curve as the Server-side analysis version. |  |
| Power Spectrum | Analysis > Power Spectrum | analysis powspec
|
A power spectrum is a spectrum that tests waves of many different frequencies overlaid onto the light curve plot. This analysis generates a spectrum of a selected region, with the frequency of the tested wave on the x-axis and power on the (or how well it fits) y-axis. This analysis function can be very useful for determining periodicity. If the power spectrum has an obvious peak and little noise (unlike the shown period spectrum), it is likely that the period of the object is [math]\frac{1}{frequency}[/math] in seconds. This is because Hertz is defined as [math]\frac{1}{seconds}[/math], so flipping it would give you seconds. However, you will want to verify this period (likely using the period folding technique described below). Note that you can only run this analysis if you have already run the NSO Analysis version of Light Curve. | |
| Period Folding | Analysis > Period Folding | analysis efold
|
This is a method of testing a potential period of a light curve of a region. It is done by taking the a certain period of a light curve and "folding" it over the rest of the light curve several times. If the period is correct, the light curve will constructively interfere and the form of the light curve will be apparent. If the period is incorrect, the light curve will destructively interfere and a periodic wave won't be apparent. This analysis requires you to enter a possible period, and it will generate a light curve of that period with the number of stacks you specify (the number of times the period is "folded"). When you run this analysis, you will be prompted to enter the period to be tested, and modify the number of stacks, if you so desire. Note that you can only run this analysis if you have already run the NSO Analysis version of Light Curve. | |
| Flux in Regions | Analysis > Flux in Regions | analysis flux
|
This generates a window that gives you the flux in regions (in photons/arcsec2/sec). It also returns the telescope, raw counts, the raw area, the regions, and the exposure of the image. |
ImExam Plugins
Analysis done with the ImExam Plugin uses a rectangular box as a region, no matter what shape region is actually chosen. It has various analysis functions that specialize in comparing pixels in a region to one another, and has lots of visualization analysis functions. These analysis functions tend to be somewhat more unclear to work with, and probably will not be heavily emphasized in a JS9 section on an Astronomy exam.
| Analysis | Location in Menu | JS9 Console Command | Description/Use | Screenshots |
|---|---|---|---|---|
| 3dPlot | Analysis > 3dPlot | N/A | Generates a 3D Plot of the data in a region, to visualize data in a three-dimensional chart. | |
| Encircled Energy | Analysis > Encircled Energy | N/A | This generates a plot of the fraction of the total intensity of the region that has been accounted for as a function of distance from the center. In other words, as you move out from the center, what fraction of the total counts are within that radius? | |
| Histogram | Analysis > Histogram | N/A | This generates a plot of the pixels in a region that are in the same 250th percentile of their value. Note that this is not the same function as the Server-side Histogram Plot function. | |
| Radial Proj | Analysis > Radial Proj | N/A | This generates a scatterplot of pixel values at their respective radii. A Gaussian fit is overlaid on the scatterplot. | |
| Region Stats | Analysis > Region Stats | N/A | This returns the statistics of the region, including (but not limited to) the total counts, the x and y position, and width and height of the region. The region is still treated as a rectangular region for this analysis, as well. | |
| X & Y Projection | Analysis > X Projection
Analysis > Y Projection |
N/A | This returns the sum, average, or median (depending on which is selected) of the values of the vertical (X) or horizontal (Y) pixels along the width (X) or height (Y) of a region. |
Additional Help
The JS9 User Guide can be found under "Help" in the menu bar, in the "General Help" dropdown. Additional JS9 help can be found in the resources in this menu as well.
