Overview

Every Mode report contains an integrated notebook-style environment where you can use either Python or R to further explore and visualize your query results. Use moveable code blocks and markdown cells for exploratory data analysis, visualization, and collaboration. Notebooks are pre-loaded with a variety of Python and R libraries. You can add output cells to shareable reports, or share the Notebook itself using a direct URL.

Using the Notebook

To get started using the Notebook:

  1. Open an existing report or create a new report and run one or more SQL queries from the Query Editor.
  2. Click New Notebook. Your query results will automatically be loaded into a datasets object.
  3. On the right side panel, click the dropdown to select the language you want to work in, either Python or R.

Key elements of the Mode Notebook:

  • Toolbar - Where you can manipulate and run your Notebook, restart the session, export, and more.
  • Cells - Compose code and view results in a Code cell, or contextualize your work with a Markdown cell.
  • Resources Panel - The right side panel provides resources to help you including keyboard shortcuts, external documentation, and supported libraries/packages.
  • Status Indicator - Where you are notified about your Notebook session status.

Working with cells

There are two types of cells in the Notebook.

Markdown - Markdown cells allow you to add context to your analysis. Any markdown code will render right in your Notebook.

Code - Input Python or R code into the IN section of the cell. When this cell runs, any corresponding output (including visualizations) will be shown in in the OUT section.

Notes:

  • When you run your notebook, cells are executed in the order they are displayed, starting from the top cell.
  • To select or change a cell’s type, go to the dropdown menu in the top toolbar and choose Code or Markdown.
  • To run a cell, select it and press Shift + Return. Or click Run Cell in the toolbar.
  • The number next to the cell label will increment by one every time code in the cell is successfully run.

Toolbar

Notebook

  1. Restart Session - Stops any current computations running in the Notebook. Changes to the Notebook that are stored in memory will be reverted, but code in input cells will be available to re-run after the Notebook restarts.
  2. Run Notebook - Runs all input cells in the Notebook in sequence (from top to bottom)
  3. Run Cell - Runs code in the selected cell
  4. Add New Cell - Adds new input cell above or below the current cell
  5. Move Cell Up - Moves the current input or markdown cell up
  6. Move Cell Down - Moves the current cell down
  7. Delete Cell - Deletes the current cell
  8. Freeze Cell - Freezes the current input cell so that no changes are allowed; also prevents this cell from running
  9. Fold Cell - Folds (hides) the current cell
  10. Markdown/Code dropdown - Allows you to select the type for the current input cell (as code or markdown)
  11. Add to Report Builder - Adds the output of the selected cell to the Report Builder
  12. Export Notebook - Exports all markdown and input cells as a .py or .r file

Notebook Status

The status indicator, located in the bottom right corner of the browser window, will notify you if there is an issue with your session. It may prompt you to restart the kernel.

  • Setting up notebook - Displayed when opening up a new Notebook, or after re-starting your session.
  • Ready - Notebook is ready to go.
  • Running - Your code is executing.
  • Loading dataframes - This message may display for larger datasets while dataframe information is loaded into the Notebook.
  • Notebook has encountered an unexpected error - Your session has crashed and will need to be restarted.
  • There was a problem with your session - Your session has terminated and you need to click Restart to get things working again.
  • Cell is still running. Hang tight! - This can appear when code being run includes long-running, computationally intense functions. The Notebook is still online.
  • Notebook is having trouble, try running again - The Notebook is experiencing problems. Please try running your code again to fix the issue.

Accessing query results

The Notebook has access to the results of every query in your report. However, the way you access those results differs depending on the language you’re using. In each case, all query results are delivered to the Notebook as a custom object called datasets. datasets contains objects of the following type:

Python: pandas DataFrame
R: Data Frame

In your Notebook code, reference query result sets in the datasets list by query name, position, or token. For example:

To return results for: Python R
First query added to report datasets[0] datasets[[1]]
Second query added to report datasets[1] datasets[[2]]
Query named ‘Active Users’ datasets["Active Users"] datasets[["Active Users"]]
Query with token ‘6763b688fb54’ datasets["6763b688fb54"] datasets[["6763b688fb54"]]

Notes:

  • The datasets object won’t update in the Notebook until after all queries in the report have run successfully.
  • Remember that R is 1-indexed and Python is 0-indexed.
  • If you refer to query results by the query name, remember to update your code if you rename the query in your report.
  • The order of the results in the datasets object is based on when the query was added to the report. Renaming a query may change the order it’s displayed in the report editor but will not affect its position in the datasets object.
How to find a query’s token

To find the query token starting from the Notebook or editor, click View in the header, then View details, and then click SQL for the query you wish to use. The URL for SQL contains the query token at the end:

https://modeanalytics.com/ORGANIZATION_USERNAME/reports/REPORT_TOKEN/queries/QUERY_TOKEN

Query token

Adding cell output to your report

Add contents of the OUT section of any Notebook cell to the Report Builder by clicking on the cell and then clicking Add to Report Builder in the toolbar. You can adjust the dimensions and placement of this cell in the Report Builder.

Add CSV export to a cell

You can add an export button to a Notebook output cell so viewers can export calculated results to a CSV. For example, to add an export button to an output cell that generated a CSV of the query results of a query named “Active Users”, add the following code to the preceding input cell:

Python R
import notebooksalamode as mode
mode.export_csv(datasets["Active Users"])
export_data(datasets[["Active Users"]])

Tip: The export button can reference and export any pandas DataFrame (Python) or R Data Frame ® available in the cell.

Available Libraries

Python

The Notebook comes pre-loaded with the following Python libraries:

  • agate: data analysis library with human-readable code
  • basemap: matplotlib toolkit to plot data on maps with coastlines, lakes, rivers, and political boundaries
  • beautiful soup: library for parsing HTML, JSON and XML data
  • cufflinks: library to bind Plotly directly to pandas dataframes
  • engarde: package for defensive data analysis
  • emcee: An MIT MCMC library
  • folium: library to build Leaflet.js maps in Python
  • gensim: library for unsupervised semantic modeling from plain text
  • geomap: package to generate maps of geolocations
  • HDBSCAN: Hierarchical Density-Based Spatial Clustering of Applications with Noise
  • jsonify: takes a .csv file and converts to .json format
  • keras: high-level neural networks API that can run on TensorFlow or Theano
  • lifelines: an implementation of survival analysis in Python
  • lifetimes: package for analyzing user behavior
  • matplotlib: 2D plotting library
  • networkx: package to create, manipulate, and study complex networks
  • nltk: natural language toolkit for working with human language data
  • numexpr: fast numerical array expression evaluator
  • numPy: scientific computing library
  • pandas: library of data structures and data analysis tools
  • pandaSQL: queries pandas dataframes using SQL syntax
  • patsy: library for describing statistical models/building design matrices
  • plotly: library for data visualization, dashboards & collaborative analysis
  • prettytable: library for easily displaying tabular data in ASCII table format
  • prophet: a procedure for forecasting time series data
  • pyzipcode: query zip codes and location data
  • requests: library that allows HTTP requests*
  • scikit-image: image processing library
  • scikit-learn: library of tools for data mining and analysis
  • sciPy: library for mathematics, science and engineering
  • seaborn: visualization library that allows developers to draw statistical graphics
  • sexMachine: predict gender from first names
  • statsmodels: library for estimating statistical models/performing statistical tests
  • symPy: library for symbolic mathematics
  • tabulate: pretty-print tabular data
  • tensorflow: library for numerical computation using data flow graphs
  • textblob: simple API for common NLP tasks
  • ua-Parser: fast and reliable user agent parser for Python
  • wordcloud: a little wordcloud generator in Python

*IMPORTANT: We discourage accessing APIs that require authentication using personally identifiable credentials and information, as will be visible to viewers of your report.

R

The Notebook comes pre-loaded with the following R packages:

  • assertthat - easy pre- and post-assertions
  • blob - simple S3 class to represent BLOBs
  • BTYD - implementing buy-til-you-die models
  • BTYDplus - extends BTYD
  • caret - streamlines creation of predictive models
  • causalImpact - estimates causal effect of intervention on time series
  • cluster - cluster analysis extended Rousseeuw et al.
  • colorspace - color space manipulation
  • data.table - extends data.frame
  • dichromat - color schemes for dichromats
  • digest - create compact hash digests of R objects
  • DMwR - functions & data for Data Mining with R
  • dplyr - a grammar of data manipulation
  • forcats - working with categorical variables (factors)
  • forecast - forecasting for time series & linear models
  • GGally - extension to ggplot2
  • ggcorplot - plots a correlation matrix
  • ggdendro - dendrograms & tree plots with ggplot2
  • ggplot2 - system for creating graphics
  • ggpubr - publication-ready ggplot2 plots
  • ggridges - ridgeline plots in ggplot2
  • ggthemes - extra themes, scales, & geoms for ggplot2
  • ggvis - interactive graphics for exploratory analysis
  • glue - glue strings to data
  • gtable - arrange grobs in tables
  • hts - hierarchical & grouped time series
  • httr - tools for working with URLs & HTTP
  • iterators - provides iterator construct for R
  • itertools - various tools for creating iterators
  • kernlab - kernel-based machine learning lab
  • kknn - weighted k-nearest neighbors
  • lars - least angle regression, lasso & forward stagewise
  • lattice - trellis graphics for R
  • lazyeval - lazy (non-standard) evaluation
  • lubridate - do more with dates and times
  • magrittr - a forward-pipe operator
  • MASS - functions & datasets to support Venables & Ripley
  • modelr - modelling functions that work with the pipe
  • munsell - utilities for using Munsell colors
  • nnet - feed-forward neural networks & multinomial log-linear models
  • prophet - automatic forecasting procedure
  • proto - prototype object-based programming
  • purrr - tools for working with functional vectors
  • RColorBrewer - ColorBrewer palettes
  • reshape2 - transform data between wide & long
  • rlang - functions for base types & core R & tidyverse features
  • scales - scale functions for visualizations
  • stringr - work with character strings & reg ex
  • tidyr - easily create tidy data
  • tm - text mining package
  • utf8 - fixes bugs in R’s UTF-8 handling
  • viridisLite - port of matplotlib color maps
  • xml2 - parse xml
  • zoo - S3 infrastructure for regular & irregular time series

FAQs

How much memory is available to the Notebook?

The Notebook allows up to 12GB of memory per session, and a run-time limit of 15 minutes.

Can I access data from an external side in the Notebook?

Mode supports the Requests library in Python, which allows you to make HTTP requests.

Important: We discourage accessing APIs that require authentication using personally identifiable credentials, as they will be visible in plain-text to viewers of the report.

Can I import other or custom libraries into the Notebook?

Not currently, but this is something we’re thinking about adding in a future release. If you would like to see this feature or know of open source libraries you’d like to see added, please let us know!

Last updated April 18, 2018