{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Jscatter Installation\n",
    "\n",
    "This Notebook aims to explain how to install and use Jscatter on a Jupyter Notebook on your personal computer or on a Jupyter server.\n",
    "\n",
    "### Content\n",
    "- Install Jscatter and prerequisites on readonly Jupyter server \n",
    "- Use Jupyter locally\n",
    " - Install Jupyter\n",
    " - Decide which plotting utility you use\n",
    " - Use Jscatter\n",
    "\n",
    "\n",
    "![Jscatter](https://jscatter.readthedocs.io/en/latest/_images/Jscatter.jpeg \"Jscatter\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "### Install Jscatter and prerequisites on readonly Jupyter server\n",
    "Open a new notebook on the server. To install Jscatter and prerequisite use the following.\n",
    "After first install the prerequisites may be cached that installation is faster.\n",
    "\n",
    "This adds main prerequisites numpy, scipy, matplotlib and Pillow if they are not preinstalled. sys.executable knows the actual running kernel."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sys\n",
    "!{sys.executable} -m pip install jscatter    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Select matplotlib interactive backend and start to use Jscatter\n",
    "Backend selection needs to be done before anything else to get interactive plots."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib notebook\n",
    "\n",
    "import jscatter as js\n",
    "import numpy as np\n",
    "\n",
    "js.usempl(True)   # force matplotlib, not needed in Linux"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Use Jupyter locally\n",
    "### Install Jupyter \n",
    "To use Jscatter please follow the specific [installation instructions](https://jscatter.readthedocs.io/en/latest/Installation.html).\n",
    "\n",
    "The Jupyter installation is explained at [Jupyter](https://jupyter.readthedocs.io/en/latest/install.html) which is mainly for python3:   \n",
    "\n",
    "    pip3 install jupyter\n",
    "\n",
    "After installing Jupyter start it by\n",
    "\n",
    "    ipython notebook\n",
    "\n",
    "or \n",
    "\n",
    "    jupyter notebook\n",
    "    \n",
    "A browser window will open. Open a new notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Decide which plotting utility you use\n",
    "On Jupyter you can use the matplotlib interactive backend as above. This needs to be done before anything else.\n",
    "\n",
    "- 'notebook' is an inline interactive backend.\n",
    "- 'qt' is e.g. interactive but with external plot window."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib notebook"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Please refer to matplotlib documentation how to install different backends.\n",
    "\n",
    "If you prefer Xmgrace you dont need to use matplotlib for 2D plots."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Use Jscatter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "import jscatter as js\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "js.usempl(True)   # force matplotlib, not needed in Linux"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### On Linux and MacOS you may want to use Xmgrace.\n",
    "Open plots like \n",
    "\n",
    "    p=js.grace()\n",
    "    \n",
    "Look into the examples and the documentation how to use this."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### If you want to open matplotlib plots use \n",
    "    \n",
    "    p=js.mplot()\n",
    "   \n",
    "or the conventional matplotlib commands. Please avoid the pyplot command syntax as it is difficult later to switch to the object oriented commands.\n",
    "The 'js.mpl' module contains some convenience tools to simplify plotting which are used in the plot opened by the above commands.\n",
    "\n",
    "To allow the usage of all original commands the mpl commands start with big letters. matplotlib commands start with small letters.\n",
    "E.g.\n",
    "    \n",
    "    p.Plot(data,symbol=[1,1,3],legend='something useful') \n",
    "    \n",
    "uses automatically the .X, .Y attributes accessible in dataArrays adds symbol formatting and a legend.\n",
    "\n",
    "    p[0].plot(data.X,data.Y,..)\n",
    "    \n",
    "uses the matplotlib command for axes[0] with explicitly given arrays. In matplotlib nomenclature p is the figure and p[0] indexes the axes. Commands for legend , symbol size and so on have to be given additionally.  "
   ]
  }
 ],
 "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.8.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
