Callables

Callables allow you to define your own functions for calculating a few of the style properties for stars: size, alpha (opacity), color, and the star's label. DSOs support callables for alpha and labels only. Starplot has a few basic callables built-in, but you can also create your own.

What's a Callable?

In Python, a "callable" is anything that can be "called" — e.g. a function or a class with __call__ implemented.

As a simple example, here's how you can pass a callable to Python's sorted function to sort a list of strings by their lengths:

>>> animals = ["elephant","cat", "dog", "tiger"]

>>> sorted(animals, key=lambda a: len(a))

['cat', 'dog', 'tiger', 'elephant']

In the example above, the value of key is the callable — in this case, a lambda function.

Here's another way to write the code above:

>>> animals = ["elephant","cat", "dog", "tiger"]

>>> def length(a):
...   return len(a)
...
>>> sorted(animals, key=length)

['cat', 'dog', 'tiger', 'elephant']

Example

Here's a basic example of using one of the built-in callables to colorize the stars based on their BV index:

from starplot.styles import PlotStyle, extensions
from starplot.map import Projection

import starplot as sp

style = PlotStyle().extend(
    extensions.GRAYSCALE_DARK,
    extensions.MAP,
)
p = sp.MapPlot(
    projection=Projection.MERCATOR,
    ra_min=3.4,
    ra_max=8,
    dec_min=-16,
    dec_max=25.6,
    style=style,
    resolution=2000,
)
p.stars(
    mag=12,
    color_fn=sp.callables.color_by_bv, # <-- here's where we specify the callable
)
p.dsos(mag=12, mag_null=True)
p.constellations()

p.export("orion_colored_stars.png", padding=0.25)

Creating Your Own Callable

Let's say you wanted to create a plot where the stars brighter than magnitude 4 should be colored blue and stars dimmer than that should be colored red. Here's a way to do that with a custom callable:

# first we define the callable:
def color_by_mag(star: Star) -> str:
    if star.magnitude <= 4:
        return "#218fef"
    else:
        return "#d52727"

# then to use your callable:
p = MapPlot(...)
p.stars(
    mag=12,
    color_fn=color_by_mag,
)

Every callable for stars is passed an instance of Star, so you can reference various properties of stars in your callables. Similarly, every callable for a DSO is passed an instance of DSO.

Built-In Callables

All of these are importable from starplot.callables

alpha_by_magnitude

alpha_by_magnitude(star: Star) -> float

Basic calculator for alpha, based on magnitude:

if magnitude < 4.6:
    alpha = 1
elif magnitude < 5.8:
    alpha = 0.9
else:
    alpha = (16 - m) * 0.09

color_by_bv

color_by_bv(star: Star) -> str

Calculates color by the object's B-V index

Color hex values from: Mitchell Charity

size_by_magnitude

size_by_magnitude(star: Star) -> float

Simple sizing by magnitude, using a step size of 1.

if mag <= 0:
    size = 3800
elif mag <= 1:  # 0..1
    size = 2400
elif mag <= 2:  # 1..2
    size = 1600
elif mag <= 3:  # 2..3
    size = 1000
elif mag <= 4:  # 3..4
    size = 600
elif mag <= 5:  # 4..5
    size = 300
elif mag <= 6:  # 5..6
    size = 120
elif mag <= 7:  # 6..7
    size = 60
elif mag <= 8:  # 7..8
    size = 40
else:           # > 8
    size = 20

size_by_magnitude_factory

size_by_magnitude_factory(
    threshold: float, over_threshold_size: float, base: float = 20
) -> Callable[[Star], float]

Creates a new version of size_by_magnitude_log with a custom threshold and base multiplier:

if magnitude >= threshold:
    size = over_threshold_size
else:
    size = base ** math.log(threshold - magnitude)

Parameters:

• threshold (float) –

  The threshold at which size will be a constant value. In other words, if an object's magnitude is more than or equal to this number, then its size will be the constant under_threshold_size

• over_threshold_size (float) –

  Size for objects that have a magnitude greater than or equal to the treshold

• base (float, default: 20 ) –

  Base for objects that have a magnitude less than the threshold

Returns:

• Callable[[Star], float] –

  A callable for calculating size based on magnitude

size_by_magnitude_for_optic

size_by_magnitude_for_optic(star: Star) -> float

Very simple sizer by magnitude for optic plots

size_by_magnitude_log

size_by_magnitude_log(star: Star) -> float

Calculates size by logarithmic scale of magnitude:

if magnitude >= 7.6:
    size = 2.36
else:
    size = 20 ** math.log(8 - magnitude)

size_by_magnitude_simple

size_by_magnitude_simple(star: Star) -> float

Very simple sizer by magnitude for map plots