API

This page details the methods and classes provided by the playground.tv package. All sequences inherit from the Sequence, all frames inherit from the FrameBase, and all illustrations inherit from the IllustrationBase.

Sequences

All these sequences keep track of timed datasets.

playground.tv.sequences.make_sequence(initial, *args, **kwargs)

Initialize a Sequence for viewing with tv.

This is a general wrapper that tries to guess what kind of Sequence to make, based solely on the inputs. If this fails, you may need to specify the Sequence explicitly.

Parameters:

• initial ((many possible types)) –

  This is the input that initializes an image sequence.

  • single FITS filename, and an extension to use.
  • list of FITS filenames, and an extension to use.
  • a glob pattern to search for FITS files (and extension)
  • single FITS HDUList, and an extension to use.
  • list of loaded FITS HDULists, and an extension to use.
  • a Stamp object from the cosmics package.

• *args – Positional arguments will be passed on to whatever Sequence is initialized
• **kwargs – Keyword arguments will be passed on to whatever Sequence is initialized

class playground.tv.sequences.Sequence(name='generic', *args, **kwargs)

A sequence of one or more images, which can be viewed (and animated) in a tv frame.

N

How many elements are in this sequence?

cadence()

Returns:cadence – A typical cadence for the sequence. Return type:astropy Time

class playground.tv.sequences.FITS_Sequence(initial, ext_image=1, ext_primary=0, name='FITS', use_headers=True, use_filenames=False, filenameparser=<function qlp_filenameparser>, timekey=None, timeformat=None, **kwargs)

A sequence of FITS images, with a time associated with each.

Initialize a Sequence of FITS images. The goal is to create a list of FITS HDUs, one for each time.

Parameters:

• initial (many possible types) –

  This is a flexible type of input, which could be...

  • single FITS filename, and an extension to use.
  • list of FITS filenames, and an extension to use.
  • a glob-like search string containing ‘*’.
  • single FITS HDUList, and an extension to use.
  • list of loaded FITS HDULists, and an extension to use.

• ext_image (int) – The extension that is the image.
• ext_primary (int) – The extension that is the primary for the FITS.
• name (str) – The name of this sequence.
• use_headers (bool) – Should we extract (time) information from the headers?
• use_filenames (bool) – Should we extract (time) information from the filenames?
• filenameparser (function) – This function takes a filename as input, and returns a dictionary containing parsed keys and values derived from it.
• timekey (string) – Which temporal key should define the time axis?
• timeformt (string) – What’s the time format for defining the time axis?

N

How many elements are in this sequence?

class playground.tv.sequences.Stamp_Sequence(initial, name='Stamp', **kwargs)

Initialize a Sequence from a Stamp. (a Stamp is a custom, simplified version of a TPF)

Parameters:

• initial ((many possible types)) –

  -a single Stamp object -something that can initialize a Stamp

  A filename for a ‘.npy’ file. A list of FITS sparse_subarray files. A search path of FITS sparse_subarray files (e.g. containing *.fits)

• **kwargs (dict) – Keyword arguments are passed to Stamp(initial, **kwargs)

class playground.tv.sequences.TPF_Sequence(initial, name='TPF', **kwargs)

Initialize a Sequence from a Target Pixel File (see lightkurve).

Parameters:

• initial – -a TargetPixelFile object -a filename of a TargetPixelFile
• **kwargs (dict) – Keyword arguments are stored in self.keywords.

Frames

All these frames provide windows for displaying sequences.

class playground.tv.frames.FrameBase(name='', ax=None, data=None, illustration=None, plotingredients=[], **kwargs)

Initialize this Frame, which can be one (of multiple) frames in an Illustration. Before plotting, each frame needs to have an ax defined saying where it should be plotted and (generally) some data associated with it.

Parameters:

• name (str) – A name to give this Frame.
• ax (matplotlib.axes.Axes instance) – All plotting will happen inside this ax. If set to None, the self.ax attribute will need to be set manually before plotting.
• data (flexible) – It can be custom object (e.g. a Stamp), or simple arrays, or a list of HDULists, or something else, depending on what this actual Frame does with it in plot and update.
• illustration (an Illustration) – The illustration in which this frame will be embedded. We keep track of this (sometimes) because we might want information that’s shared across the whole illustration to be accessible to this individual frame when plotting.
• plotingredients (list) – A list of keywords indicating features that will be plotted in this frame. It can be modified either now when initializing the frame, or any time before calling i.plot() from the illustration.
• go nowhere (?) (**kwargs) –

offset

Get a time offset, to use as a zero-point.

Returns:offset – An appropriate time zero-point (in JD). Return type:float

plot()

This should be redefined in a class that inherits from FrameBase.

update(*args, **kwargs)

This should be redefined in a class that inherits from FrameBase.

class playground.tv.frames.imshowFrame(name='image', ax=None, data=None, title=None, plotingredients=['image', 'time', 'colorbar', 'arrows', 'title'], processingsteps=[], firstframe=None, cmapkw={}, **kwargs)

An imshow frame can show a sequence of images, as an imshow.

Initialize this imshowFrame, will can show a sequence of 2D images.

Parameters:

• name (str) – A name to give this Frame.
• ax (matplotlib.axes.Axes instance) – All plotting will happen inside this ax. If set to None, the self.ax attribute will need to be set manually before plotting.
• data (Image_Sequence) – Any Sequence that contains 2D images.
• title (str) – A string to display as the title of this frame. If nothing, this will try to pull a title out of the data, or leave it blank.
• plotingredients (list) – A list of keywords indicating features that will be plotted in this frame. It can be modified either now when initializing the frame, or any time before calling i.plot() from the illustration.
• cmapkw (dict) – Dictionary of keywords to feed into the cmap generation.

draw_arrows(origin=(0, 0), ratio=0.05)

Draw arrows on this Frame, to indicate the +x and +y directions.

Parameters:

• origin (tuple) – The (x,y) coordinates of the corner of the arrows.
• ratio (float) – What fraction of the (longest) axis should the arrows span?

plot(time=None)

Generate the (initial) plot for this frame.

Individual features can be modified afterwards, through the .ax (the plotted axes) or the .plotted (dictionary of plotted elements) attributes.

Parameters:time (astropy Time) – The time to plot, defaults to the first with None.

process_image(image)

Apply any extra processing steps to the image (subract a median image, normalize, mask, ???)

update(time)

Update this frame to a particular time (for use in animations).

class playground.tv.frames.EmptyTimeseriesFrame(name='timeseries', xlim=[None, None], ylim=[None, None], ylabel='', histogram=True, **kwargs)

An EmptyTimeseriesFrame has a vertical bar for time when animated.

The frame should be added to an illustration, the illustration should be plotted, and then data can be plotted into the ETF.ax and ETF.ax_hist frames.

Initialize an empty timeseries frame.

Parameters:

• name (string) – A custom name for this frame.
• xlim (tuple) – Set the xlimits. If None, wait for data to appear.
• ylim (tuple) – Set the ylimits. If None, wait for data to appear.
• ylabel (string) – Set a ylabel for this plot.
• histogram (bool) – Should we add an extra axis for a histogram?

class playground.tv.frames.ZoomFrame(source=None, position=(0, 0), size=(10, 10), name='zoom', cmapkw={}, plotingredients=['image', 'colorbar'], **kwargs)

Initialize a ZoomFrame that can display images taken from a zoomed subset of a source imshowFrame. This is kind of like a magnifying class you can drop down on an image.

Parameters:

• source (imshowFrame) – A frame into which this one will be zooming.
• position ((tuple)) – The (x, y) = (col, row) position of the center of zoom.
• shape ((tuple)) – The (x, y) = (ncols, nrows) shape of the zoom.
• name (str) – A name to give this Frame.
• ax (matplotlib.axes.Axes instance) – All plotting will happen inside this ax. If set to None, the self.ax attribute will need to be set manually before plotting.
• plotingredients (list) – A list of keywords indicating features that will be plotted in this frame. It can be modified either now when initializing the frame, or any time before calling i.plot() from the illustration.
• cmapkw (dict) – Dictionary of keywords to feed into the cmap generation.

class playground.tv.frames.LocalZoomFrame(source, position=(0, 0), size=(10, 10), zoom=10, **kwargs)

Initialize a ZoomFrame that can display images taken from a zoomed subset of a source imshowFrame. This is kind of like a magnifying class you can drop down on an image.

It doesn’t add a new axis.

Parameters:

• source (imshowFrame) – A frame into which this one will be zooming.
• position ((tuple)) – The (x, y) = (col, row) position of the center of zoom. (These are in original image coordinates, not those that have been transformed for display.)
• shape ((tuple)) – The (x, y) = (ncols, nrows) shape of the zoom.

class playground.tv.frames.CameraFrame(name='camera', ax=None, data=None, **framekw)

Initialize a CameraFrame. For plotting, this expects to see a full-frame image from a full camera (not split into CCDs.)

Parameters:

• name (str) – A name to give this Frame.
• ax (matplotlib.axes.Axes instance) – All plotting will happen inside this ax. If set to None, the self.ax attribute will need to be set manually before plotting.
• data (Image_Sequence) – Any Sequence that contains 2D images.
• **framekw (dict) – Passed to imshowFrame; check it out for more options.

class playground.tv.frames.CCDFrame(name='ccd', ax=None, data=None, camera=<camera Frame | data=<sequence of 0 images> | name=camera>, **kwargs)

This is an imshowFrame associated with one CCD. It can transform from CCD coordinates to Camera coordinates.

A single CCD can be created on its own, but more often it will be linked to a Camera, to continue the transformation onward from Camera to display.

Illustrations

All these illustrations provide layouts in which to place frames.

class playground.tv.illustrations.IllustrationBase(nrows=1, ncols=1, figkw={'figsize': None, 'dpi': None}, sharecolorbar=True, subplot_spec=None, **gridspeckw)

This contains the basic layout and organization for a linked visualization of images.

Other illustrations inherit from this basic one, changing the

Initialize an Illustration, setting up its figure and basic layout.

nrows

: int

The number of rows in the illustration.

ncols

: int

The number of columns in the illustration.

figkw

: dict

Keywords to pass along to create a figure.

**gridspeckw

: dict

Any extra keywords are passed to the gridspec

animate(filename='test.mp4', mintime=None, maxtimespan=None, cadence=<Quantity 1. s>, fps=30, dpi=None, **kw)

Create an animation from an Illustration, using the time axes associated with each frame.

This should be called after illustration.plot()

Parameters:filename (str) –

plot(*args, **kwargs)

Plot all the frames in this illustration.

*args, **kwargs are passed to frames’ .plot()

savefig(filename, **savefigkw)

Call plt.savefig, but make an announcement about it. This should be called after illustration.plot()

Parameters:

• filename (str) – Where should the figure be saved?
• are passed to savefig (**savefigkw) –

update(*args, **kwargs)

Update all the frames in this illustration.

*args, **kwargs are passed to the frames’ .update()

class playground.tv.illustrations.GenericIllustration(imshows=[], timeseries=[], imshowheight=1.0, imshowrows=1, sizescale=3, figsize=None, dpi=None, hspace=0.03, wspace=0.08, left=0.1, right=0.9, bottom=0.2, top=0.8, **illkw)

Initialize an illustration from list of frames.

Parameters:

• imshows (list) – A list of imshow frames, to be displayed in a row on the top.
• timeseries (list) – A list of timeseries frames, to be displayed in rows below.
• imshowheight (float) – How tall is the imshow, compared to the entire timeseries block?
• sizescale (float) – An overall size scale, in inches.
• figsize (tuple) – Override the automated figure size with your own, in inches.
• keywords are passed to IllustrationBase (**illkw) –

class playground.tv.illustrations.CameraIllustration(data=[], orientation='horizontal', sizeofcamera=4, subplot_spec=None, **framekw)

An illustration for displaying a single Camera (unrotated, untransformed).

Parameters:

• data (various) –

  Anything that can initialize a sequence with the make_sequence() helper function.

  or

  a dictionary with keys of ‘ccd1’, ‘ccd2’, ‘ccd3’, ‘ccd4’ that each contain something that can initialize a sequence

• orientation (str) – ‘horizontal’ = camera 2 is right of camera 1 ‘vertical’ = camera 2 is below camera 1
• sizeofcamera (float) – What’s the size, in inches, to display a single camera?
• passed to CameraFrame (**framekw) –

class playground.tv.illustrations.FourCameraIllustration(cam1=[], cam2=[], cam3=[], cam4=[], orientation='horizontal', sizeofcamera=4, subplot_spec=None, **kwargs)

For displaying a single Camera.

Parameters:

• etc... (cam1,) –

  Anything that can initialize a sequence with the make_sequence() helper function.

  or

  a dictionary with keys of ‘ccd1’, ‘ccd2’, ‘ccd3’, ‘ccd4’ that each contain something that can initialize a sequence

• orientation (str) – ‘horizontal’ = camera 2 is right of camera 1 ‘vertical’ = camera 2 is below camera 1
• sizeofcamera (float) – What’s the size, in inches, to display a single camera?

class playground.tv.illustrations.SingleCameraWithZoomIllustration(data=[], zoomposition=(0, 0), zoomsize=(10, 10), **kwargs)

For displaying a single Camera.

**kwargs are passed to both make_sequence and the frames

class playground.tv.illustrations.SideBySideIllustration(imshows=[], timeseries=[], width_ratios=[5, 1], each=1.0, hspace=0.15, wspace=0.08, left=0.15, right=0.95, bottom=0.3, top=0.9, fudge=1.2, **kwargs)

Initialize an illustration from list of frames.