Skip to content

Selecting Objects

When plotting stars, constellations, or deep sky objects (DSOs), you can select exactly which objects to plot by using expressions that reference fields on the object's model. Only the objects that satisfy ALL the conditions will be plotted.

Starplot uses Ibis for handling these expressions, so if you're familar with that library then you already have a head start on selecting data in Starplot.

Let's check out a simple example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
from starplot import MapPlot, Projection, _

# Create a simple map around Orion
p = MapPlot(
    projection=Projection.MERCATOR,
    ra_min=3 * 15,
    ra_max=8 * 15,
    dec_min=-16,
    dec_max=25,
)

# Plot all DSOs that satisfy two conditions:
#   1. Magnitude is less than 12
#   2. Size is greater than 0.08
p.dsos(
    where=[
        _.magnitude < 12,
        _.size > 0.08,
    ]
)

On line 15, we plot only the DSOs we want by passing the where keyword argument. This argument contains a list of expressions that describe which objects you want to plot. Only the objects that satisfy ALL of these conditions will be plotted. In this example, we plot all DSOs that have a magnitude less than 12 AND a size greater than 0.08 square degrees.

When building expressions, you use the underscore, _, to reference fields on the model. This is kind of a "magic variable" in Ibis (known as the Underscore API) which makes it easy to work with data and chain expressions together.

More Expression Examples

Select stars that have a non-null HIP id:

_.hip.notnull()

Select stars that have a HIP id OR have a bluish color (bv < 0):

(_.hip.notnull()) | (_.bv < 0)

Select stars with the names Sirius, Rigel, or Vega:

_.name.isin(["Sirius", "Rigel", "Vega"])

Select DSOs that have no defined size OR are larger than 0.01 square degrees:

(_.size.isnull()) | (_.size > 0.01)

Select stars that are within the Pleiades (M45) star cluster (assumes m45 = DSO.get(m='45')):

_.geometry.intersects(m45.geometry)

But wait, there's more!

Starplot supports all expressions from Ibis, so check out their documentation ↗ for more details.

Important Details

  • When writing expressions, you can reference any field on the model you're filtering
  • See table below for a list of operators you can use in your expressions
  • You can combine expressions with the bitwise OR (|) / AND (&) operators, but you must put parenthesis around each expression when doing this (e.g. (_.magnitude > 8) | (_.name == "Vega"))

Operators

Operator Description Example
<, <= Less than, less than or equal to _.magnitude < 8
>, >= Greater than, greater than or equal to _.magnitude >= 2
== Equals _.name == "Vega"
!= NOT equal _.name != "NGC1976"

There are also a few operators you can use to combine expressions:

Operator Description Example
| Logical OR (_.magnitude > 8) | (_.name == "Vega")
& Logical AND (_.magnitude < 8) & (_.size.is_not_null())

Important: When using operators to combine expressions, you must put each expression in parenthesis:

# Good ✅ 
(_.magnitude > 8) | (_.name == "Vega")

# Bad ❌ 
_.magnitude > 8 | _.name == "Vega"