Vizic API

Connection

class vizic.connection.Connection(host='localhost', port=27017, db='vis', url='http://localhost:8888/')

MongoDB connection wrapper at the front-end.

This object establish connections to the given database. Error will be thrown if fails, otherwise push the database information to the server through REST API.

Parameters:

• host (str) – The host name or address. Defaults to localhost.
• port (int) – The port that the specified database is listening to. Defaults to 27017.
• db – A MongoDB database to store or retrive data. Defaults to vis.
• url (str) – The address for the Jupyter server. This can be determined using NotebookUrl widget is not known. Defaults to http://localhost:8888/

Raises:

Exception – If initiating connection to specified database fails.

__init__(host='localhost', port=27017, db='vis', url='http://localhost:8888/')

Parameters:

• host (str) – The host name or address. Defaults to localhost.
• port (int) – The port that the specified database is listening to. Defaults to 27017.
• db – A MongoDB database to store or retrive data. Defaults to vis.
• url (str) – The address for the Jupyter server. This can be determined using NotebookUrl widget is not known. Defaults to http://localhost:8888/

Raises:

Exception – If initiating connection to specified database fails.

change_db(db)

Change the database used for Vizic

rm_catalog(collection, db='vis')

Remove all data associated with given catalog collection.

Parameters:

• collection (str) – The catalog collection to be removed.
• db (str) – The database that the collections are stored. Defaults to vis.

rm_circles(circles_id, db='vis')

Remove stored data for a CirclesOverLay.

Parameters:

• circles_id (str) – The name given to this particular CirclesOverLay.
• db (str) – The database that the data is stored. Defaults to vis.

show_catalogs(db='vis')

Show catalogs stored in a given database.

Parameters:db (str) – The MongoDB database to look for stored catalogs. Defaults to vis. Returns:A list of catalog collection names.

show_circles()

Show CirclesOverLay data stored in database.

Returns:A list of CirclesOverLay ids.

Map & Layers

class vizic.astroleaflet.AstroMap(**kwargs)

The map class, in charge of the overall operations.

AstroMap extends the Map class from ipyleaflet with added rich features to display and interact with visualized astronomical catalogs and custom overlays.

Note

Class attribute center is always in the form of [lat, lng].

Keyword Arguments:  

• zoom (int) – Initial zoom for the map. Defaults to 1.
• max_zoom (int) – Allowd maximum zoom level for the map. Defaults to 12.
• position_control (bool) – Whether to show projected mouse position on the left bottom corner of the map window. Defaults to True.
• fullscreen_control (bool) – Whether to allow full screen mode. Defaults to True.

Parameters:

**kwargs – Optional arguments for map settings.

__init__(**kwargs)

Parameters:**kwargs – Optional arguments for map settings.

add_layer(layer)

Add layer to map.

Parameters:layer – layer object to be added to the map.

center_map()

Reset the zoom and location of the map.

clear_layers()

Remove all existing layers from map.

fly_to(lnglat, zoom)

Set view of the map to a specified zoom and location.

Parameters:

• lnglat – A list containing the RA and DEC for target locations.
• zoom – An integer representing the target zoom level.

remove_layer(layer)

Remove layer from map.

Parameters:layer – layer object to be removed from the map.

class vizic.astroleaflet.GridLayer(connection, coll_name=None, **kwargs)

Base tilelayer class for hosting visualized catalogs.

Keyword Arguments:  

• df – A pandas dataframe where the data to be visualized is stored.
• min_zoom (int) – Minimum zoom level for the tileLayer. Defaults to 0.
• max_zoom (int) – Maximum zoom level for the tileLayer. Defaults to 8.
• collection (str) – The name for the MongoDB documents collection that stores pre-ingested data.
• color (str) – Preset color for visualized objects. Defaults to red.
• df_rad (int) – The raidus of the circles representing objects in the catalog when size information is provided. Defaults to 2.
• scale_r (float) – A float number indicating the scaling ratio for visualized objects. Defaults to 1.0.

Parameters:

• connection – A wrapper for MongoDB connections.
• coll_name (str) – The collection name for a new catalog to be ingested into the database. Default is None.
• **kwargs – Arbitrary keyword arguments.

__init__(connection, coll_name=None, **kwargs)

Parameters:

• connection – A wrapper for MongoDB connections.
• coll_name (str) – The collection name for a new catalog to be ingested into the database. Default is None.
• **kwargs – Arbitrary keyword arguments.

get_fields()

Return float properties in the catalog.

get_min_max(field)

Return the min/max value in specified catalog property.

Parameters:field – The name of the specified property. Raises:Exception – If the provided property is not a float property or such a property doesn’t exist in the catalog.

push_data(url)

Update server extension with newly displayed catalog.

Send basic information of this tileLayer using Rest API to the server for directing data request from the front-end.

Parameters:url (str) – The Jupyter server address.

Custom overlays

class vizic.astroleaflet.VoronoiLayer(gridLayer, **kwargs)

Voronoi Diagram Layer.

Using the catalog data displayed by the GridLayer to compute and display Voronoi Diagram.

Keyword Arguments:  

• color (str) – Color for the overlayed diagram. Defaults to #88b21c.
• svg_zoom (int) – Initial zoom for projecting the Voronoi diagram onto the screen. The higher the zoom the better the resolution and accuracy. Defaults to 5.

Parameters:

• gridLayer – A gridLayer instance.
• **kwargs – Arbitrary keyword arguments.

Raises:

Exception – If the gridLayer object doesn’t have a connected database.

__init__(gridLayer, **kwargs)

Parameters:

• gridLayer – A gridLayer instance.
• **kwargs – Arbitrary keyword arguments.

Raises:

Exception – If the gridLayer object doesn’t have a connected database.

class vizic.astroleaflet.DelaunayLayer(gridLayer, **kwargs)

Delaunay Triangulation Layer.

Using the catalog data displayed by the GridLayer to compute and display Delaunay Triangulation.

Keyword Arguments:  

• color (str) – Color for the overlayed Triangulation. Defaults to blue.
• svg_zoom (int) – Initial zoom for projecting the Delaunay triangulation onto the screen. The higher the zoom the better the resolution and accuracy. Defaults to 5.

Parameters:

• gridLayer – A gridLayer instance.
• **kwargs – Arbitrary keyword arguments.

Raises:

Exception – If the gridLayer object doesn’t have a connected database.

__init__(gridLayer, **kwargs)

Parameters:

• gridLayer – A gridLayer instance.
• **kwargs – Arbitrary keyword arguments.

Raises:

Exception – If the gridLayer object doesn’t have a connected database.

class vizic.astroleaflet.HealpixLayer(gridLayer, **kwargs)

Healpix grid Layer.

Using the catalog data displayed by a given tileLayer to compute and display Healpix pixelization grid.

Keyword Arguments:  

• color (str) – Color for the overlayed Healpix grid. Defaults to white.
• svg_zoom (int) – Initial zoom for projecting Healpix grid onto the screen. The higher the zoom the better the resolution and accuracy. Defaults to 5.

Parameters:

• gridLayer – A gridLayer instance.
• **kwargs – Arbitrary keyword arguments.

Raises:

Exception – If the gridLayer object doesn’t have a connected database.

__init__(gridLayer, **kwargs)

Parameters:

• gridLayer – A gridLayer instance.
• **kwargs – Arbitrary keyword arguments.

Raises:

Exception – If the gridLayer object doesn’t have a connected database.

inject_data(gridLayer)

Import computed Healpix grid into the database

class vizic.astroleaflet.CirclesOverLay(gridLayer, name, **kwargs)

Circles overlay class.

Overlay a group of circles using data provided in a pandas dataframe or a document ID for stored data in the database.

Keyword Arguments:  

• color (str) – Color for the overlayed circles. Defaults to purple.
• svg_zoom (int) – Initial zoom for projecting circles onto the screen. The higher the zoom the better the resolution and accuracy. Defaults to 5.
• df – A pandas dataframe containing the positions for the circles to be drawn. Raidus for these circles could also be specified here.
• raidus (int) – The raidus of the circles drawn measured in pixels. Defaults to 50 pixels.
• cols – A list indicating the position columns name. Defauts to [RA, DEC]. A third entry can be provided to indicate the radius column.

Parameters:

• gridLayer – A gridLayer instance.
• name – The document ID for data stored in the database or a new user-defined ID for new data.
• **kwargs – Arbitrary keyword arguments.

__init__(gridLayer, name, **kwargs)

Parameters:

• gridLayer – A gridLayer instance.
• name – The document ID for data stored in the database or a new user-defined ID for new data.
• **kwargs – Arbitrary keyword arguments.

inject_data(document_id)

Import data to the database

class vizic.astroleaflet.MstLayer(gridLayer, neighbors=15, **kwargs)

Minimum spanning tree (MST) overlay class.

Layer class for MST computed using the catalog visualized by the base tileLayer with added features to cut the tree by maximum edge length and minimum branch size (the number edges in a branch).

Keyword Arguments:  

• color (str) – Color for the overlayed MST. Defaults to #0459e2.
• svg_zoom (int) – Initial zoom for projecting MST onto the screen. The higher the zoom the better the resolution and accuracy. Defaults to 5.

Note

To speed the calculation, Vizic retains the index of non-zero element in the MST sparse matrix.

Parameters:

• gridLayer – A gridLayer instance.
• neighbors – Vizic uses kneighbors_graph from sklearn to compute spanning trees for each set of points. The higher the number of neighbors used, the higher the precision.
• **kwargs – Arbitrary keyword arguments.

Raises:

Exception – If the gridLayer object doesn’t have a connected database.

__init__(gridLayer, neighbors=15, **kwargs)

Note

To speed the calculation, Vizic retains the index of non-zero element in the MST sparse matrix.

Parameters:

• gridLayer – A gridLayer instance.
• neighbors – Vizic uses kneighbors_graph from sklearn to compute spanning trees for each set of points. The higher the number of neighbors used, the higher the precision.
• **kwargs – Arbitrary keyword arguments.

Raises:

Exception – If the gridLayer object doesn’t have a connected database.

cut(length, members)

Cut the MST.

Parameters:

• length (float) – Maximum edge length.
• members (int) – The minimum number of edges in each saved branch.

get_data()

Retrive the MST edges data from the database.

get_index()

Retrive the index of the saved MST matrix

inject_data(neighbors)

Calculate and import MST data into the database.

Control Widgets

Classes in this modules are used to create widgets to interact with visualized catalogs.

class vizic.control_widgets.CFDropdown(layer, **kwargs)

Dropdown menu for selecting colormapping field.

Extends Dropdown class from ipywidgets.

Parameters:

• layer – The tileLayer that the menu is associated with.
• **kwargs – Arbitrary keyward arguments for Dropdown.

__init__(layer, **kwargs)

Extends Dropdown class from ipywidgets.

Parameters:

• layer – The tileLayer that the menu is associated with.
• **kwargs – Arbitrary keyward arguments for Dropdown.

link()

Link the value of the dropdown to c_field in tileLayer

unlink()

Unlink for provided tileLayer

class vizic.control_widgets.ColorMap(gridlayer, **kwargs)

Dropdown menu for selecting colormapping color space.

Extends Dropdown class from ipywidgets.

Parameters:

• gridlayer – The base tileLayer the widget is associate with.
• **kwargs – Arbitrary keyward arguments for Dropdown.

__init__(gridlayer, **kwargs)

Extends Dropdown class from ipywidgets.

Parameters:

• gridlayer – The base tileLayer the widget is associate with.
• **kwargs – Arbitrary keyward arguments for Dropdown.

class vizic.control_widgets.FilterBox(layer, field, *pargs, **kwargs)

A box layout wrapping a FilterSlider object.

Extends Box from ipywidgets.

Parameters:

• layer – A gridLayer instance.
• field (str) – The property field of the catalog that the slider will use for filtering.
• *args – Variable length argument list for Box.
• **kwargs – Arbitrary keyword arguments for Box.

__init__(layer, field, *pargs, **kwargs)

Extends Box from ipywidgets.

Parameters:

• layer – A gridLayer instance.
• field (str) – The property field of the catalog that the slider will use for filtering.
• *args – Variable length argument list for Box.
• **kwargs – Arbitrary keyword arguments for Box.

class vizic.control_widgets.FilterSlider(layer, field, **kwargs)

RangeSlider widget for filering displayed objects.

Ranges for selected field are automatically displayed on the slider. Move the bars to filter out unwanted objects.

readout_format

str – The format of the float numbers, which show the value range of a particular property, on the slider.

Extends FloatRangeSlider from ipywidgets.

Parameters:

• layer – A gridLayer instance.
• field (str) – The property field of the catalog that the slider will use for filtering.
• **kwargs – Arbitrary keyword arguments for FloatRangeSlider.

__init__(layer, field, **kwargs)

Extends FloatRangeSlider from ipywidgets.

Parameters:

• layer – A gridLayer instance.
• field (str) – The property field of the catalog that the slider will use for filtering.
• **kwargs – Arbitrary keyword arguments for FloatRangeSlider.

link()

Link slider values with the filter_range from tileLayer.

unlink()

Unlink from the provided tileLayer.

class vizic.control_widgets.FilterWidget(layer, *pargs, **kwargs)

A Dropdown menu and a rangeSlider wrapped in a box layout.

Select the field for filtering objects and perform the filter action in one widget. The map will reset when a new field is chosen.

Extends Box from ipywidgets.

Two links are created: 1) link the dropDown menu with the filter_field attribute from the tileLayer. 2) link the filter_obj attribute from the tileLayer to the _active status attribute in this widget. :param layer: A gridLayer instance. :param *args: Variable length argument list for Box. :param **kwargs: Arbitrary keyword arguments for Box.

__init__(layer, *pargs, **kwargs)

Extends Box from ipywidgets.

Two links are created: 1) link the dropDown menu with the filter_field attribute from the tileLayer. 2) link the filter_obj attribute from the tileLayer to the _active status attribute in this widget. :param layer: A gridLayer instance. :param *args: Variable length argument list for Box. :param **kwargs: Arbitrary keyword arguments for Box.

link()

Link the slider with the provided tileLayer.

unlink()

Unlink slider from the tileLayer.

class vizic.control_widgets.GetDataButton(layer, **kwargs)

Getting selected data.

Clicking this button to query the database for data selected using the lasso-like selection tool.

Extends Button from ipywidgets.

Parameters:layer – The tileLayer that the button is asccoiate with.

__init__(layer, **kwargs)

Extends Button from ipywidgets.

Parameters:layer – The tileLayer that the button is asccoiate with.

class vizic.control_widgets.HomeButton(map, **kwargs)

Home button Widget

Reset the map to initial zoom level and center.

Parameters:

• map – An AstroMap object, which the widget is intended to control.
• **kwargs – Arbitrary keyward arguments for Button.

__init__(map, **kwargs)

Parameters:

• map – An AstroMap object, which the widget is intended to control.
• **kwargs – Arbitrary keyward arguments for Button.

handle_click(b)

Reset the map

class vizic.control_widgets.LayerColorPicker(**kwargs)

Layer colorpicker widget.

layer

The layer of which the color is being controlled by the picker.

link(layer)

Link the colorpicker to the layer.

Used directional link from value attribute to the color attribute of the target layer object.

unlink()

Unlink colorpicker and layer.

class vizic.control_widgets.NotebookUrl(**kwargs)

Widget to get Jupyter server url.

The actural url of the Jupyter server is assigned to class variable nb_url after the widget being rendered.

Public constructor

class vizic.control_widgets.PopupDis(**kwargs)

Popup display Widget

layer

The base tilelayer that the widget is monitoring.

Initiate the widget object create a direction link

The link is from the obj_catalog attribute of the layer object to the data attribute in this widget.

__init__(**kwargs)

Initiate the widget object create a direction link

The link is from the obj_catalog attribute of the layer object to the data attribute in this widget.

class vizic.control_widgets.SelectionTrig(map, **kwargs)

A control widget to trigger lasso selection

Extends ToggleButton from ipywidgets.

Parameters:

• map – An AstroMap map object that the trigger widget is associated with.
• **kwargs – Arbitray keyword arguments for ToggleButton.

__init__(map, **kwargs)

Extends ToggleButton from ipywidgets.

Parameters:

• map – An AstroMap map object that the trigger widget is associated with.
• **kwargs – Arbitray keyword arguments for ToggleButton.

link()

Link the trigger to target AstroMap object

unlink()

Unlink from the provided AstroMap

Utils

The following functions are responsible for generating and modifying Minimum Spanning Tree and HEALPix Grids from a given dataset.

vizic.utils.cut_tree(mst_index, length, member)

Find the index for saved edges after a cut.

Note

At the frond-end all edges in a MST are stored in a JavaScript array and this function only returns the indexes for wanted edges.

Parameters:

• mst_index – A tuple of arrays indicating the indexes and values for the MST sparse matrix.
• length (float) – The maximum length for edges in a trimmed tree. All edges above are cutted off.
• member (int) – Minimum number of edges required in a saved branch. All branches having less members are removed in the final tree.

Returns:

A list of integers representing the index for saved edges.

vizic.utils.get_m_index(df)

Find the index from a given dataframe of MST edges.

Parameters:df – A pandas dataframe of MST edges. Returns:A tuple of arrays storing the indexes and values of non-zero elements in the MST sparse matrix.

vizic.utils.get_mst(df, neighbors)

Compute the Minimum Spanning Tree (MST) from postions.

This function takes a pandas dataframe of poistions and compute the distances to k-neighbors for all poistions given, then find the MST using scipy.sparse.csgraph. Finally finds the non-zero elements in a returned sparse matrix.

Parameters:

• df – A pandas dataframe all positions with longitude as RA and latitute as DEC.
• neighbors (int) – The number of neighbors used when computing tress.

Returns:

A pandas dataframe for all edges in the MST and a tuple of arrays storing the indexes and values of non-zero elements in the MST sparse matrix.

vizic.utils.get_vert(pixel, nside, nest)

Get the coordinates for the vertices for a single Healpix index for a given resolution (nside) and schema (nest)

Parameters:

• All arguments are required (*) –
• pixel (int) – Healpix index
• nside (int) – Healpix resolution given by nside parameters for the input pixel
• nest (bool) – Pixelization schema, True: Nested Schema, False: Ring Schema

Returns:

Two lists with the RA and DEC positions for the vertices for the given pixel.

vizic.utils.get_vert_bbox(llra, lldec, urra, urdec, nside, nest)

Get a list of the vertices for all Healpix pixels inside a given bounding box, resolution and pixelization schema.

Parameters:

• llra (float) – Lower left RA for the bounding box.
• lldec (float) – Lower left DEC for the bounding box.
• urra (float) – Upper right RA for the bounding box.
• urdec (float) – Upper right DEC for the bounding box.
• nside (int) – Healpix resolution given by nside.
• nest (bool) – Pixelization schema, True: Nested Schema, False: Ring Schema

Returns:

A list with the vertices for all pixels inside the bounding box.

vizic.utils.is_inside_bbox(ra, dec, llra, lldec, urra, urdec)

Find whether a point is inside a bounding box.

Parameters:

• ra (float) – Right ascension of the query point.
• dec (float) – Declination of the query point.
• llra (float) – Lower left RA for the bounding box.
• lldec (float) – Lower left DEC for the bounding box.
• urra (float) – Upper right RA for the bounding box.
• urdec (float) – Upper right DEC for the bounding box.

Returns:

A Bool whether the point is inside the bounding box.

TODO: Use ray tracing for any polygon shape