{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Getting Started"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"**Vizic** uses MongoDB for data storage, and an added Jupyter server extension to direct catalog request to the database. Therefore the server extension needs to be specified when starting the Jupyter Notebook App from the command line."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To start the Notebook App:\n",
"\n",
"\tjupyter notebook --NotebookApp.nbserver_extensions=\"{'vizic.mongo_ext.extension':True}\""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"In addition, a running MongoDB instance is requied. To start a new instance on the local machine, enter the following command in a new terminal window:\n",
" \n",
" mongod"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"On Linux machines, MongoDB instance can be also started with:\n",
"\n",
" sudo service mongod start"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"\n",
"**Note:** \n",
"\n",
"Before starting a MongoDB instance, the directory of dabase files must exist. The default path is \"/data/db/\". If such path doesn't exist, errors will be thrown by MongoDB. In some cases, you might experience difficulties starting an instance due to permission issue or file lock, the solution would be specify a new directory for data storage using the command \n",
"\n",
" mongod --dbpath /custom/path/\n",
"\n",
"
"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"After the MongoDB database and the Jupyte App are setted up, we can start to work with **Vizic**. Some basic features are deomnstrated below, for more indepth exmaples and a demo dataset, please check out the repository on GitHub."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Connection"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"from vizic import *\n",
"import pandas as pd\n",
"import numpy as np\n",
"from ipywidgets import *"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If the url of the notebook server is unknown, use the following widget get it."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"url = NotebookUrl()\n",
"url"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Initiate database connection using Notebook server url and the address (host and port) for the targe MongoDB instance. The default MongoDB host is `localhost` and the default port number is `27017`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"c = Connection(url = url.nb_url)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## AstroMap"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We first import the demo catalog from a csv file to a pandas dataframe. Then create a catalog layer using this pandas dataframe. The data used can be obtained from the github repository."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"df_vizic = pd.read_csv('demo.csv')\n",
"df_vizic['radius'] = df_vizic.petroR90_r # assign radius column\n",
"c.rm_catalog('vizic') # for demo purpose, remove catalog with same given name if existed\n",
"g = GridLayer(c, coll_name=\"vizic\", df=df_vizic, scale_r=2) # use scale_r to scale up visualized objects"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"\n",
"**Note:** \n",
"\n",
"To implement the tiled web map design, **vizic** uses the size information to filter out objects that are too small to display at current zoom level. The program uses `B_IMAGE`, which is normally the semi-minor axis of an object, or `RADIUS` as the ruler. If none of the above columns is presented in the dataframe, **vizic** will display all objects regardless of the zoom level with a significant performance cost. \n",
"\n",
"
"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"\n",
"**Note:** \n",
" \n",
"The default unit for object sizes is arcsecond.\n",
"\n",
"
"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"After some datasets are successfully imported, we can also retrieve the catalog either by a randomly generated uuid or a customized name provided when the data was initially imported."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false,
"scrolled": false
},
"outputs": [],
"source": [
"g = GridLayer(c, collection='vizic',scale_r=2)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now let's create the main map widget (AstroMap) and some control widgets for the catalog layer."
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"# Map object\n",
"m = AstroMap(default_tiles=g, zoom=1) \n",
"# A color picker widget\n",
"cp = LayerColorPicker(layer=g, concise=True)\n",
"# PopupDis widget to display catalog data individually checked object\n",
"p = PopupDis(layer=g)\n",
"# A reset button\n",
"hb = HomeButton(m)\n",
"# A trigger to enter data selection mode\n",
"s = SelectionTrig(m); s.link()\n",
"# A button to initiate query for selected from the database\n",
"get = GetDataButton(g)"
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"# Create a dropdown widget to select the property used for color-mapping\n",
"cdrop = CFDropdown(g)\n",
"g.custom_c = True\n",
"# Create a widget to filter displayed objects with given value ranges\n",
"f = FilterWidget(g)\n",
"g.filter_obj = True\n",
"f.link()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Use an accordion widget to put control widgets together."
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"accordion = Accordion(children=[cdrop, f, p])\n",
"accordion.set_title(2, 'Object Catalog')\n",
"accordion.set_title(0, 'Color by Property')\n",
"accordion.set_title(1, 'Filter Objects')\n",
"accordion.layout.width = '50%'\n",
"accordion.layout.overflow_x = 'scroll'"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Put the accordion side by side with the map widget to make an integrated interface."
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {
"collapsed": false,
"scrolled": true
},
"outputs": [],
"source": [
"app = HBox([m, VBox([hb, s, get, cp]), accordion]); app"
]
},
{
"cell_type": "markdown",
"metadata": {
"collapsed": true
},
"source": [
"## Interface and Interaction"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Basic map browsing"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Color mapping & objects filtering"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Clickable objects"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Selection tool"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
""
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.4.3"
},
"widgets": {
"state": {
"b52e005f79074ec8b3b03ee0bd34bb08": {
"views": [
{
"cell_index": 10
}
]
}
},
"version": "1.2.0"
}
},
"nbformat": 4,
"nbformat_minor": 2
}