Flags Tutorial

How do I...

Find out if SDSS's imaging data for an object are reliable?

Introduction

The SDSS does automatic processing to determine the reliability of the imaging data for each of the 300 million objects that it has seen. The reliability data are referred to as flags. You can view flags for any object through the SDSS's Catalog Archive Server (CAS); the flags are stored in the PhotoObj table in the CAS database. Understanding the flags is extremely important for doing science, so that you can understand what data are reliable.

In the Algorithms pages there are more detailed descriptions of the flags and our recommendations on how to use them. This tutorial shows you some examples of using these flags.

By using several flags together, you can search for only objects that have clean photometry. (skip to clean photometry search guide)

Flags are yes/no parameters (see the bitmask page). If a certain flag (such as Saturated) is present for an object, the object possesses that characteristic (i.e. its image is saturated). To save space in the database, the flags are stored as zeros (absent) or ones (present). Each object has a long bitwise number associated with it, where each set of digits corresponds to one flag. The CAS database includes functions that translate back and forth between the binary numbers and the flag names.

You can view flag names directly with the Explore tool, but to work with flags in search results, you will need to know how to use the translate functions.

Use the Explore tool to look at a single object. See the How do I get an image of my favorite object? tutorial to learn how to use the Explore tool.
Look at flags, the third row of data just below the object's coordinates. You will see the object's flags listed, one after the other with one space in between. See the list of flags in the Schema Browser for what they mean. Instructions for using the Schema Browser are in the next section, Interpret Flags.

Interpret Flags

Use the Schema Browser to study the list of the SDSS's flags.
Type flags into the Search window and click Go.
Results of your search will show up in the right-hand window of the Schema Browser. Click on the very first PhotoObj link, next to the name flags. You will go to the schema browser entry for the PhotoObj view.
The 13^th entry in the table is flags. Click on the (NEED A LOCAL VERSION OF THIS IMAGE) link to the right of flags.
The Data Values table shows the name, value, and description of each flag. Name is the name of the flag; this is what you will see in the Explore tool. Value is the bitmask value for the flag. Description is a short description of what the flag means.
The Access Functions, fPhotoFlags and fPhotoFlagsN, are needed to use the flag names in SQL queries.

Search for Flags in a Query

You can search through flags as part of your searches with the Imaging Query Form. You can request that the tool return only objects that possess one or more flags, such as searching for moving objects by looking for the MOVED flag. Or you can search for only those objects that do not possess certain flags, such as searching for unsaturated objects by checking that the SATURATED flag is off.

Go to the Imaging Query Form. From the astronomers' main page, look under Search Tools. For more on how to use the Imaging Query Form, see the guide How do I find data for all objects in a given RA/Dec/Magnitude/Absolute Magnitude range?
Select any parameters you like on the form, then look at the Obj Flags drop-down menus at the bottom of the form.
To guarantee that your results will possess a certain flag, select the flag from the At least one of these flags ON menu. To select more than one flag to check, hold down the CTRL key while selecting.
To guarantee that your results will not possess a certain flag, select the flag from the All of these flags OFF menu. To select more than one flag to check, hold down the CTRL key while selecting.
The flags will not show up in the search results unless you specifically request them in the Imaging menu of the Parameters to Return section above. But the flags will be searched, and the search will return only objects that meet your flag criteria.
Click Submit Request to send your query to the database.

Search for Flags with SQL

You can also search through flags as part of your searches using SQL. SQL searches will search for and return flags as long decimal numbers that have been converted from binary - but you translate between these numbers and the flag names with the functions dbo.fPhotoFlags and dbo.fPhotoFlagsN.

Go to the SQL Search tool, under the Search menu. To get there from the astronomers' main page, look under Search Tools. To get there from the public main page, look for Search under SkyServer tools.
To constrain your search based on flags, add one of the following to the WHERE block of your query:
1. To find only objects for which a certain flag is present:
  
  WHERE (p.flags & dbo.fPhotoFlags('flag')) > 0
  
  Replace flag with the name of the flag you want to search. For example, this query will find IDs and positions of objects that have been flagged as having moved:
  
  SELECT objid, ra, dec FROM photoTag WHERE (flags & dbo.fPhotoFlags('MOVED')) > 0
2. To find only objects for which a certain flag is absent:
  
  WHERE (p.flags & dbo.fPhotoFlags('flag')) = 0
  
  Replace flag with the name of the flag you want to search. For example, this query will screen out IDs and positions of objects that have been flagged as not being saturated:
  
  SELECT objid, ra, dec FROM photoTag WHERE (flags & dbo.fPhotoFlags('SATURATED')) = 0

Search for Objects with Clean Photometry

By using several flags together, you can limit your searches to return only objects that have clean photometry, thereby ensuring that you have a good sample. The flags you use differ depending on whether you are looking at stars or extended objects.

The queries below run slowly. These are test versions that use TOP 10 to return only the first 10 matching objects. To return all matching objects, remove the top 10 and use the CasJobs batch query system, which lets you run queries that take up to 8 hours. Also, note that lines that start with "--" are comments that are not executed as SQL statements.

For stars, use the following query to return IDs, positions, colors, and flags:

SELECT TOP 10 objid, ra, dec, u, g, r, i, z,
dbo.fPhotoFlagsN(flags) as flags
FROM star
WHERE ((flags & 0x10000000) != 0)  -- detected in BINNED1
AND ((flags & 0x8100000c00a4) = 0) -- not EDGE, NOPROFILE, PEAKCENTER,
                                   -- NOTCHECKED, PSF_FLUX_INTERP, SATURATED, or BAD_COUNTS_ERROR
AND (((flags & 0x400000000000) = 0) OR (psfmagerr_g <= 0.2))
                                   -- not DEBLEND_NOPEAK or small PSF error
                                   -- (substitute psfmagerr in other band as appropriate)
AND (((flags & 0x100000000000) = 0) OR (flags & 0x1000) = 0)

For extended objects, use the following query to return IDs, positions, colors, and flags:

SELECT TOP 10 objid, ra, dec, u, g, r, i, z,
dbo.fPhotoFlagsN(flags) as flags
FROM galaxy
WHERE ((flags & 0x10000000) != 0)  -- detected in BINNED1
AND ((flags & 0x8100000c00a0) = 0) -- not NOPROFILE, PEAKCENTER,
                                   -- NOTCHECKED, PSF_FLUX_INTERP, SATURATED, or BAD_COUNTS_ERROR
                                   -- if you want to accept objects with interpolation problems for PSF mags,
                                   -- change this to: AND ((flags & 0x800a0) = 0)
AND (((flags & 0x400000000000) = 0) OR (psfmagerr_g <= 0.2))
                                   -- not DEBLEND_NOPEAK or small PSF error
                                   -- (substitute psfmagerr in other band as appropriate)
AND (((flags & 0x100000000000) = 0) OR (flags & 0x1000) = 0)
                                   -- not INTERP_CENTER or not COSMIC_RAY omit this AND clause if you
                                   -- want to accept objects with interpolation problems for PSF mags.

You might also want to see SkyServer examples, such as this one and this one

A Shortcut: the "clean" flag

Finally, the photometric catalogs have a special flag called clean for each object, which contains an evaluation of whether the object is "clean" photometry. This definition is described in detail in our recommended flags documentation. (It differs slightly from the example directly above, an example of how different use cases can result in different decisions about what exactly is the set of "good" data).

Using clean is simple; to get a set of clean photometry you can just say in CASJobs or SkyServer:

  SELECT TOP 100 ra, dec FROM photoObj
  WHERE clean = 1