{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting Circos Up and Running\n",
    "\n",
    "Done!  \n",
    "That is done if you already launched via the Binder system. (And if you haven't, click [here](http://beta.mybinder.org/v2/gh/fomightez/circos-binderized/master?filepath=index.ipynb) to do so.)\n",
    "\n",
    "If you are new to running Circos, you'll want to **stop reading this particular page** and simply continue on to the **next page** in the series [here ➡](notebooks/Quick_Start_Part1.ipynb) to get started building up a simple image in steps. \n",
    "\n",
    "The [index](index.ipynb) page is meant to provide a way to access the content in a manner that parallels [the official Circos site](http://circos.ca/). \n",
    "\n",
    "Others should find the items below address any remaining questions and provide an interface to run Circos."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "-----\n",
    "\n",
    "This page is an amalgam meant to address the content of the following pages at the documentation site:\n",
    "\n",
    "- the top part of [GETTING STARTED](http://circos.ca/support/getting_started/)\n",
    "- [Software: GETTING CIRCOS UP AND RUNNING](http://circos.ca/software/)\n",
    "- [REQUIREMENTS](http://circos.ca/software/requirements/)\n",
    "- [0 — CONFIGURATION AND INSTALLATION: 6. PERL AND MODULES](http://circos.ca/tutorials/lessons/configuration/perl_and_modules/)\n",
    "- [DOWNLOAD CIRCOS, TUTORIALS AND TOOLS](http://circos.ca/software/download/)\n",
    "\n",
    "This distillation is largely possible because the involved issues are handled by Circos already working when these notebooks are launched via the Binder system. **Additionally, the code for tutorials is present as well.**\n",
    "\n",
    "Because that is already handled,  you'll want to **stop reading this particular page** and simply continue on to the **next page** in the series [here ➡](notebooks/Quick_Start_Part1.ipynb) to get started building up a simple image in steps. \n",
    "\n",
    "For those of you already familiar with Circos and looking to see how to use it with this interface, continue on reading this page.\n",
    "\n",
    "At any point you can use the `+` button from the notebook toolbar above to add a cell and use Circos as if you are at the command line in that cell, executing cells by typing `shift-enter` or pressing the `Run` button on the toolbar. Alternatively, if you prefer to use the shell terminal directly, click the orange and gray `Jupyter` logo at the top left left of this page and then from the dashboard that comes up, choose `New` > `Terminal` to launch a terminal window. Still, you may wish to review the commands in the cells below to see how to run things here."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Triggering the 'complex' example code to run\n",
    "\n",
    "Running the code in next cell will generate the example image discussed [here](http://circos.ca/support/getting_started/). First, after changing to the pertinent directory, with a `rm` command, we delete the original, stored version of the output file. Then we run the demonstration `circos.conf` file by triggering the example `run` script. \n",
    "\n",
    "(Note, it will show many copies about `Use of uninitialized value in subroutine entry at /home/jovyan/circos-0.69-6/bin/../lib/Circos/Configuration.pm line 781.`; however, the process still works.)\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cd circos-0.69-6/example\n",
    "rm circos.png #delete stored version\n",
    "./run"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, after changing the working directory to `circos-0.69-6/example`, the example command could be run via the command below and that will better mirror how other commands will be run where `conf` files are in their own directories.\n",
    "\n",
    "```\n",
    "../bin/circos -conf etc/circos.conf > run.out\n",
    "```\n",
    "\n",
    "(Normally though, you wouldn't necessarily need the ` > run.out` part.)\n",
    "\n",
    "Run the next cell. If things worked it will display some text; howeverm not text that reads `tail: cannot open 'run.out' for reading: No such file or directory`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "head run.out"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Additionally, you click in the cell immediately below this one and hit `shift-enter` to refresh and see the generated image.\n",
    "\n",
    "### View generated demo image below"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![display image](circos-0.69-6/example/circos.png)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Retrieving your results in this interface\n",
    "\n",
    "You can right click images displaying in the notebook and use `Save Image As…` to save them to your local drive.\n",
    "\n",
    "Alternatively, they can be downloaded from the Jupyter Dashboard after navigating to the location in the file hierarchy and then checking the checkbox next to the file name and then choosing `Download` button that appears above the file listing."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Verify necessary Perl modules installed\n",
    "\n",
    "As discussed above everything is all set up and one can verify the necessary Perl modules are installed, just as you would on a local installation as discussed [here](http://circos.ca/documentation/tutorials/configuration/perl_and_modules/), by running the next command.\n",
    "\n",
    "Hit `shift-enter` in next cell to see all the modules Circos needs are installed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cd circos-0.69-6/example\n",
    "../bin/circos -modules"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "------\n",
    "\n",
    "**Things to keep in mind in this interface...**\n",
    "\n",
    "Keep in mind to treat the instance of your environment as ephemeral.  \n",
    "It is advisable to download or make a local copy of anything useful you generate ASAP. \n",
    "\n",
    "In regards to security, the [documentation warns](https://mybinder.readthedocs.io/en/latest/faq.html#can-i-push-data-from-my-binder-session-back-to-my-repository), \"You shouldn’t do anything on mybinder.org that you wouldn’t mind sharing with the world!\". BinderHub can be delployed locally to serve more specialized needs, see [here](https://mybinder.readthedocs.io/en/latest/faq.html#what-can-i-do-if-mybinder-org-does-not-meet-my-needs).\n",
    "\n",
    "------\n",
    "\n",
    "Subsequent notebooks...\n",
    "\n",
    "If still looking for more guidance to using Circos with this interface, it is suggested you continue on with the next notebook in the series [here ➡](notebooks/Quick_Start_Part1.ipynb).\n",
    "\n",
    "*Technical note related to minor differences you'll see in subsequent notebooks:*\n",
    "\n",
    "This is rather technical, but I am explaining the situation here for those curious about the differences in running Circos within these set of active notebooks served via the Binder system as opposed to the command line, and those that might notice a slight difference between this notebook and subsequent ones. It boils down to the fact that in other notebooks in this series of notebooks, you'll need `%%bash` at the start of cells where you are placing code to run Circos. If you want to understand why, continue on to the next paragraph.  \n",
    "You'll note that nothing was required in each cell, but the commands you'd normally use on the command line to run Circos. This first notebook page in the series accesses the command line directly. This can be determined by looking in the upper right corner, below, the `Logout` button, and seeing there is `Bash` indicating this notebook page is actually being run in a `Bash` kernel, i.e., it is providing the computational engine enabling running code in the cells. In subsequent notebooks, however, a `%%bash` tag is included at the start of most lines of code in order to trigger that redirect while taking advantage of the richer environment revealed by running the notebooks within the interactive Python kernel. This notebook being in the `Bash` kernel was done for two reasons: (1) this made it possible for the initial commands presented to look familiar to those in the Circos documentation without the need to first introduce additional cruft, i.e., IPython magicks; and (2) since this will be the first notebook in the series of notebooks I wanted to provide the fastest, least cluttered route for those already using command line-based Circos to get back to running Circos after launching a session via Binder."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Bash",
   "language": "bash",
   "name": "bash"
  },
  "language_info": {
   "codemirror_mode": "shell",
   "file_extension": ".sh",
   "mimetype": "text/x-sh",
   "name": "bash"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}