The Filter and Query Language

Overview

The Kepler Data Explorer has been designed with two goals in mind: to make access to the Kepler Database fun and straightforward, and to enable users to quickly build customizable, powerful, and useful filters and views of the dataset. This latter, more advanced feature, is made possible through a simple query language that is built into the table and plotter components. Advanced users who would like to leverage the full flexibility of the Kepler Data Explorer should peruse this section of the documentation to familiarize themselves with the query language.

The query language is used in two distinct contexts: to construct filters and to combine and transform planet properties to create new quantities. The former is used in the Table and Plotter to select a subset of planets to view, the latter is used in the plotter to produce scatter plots and histograms of combinations of planet properties and in the table to construct custom columns.

Example Queries

Perhaps the simplest way to introduce the query language is to present some examples. If you would rather jump to a list of available operations and functions skip to below.

Example Filters

• The filter:

  RPLANET < 2

  selects all planets with radii smaller than 2 earth radii. Note that the Column ID RPLANET is used to refer to the planet radius. The table in the column definitions help page can be used to lookup column IDs for all KOI properties in the Kepler dataset.

• The filter:

  19 < RA AND RA < 19.5 AND 40 < DEC AND DEC < 42

  selects all planets with coordinates lying in the range 19<Right Ascension<19.5 and 40<Declination<42. The query language supports the three basic boolean operations: AND, OR, and NOT. The equivalent notation &&, ||, and ! can also be used.

• The filter:

  PER[yrs] >= 1

  selects all planets with orbital periods (PER) greater then or equal to 1 (Earth) year. This filter illustrates the use of basic unit conversion in the query language. The default unit for orbital period is days, however an alternate set of units can be requested by passing the relevant unit ID in square brackets. Of course, the chosen unit must be valid -- see the section on units below for more details and for a table of unit IDs.

  Of course this filter is equivalent to

  PER >= 365

  Alternatively one could scale the PER property directly:

  PER/365 >= 1

  in fact, the Exoplanet Query Language allows for arbitrary mathematical combinations of property IDs and numbers. Addition (+), division (-), multiplication (*), division (/), and exponentiation (^) are all supported.

• The filter:

  UPER/PER<=1e-5 AND UPER>0

  selects all planets with periods accurate to within 1 part in 10^-5. Note that planet properties can be combined mathematically enabling us to take the ratio of the uncertainty in the orbital period (UPER) to the period (PER). We include UPER>0 to ensure that planets without period uncertainties are not included in the cut.

• The filter:

  CONFIRMED

  selects all KOI systems that are confirmed planetary candidates. To select KOI that are both confirmed and strong candidates one can combine the CONFIRMED and STRONG columns:

  CONFIRMED || STRONG

  or even

  !(MODERATE || NEEDS_FOLLOWUP)

  alternatively, one can use the VETTING_FLAG column as follows:

  VETTING_FLAG <= 2

  this works because confirmed planets have VETTING_FLAG = 1 and strong candidates have VETTING_FLAG = 2

• The filter:

  N_OBJ >= 3

  selects all KOI systems containing 3 or more KOIs. It is important to understand that the KOI is the fundamental object stored in the Kepler database -- there are no stellar objects; rather, all stellar system information is stored in KOI objects such that KOI orbiting the same star have the relevant stellar information duplicated amongst them. Thus to select all systems containing 3 or more KOI one must select all KOI with N_OBJ >= 3.

  One can emulate stellar searches by first restricting the Database to pick out the first KOI for each system (those KOI's with KOI = XX.01). One way to do this would be to use the filter:

  KOI_OBJ = 1

  This matches all objects with KOI ID's of the form XX.01. KOI_OBJ picks out the object component of the KOI ID. More intuitively, however, one can use the FIRST_OBJECT column to quickly select the first KOI subset of the database. Since FIRST_OBJECT is a boolean flag the filter is simply:

  FIRST_OBJECT

• The (complicated) filter:

  sqrt((RA[deg]-19*15)^2+((DEC[deg]-41)*cos(RA[rad]))^2)<1

  selects all planets that lie (roughly) within one degree of the coordinate RA=19h, DEC=41°. This is accomplished by computing the angular distane in degrees between each planet's RA and DEC coordinate and the point (285, 41) using the spherical coordinate metric. Note the use of the sqrt and cos functions. The query language supports a number of common mathematical functions.

Example Custom Properties

All of the above examples combine and compare planet properties in order to ultimately produce a true or false cut on each planet in the Kepler database. This behavior is appropriate in the context of filters. The query language is also used, however, when constructing custom scatter and histogram plots in the Plotter and custom columns in the table. In this context, KOI properties can be combined mathematically in order to yield a new numerical quantity for each KOI. This quantity can then be plotted against other numerical quantities, or presented in the table. Here are some examples:

• The quantity:

  RPLANET[rearth]^3

  approximates the planetary mass (in earth mass units) of the KOI assuming an earth-like density.

• The quantity:

  2*pi*A[m]/PER[s]

  computes the KOI's orbital velocity in units of meters-per-second.

Supported Operations and Functions

The following operations and functions are supported by the query language.

Supported Mathematical Operators

Symbol	Operation	Example
+	Addition	RA + 10
-	Subraction	RA - 10
*	Multiplication	2*A
/	Division	UPER/PER
%	Modulo	N_OBJ%2
^,**	Exponentiation	A^2 or A**2

Supported Comparison Operators

Symbol	Operation	Example
>	Greater-than	DEC > 30
<	Less-than	DEC < 50
>=	Greater-than-or-equal-to	N_OBJ >= 3
<=	Less-than-or-equal-to	N_OBJ <= 3
=,==	Equal-to	N_OBJ = 2 or N_OBJ == 2
!=	Not-equal-to	N_OBJ != 2

Supported String Comparison Operators

Note: all string comparisons are case-insensitive.

Symbol	Operation	Example
CONTAINS	Subset matching: returns true if any part of the string on the left hand side matches the string on the right hand size	VETTING_STATUS CONTAINS "Candidate"
==	Identical matching: returns true if the left hand side and right hand side match exactly	VETTING_STATUS == "Strong Candidate"

Supported Boolean Operators

Symbol	Operation	Example
&&, AND	Logical and	DEC > 42 && DEC < 44 or DEC > 42 AND DEC < 44
||, OR	Logical or	N_OBJ == 2 || N_OBJ == 3 or N_OBJ = 2 OR N_OBJ = 3
!, NOT	Logical not	!(RECON && ADAPTIVE) or NOT (RECON AND ADAPTIVE)

Supported Functions

Symbol	Operation
abs(x)	Absolute Value
asin(x)	Inverse Trigonometric Sine, returns radians
acos(x)	Inverse Trigonometric Cosine, returns radians
atan(x)	Inverse Trigonometric Tangent, returns radians
atan2(y,x)	C-like arctangent, takes two arguments and returns radians
sin(x)	Trigonometric Sine, accepts radians
cos(x)	Trigonometric Cosine, accepts radians
tan(x)	Trigonometric Tangent, accepts radians
ceil(x)	Takes the ceiling of the passed in number
floor(x)	Takes the floor of the passed in number
round(x)	Rounds the passed in number
exp(x)	Exponential function
log(x), ln(x)	Natural Logarithm (i.e. ln)
log10(x)	Log base 10
sqrt(x)	Square root function
max(x,y)	Returns the larger of x and y
min(x,y)	Returns the smaller of x and y

Support Constants

Symbol	Description
pi	pi = π = 3.14159....
true	The boolean value true
false	The boolean value false
NaN	The special not-a-number value NaN
inf, infinity	Infinity

Units

The query language allows for basic unit conversions for columns that have associated units.

Physical Class	Unit	Unit ID
Time	Seconds	s
	Minutes	min
	Hours	hrs
	Days	days
	Years	yrs
Length	Centimeters	cm
	Meters	m
	Kilometers	km
	Astronomical Units (AU)	au
	Light Years	ly
	Parsecs	pc
	Earth Radii	rearth
	Jupiter Radii	rjupiter
	Solar Radii	rsun
Mass	Grams	g
	Kilograms	kg
	Earth Mass	mearth
	Jupiter Mass	mjupiter
	Solar Mass	msun
Volume	Centimeters3	cm^3
	Meters3	m^3
Concentration	Parts-per-million	ppm
	Percentage	percent
Angle	Degrees	deg
	Radians	rad
	Hours	hr
	Arcseconds	arcsec
	Milliarcseconds	marcsec
Temperature	Kelvin	K
	Celcius	C
	Fahrenheit	F