Image and Spectrum Viewer (Atlas): Tables

Contents of page/chapter:
+Table Header
+Table Columns
+Adding Columns
+Table Filters
+Table Actions: Searches
+Row Details
+Table Cells
+Saving Tables
+Table Navigation

Table Header

The table is shown exactly as it has been provided to the tool, with all columns as defined by the creator of the table. To understand what each column is, please see the documentation associated with that catalog or table.

At the top of the table, there can be several symbols:

which we now describe, going from left to right along the top of the catalog tab.

Table navigation

The first thing to notice is that (typically) only the first 50 rows are displayed in the table. In the example here, there are 316 results that were retrieved as a result of the search, grouped into 7 'pages.' The left/right black arrows plus the page number allow you to navigate among these 'pages' of 50 results each. Note that the entire set of results (not just the 50 rows you are currently viewing) can be sorted by clicking on any column's name.

Filter

Filters are complex and powerful enough that they are covered in a separate section below.

Table as text

Clicking on this changes the table display into a fixed-width text display. The icon then changes to click this again to return to the default table view.

Save table

This is how you can save the table. It has a separate section below.

Add a column

This icon adds a new column to the table. This has a separate section below.

Info link

You may or may not see this icon. This is an "information" button and, if it exists, it may provide additional information about the table. It could have information about the job that was used to retrieve it:

where the direct link to the job is given there (and can be copied by clicking on the clipboard, ready to be pasted into a helpdesk query, for example), with a job id as shown. It could also just have information about the table metadata:

where the information about this table includes information about the query that produced it.

Row details

You may or may not see this icon. This is how you get more information about the currently-selected row. It has a separate section below.

Table options

Clicking on this icon brings up options for the table, e.g., how many rows are displayed per page, which columns are shown, metadata about each column if available, whether units and data types are shown at the top of the column, shown here:

By default, it is often but not always the case that all columns are shown. To show or hide columns, select the tickbox in each given row. The default page size is 100 rows. Note that expanding the page size to numbers much greater than 100 may result in a substantial performance degradation (e.g., your browser will appear to freeze or not appear to be doing anything while it manages and renders the large table). See the Filters section below for more things to do from the table options pop-up.

Help

The last option on the top of the catalog tab may be a context-sensitive help marker, which should bring you to this online help.

Table Columns

Clicking on the column names sorts the table by that column; clicking once sorts in ascending order, clicking a second time sorts in descending order, and clicking a third time returns the table to the original order. Small arrows appear next to the column names to remind you if the column is sorted in ascending or descending order.

⚠ Tips and Troubleshooting

• You can hide or display columns; click on the gears () to get to the table options, and tick the box corresponding to the row you want to hide or show.

Adding Columns

• Name of the column (required) -- it cannot have special characters like a minus sign or a percent symbol; you can only use letters, numbers, and underscores.
• Mode "Enter expression" or "Use preset function" -- options shown here correspond to "Enter expression" options; the preset function options are included in the last bullet here.
• Expression (required) -- using basic SQL operators, you can manipulate columns to create the new column. (See more on this below.)
• Data Type -- specify if your new column is a double precision floating point ("double"), a long integer ("long"), or a string ("char").
• Precision -- if you have selected "double" for data type, select how many decimal places your new column should display. For example, if you want the numbers to display as 1.23, enter "F2".
• Units -- specify the units of your new column. For more information, see IVOA documentation
• UCD, or unified content descriptor -- for VO compliance, add this for your new column. For more information, see IVOA documentation
• Description -- add a description for your new column.
• Select a preset -- if you select "Use preset function", you can choose (a) "set filtered rows to 'true' and the rest to 'false'", (b) "set selected rows to 'true' and the rest to 'false'", or (c) "number rows in current sort order". These options are useful for tagging items you have selected in myriad ways (from plots, images, complicated filters), or ordered in complicated ways. For example, if you have constructed a complicated filter, then you can create a column that is true for the selected rows; if you cancel the complicated filter, you can then easily recreate the complicated filter by simply filtering on your newly created column.

You need to use the column names exactly as they appear in your catalog. Supported operators are: +, -, *, /, =, >, <, >=, <=, !=, LIKE, IN, IS NULL, IS NOT NULL. You may use functions as well; for a list of all available functions, see here . Some examples (from the general case where these tables are used for catalogs) include:

• "w3mpro" - "w4mpro"
• sqrt(power("w3sigmpro",2) + power("w4sigmpro",2))
• ("ra"-82.0158188)*cos(radians("dec"))
• "phot_g_mean_mag"-(5*log10(1000/"parallax") - 5)

• When you create a new column that is calculated from other columns, it is created statically. That is, it is not dynamically updated like a spreadsheet, but calculated once and left alone after that.
• When you create a new column, the header of the new column is red to let you know that the column is not present in the original catalog.
• When you save the catalog, the header of the saved catalog indicates that you have added a column. When you load the catalog back into the tool, the header of the new column is still red.
• You can edit or delete columns after you have created them; click on the gears () to get to the table options, and then click on the edit icon to bring up a dialog box to edit or delete the column.
• You can hide columns; click on the gears () to get to the table options, and tick the box corresponding to the row you want to hide or show.
• If you create a new column that turns a floating point column into an integer with the "FLOOR()" function, you need to be sure to set the resulting column type to "long". For example, if you have data covering several days or years, and you have a column that is a floating-point MJD, you can convert it into an integer, e.g., via FLOOR(mjd) for days or FLOOR(mjd/365.24) for years, then you can use the drop-down filter menu for the new column to quickly compare different time ranges. But, the new column must be an integer (e.g., "long") in order for this to work properly.
• If you need to, say, take the square root of a column that occasionally has a negative number, and you want it to attempt to handle this in a physically reasonable manner, you can construct expressions like this for a column named 'col' that has some positive and some negative numbers: if("col">=0,sqrt("col"),-sqrt(-"col"))

Table Filters

For columns (fields) with a limited set of choices, on the right edge of the text entry box, an arrow appears; click on it to get a drop-down from which you can select the available choices. To implement the filter, make the choices, and click "Apply" when you are done. Click "clear" in the top of the drop-down menu to remove that filter.

Example: Your search results are a list of images, which may include science images, uncertainty images, coverage images, and more. Click on the filter icon, and click on the downard pointing arrow at the top of the "Type of Data" column. Select "science" and click "apply." The table is now limited to science images.

After you impose a filter, then the number of rows in the table is restricted according to the rules you have specified, and the "filters" icon on the top right of the catalog pane has changed to remind you that there has been a filter applied, in this case four filters: . To clear the filters, click on the cancel filters icon (which also appears after you impose filters): .

Filters can be used in combination. Note that the filters between columns are logically "AND"ed together, but filters within the same column can be logically "AND"ed or "OR"ed together; examples are below.

The available logical operators are :

• = which means 'equal to' (exactly!), e.g., the parameter on which you are querying (the column headers as shown) is exactly equal to this value you are specifying.
• > which means 'greater than'
• < which mean 'less than'
• != which means 'not equal to' (exactly!)
• >= which means 'greater than or equal to'
• <= which means 'less than or equal to'
• IN which means 'included within this list', e.g., the parameter on which you are querying is included within the list you are specifying (if the column filter is free-form text, type "value1,value2" and it will give you rows that have value1 or value2).
• LIKE which means 'resembles the text that is entered', e.g., the text resembles the text that you type in the box.
• IS which effectively is the same as =
• IS NOT which effectively is the same as !=

• Retain rows for which a certain parameter is not an empty string: !=''
• Retain rows for which a certain parameter is not NULL and is larger than 1.234: > 1.234 and IS NOT NULL
• Retain rows that have values between -0.5 and 1.25: > -05 and < 1.25
• Retain rows with a parameter greater than one value or exactly not equal to another value: > 12345 or != 3000
• Retain rows with a parameter equal to one of the values in a list: IN a,b,c,d

If you click on the table options icon (), you get a pop-up that includes a place to filter columns. Here is an example of the table columns for a WISE catalog that has been filtered to just have SNR>10 for each of the four bands:

You can type in constraints in the filter box in much the same way as you can from the catalog itself; note that the column description is included here, which may make this way of setting filters more useful when working with a new (to you) catalog.

The second tab is the advanced filter interface:

Here, the columns are listed alphabetically on the left, the constraints you have imposed are in the "current constraints" box, and you can apply additional SQL constraints via the free-form text box. Hints for syntax are given below the entry box. This window can be resized such that you can see the whole set of hints and imposed filters. Note that in this interface, column headers must be enclosed within double quotes.

Cancelling filters

After you impose a filter, then the "filters" icon on the top right of the catalog pane has changed to remind you that there has been a filter applied, in this case just one filter: To clear all the filters at once, click on the cancel filters icon (which also appears after you impose filters): .

⚠ Tips and Troubleshooting

• If you impose logically inconsistent restrictions such as "exposure_time > 160" and "exposure_time < 100" (">160;<100" in the filter box for a column called "exposure_time"), no data will result, because no data are (can be) both less than 160 seconds long and greater than 100 seconds long at the same time. However, "exposure_time > 160 or < 100" works just fine (">160 or <100" in the filter box for the column "exposure-time").
• If you impose nonsensical filters (like using a letter where a number should be, like "w1snr < f") then it will let you know that something has gone really wrong, and let you go back to fix it.
• However, a filter like "ph_qual < f" could be valid -- if the column with which you are working is a string, then a string is a valid filter. It is case-insensitive. For the ph_qual column in the 2MASS catalog, the values are always three letters, such as AAA or ABA or CUU. A filter like "ph_qual < f" will operate as if you have alphabetized the list. Any string that starts with A comes before F and so will be retained. If you do "ph_qual < BBB" then AAA will be left in, but so will "BAU", because alphabetically, BAU precedes BBB.
• If you impose filters from a plot, it can manifest as several filters on the catalog, e.g., one for each side of the square you have drawn on the plot. If you want to remove, say, just one of the four filters (rather than all of them by cancelling all filters), you can do so from the table options pop-up.
• If you want to copy all of the "current constraints", even if the entire field is not visible to you, you can click on the clipboard icon to copy the entire string, and then paste it into another field or application to see what it is.
• If you are choosing filters from a list of terms, cancelling those filters might not work the way it cavalierly seems like it should. If a down arrow appears next to the filter box, then a list of options you can select is available. Tick the boxes you want, and click "Apply" to apply the filter. Now, if you want to change the filter, click the down arrow, select different options, and click "Apply" again to re-impose the new filter. To remove the filter, you have to treat it like you would when applying a modified second filter -- unselect the choices, or hit 'clear', and then hit Apply again. If you deselect the choices and then click elsewhere in the window without hitting clear, your actions are interpreted as 'cancel without doing anything' as opposed to 'impose the new filter I just set' (which is 'cancel all filters'). When you are resetting the filter to be 'select nothing', it is treating that as a new filter setting, so you need to set up that filter and click 'Apply' in order for it to understand.
• If you impose filters from a plot, image, or table, you can cancel them from a plot, image, or table. That is, if you impose filters from a plot, and different additional filters from the image, when you click the 'cancel filters' icon from the table, all the filters are canceled at once. If you have filters imposed from multiple places, clicking on 'cancel filters' doesn't cancel just the filters imposed from that place; it cancels all of them. If you want to be able to reconstruct a complicated set of filters, though, you can add a column to your table that is one of the preset functions -- set it to true if the row is filtered. Then you can cancel all your filters at any time but you can easily recover the filtered data by filtering on that one new column.

Table Cells

If you click on the ellipsis, you get a drop-down menu:
from which you can choose to copy the cell value or view it in a pop-up window.

If you view it in a pop-up window, it will attempt to format it in a readable fashion:

which, for most cells, will be functionally indistinguishable from no special formatting. It will only matter for very complicated cells.

Saving Tables

You obtain this pop-up:

You have several choices to make. In order, they are:

File format

You can save the table in a variety of formats:

It defaults to saving it as an IPAC table file , which is basically ASCII text with headers explaining the type of data in each column, separated by vertical bars.

Other formats include comma-separated values (csv, suitable for, e.g., Excel), tab-separated values (tsv), and three different versions of VO tables . You can save the file in parquet file format , which is a highly efficient, compressed, column-oriented format for tabular data that has been adopted by many recent wide area survey projects. You can also save the file in DS9 Regions file format , although that makes very little sense in the Atlas tool.

File name

The tool tries to make a guess at a sensible filename. Feel free to change it to something that makes sense to you.

File location

You may save your file to a local file (on your disk) or, if you are logged in, in the IRSA Workspace .

Modifications to the table

Depending on what you have been doing to the table at this point, you may have filtered or added columns. If you want to save the table as it is currently displayed, with all filters as imposed and any columns hidden, and any added columns as shown, select "Save table as displayed." If you want to save the original table, with all rows and the original columns intact, choose "Save table as originally retrieved."