{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Plotting interactions\n",
    "=====================\n",
    "\n",
    "Interactions are any data type that describes a relationship between two\n",
    "windows of nucleotides. RING-MaP, PAIR-MaP, SHAPE-JuMP, and pairing\n",
    "probabilities are all examples of interactions. RING-MaP and PAIR-MaP data can\n",
    "have variable window sizes, but they usually describe 1 and 3 nucleotide\n",
    "windows respectively. Herein, I'll refer to these windows as i and j.\n",
    "\n",
    "I will only be using arc plots in this example, but other plots can also accept\n",
    "`interactions` and `interactions_filter` arguments. So far, this includes:\n",
    "\n",
    "- arc plots `arc`\n",
    "- circle plots `circle`\n",
    "- secondary structure diagrams `ss`\n",
    "- 3D molecular renderings `mol`\n",
    "- contour and heatmap plots `heatmap`\n",
    "- distance distribution histograms `disthist`\n",
    "\n",
    "The `interactions_filter` argument helps to filter out unwanted interactions.\n",
    "It also controls the color gradient in which the interactions are plotted. In\n",
    "this notebook, I will demonstrate some of these options and how they can be\n",
    "used in your analysis.\n",
    "\n",
    "Visit the [Interactions reference](../guides/filters.md) page for a full list of\n",
    "available arguments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import rnavigate as rnav\n",
    "from rnavigate.examples import rnasep_1\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Demonstration\n",
    "-------------\n",
    "\n",
    "In these examples, I'll be working with SHAPE-JuMP data, which is particularly\n",
    "dense and requires filtering. First, lets see what these data look like in\n",
    "thier raw form. By default all of the data is displayed according to\n",
    "\"Percentile\", which is the percentile rank of the deletion rate among all\n",
    "deletions, a float value from 0 to 1. However, the color scale only spans 0.98\n",
    "to 1. Let's see what this looks like:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot = rnav.plot_arcs(\n",
    "    samples=[rnasep_1],\n",
    "    sequence=\"shapejump\",\n",
    "    interactions=\"shapejump\",\n",
    "    structure=\"ss_pdb\",\n",
    "    profile=\"shapemap\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see here that the data is very dense; there is a yellow smudge behind\n",
    "the blue and green arcs. These lower values are usually just noise, so lets\n",
    "remove them by requiring the deletions to be in the 95th percentile."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot = rnav.plot_arcs(\n",
    "    samples=[rnasep_1],\n",
    "    sequence=\"shapejump\",\n",
    "    structure=\"ss_pdb\",\n",
    "    profile=\"shapemap\",\n",
    "    interactions={\n",
    "        'interactions': 'shapejump',\n",
    "        'Percentile_ge': 0.95},\n",
    "    )\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Better. Still, many of these are reflective of secondary structure. I'll remove\n",
    "these by requiring the contact distance to be above 14. This means that it takes\n",
    "at least 15 steps through the secondary structure graph to get from i to j."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot = rnav.plot_arcs(\n",
    "    samples=[rnasep_1],\n",
    "    sequence=\"shapejump\",\n",
    "    structure=\"ss_pdb\",\n",
    "    profile=\"shapemap\",\n",
    "    interactions={\n",
    "        'interactions': 'shapejump',\n",
    "        'Percentile_ge': 0.95,\n",
    "        'normalization': 'min_max',\n",
    "        'values': [0.95, 1.0],\n",
    "        'min_cd': 15},\n",
    "    )\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Interesting...Let's test if these are really reflective of tertiary structure.\n",
    "This time, we'll use the \"Distance_02'\" metric to color the arcs. This is \n",
    "calculated from our reference PDB structure as the 3D distance between the 2'\n",
    "oxygen atom of nucleotide i and nucleotide j. We'll also have to change the\n",
    "colormaps min and max values, since it is now being applied to the 3D distance\n",
    "in angstroms. We'll also further limit the percentile (98th)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot = rnav.plot_arcs(\n",
    "    samples=[rnasep_1],\n",
    "    sequence=\"shapejump\",\n",
    "    structure=\"ss_pdb\",\n",
    "    profile=\"shapemap\",\n",
    "    interactions={\n",
    "        'interactions': 'shapejump',\n",
    "        'Percentile_ge': 0.98,\n",
    "        'normalization': 'min_max',\n",
    "        'values': [5, 50],\n",
    "        'min_cd': 15,\n",
    "        'metric': \"Distance_O2'\"})\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Many of the one-off deletions are quite far away, but the densest cluster here\n",
    "is definitely close in space. Pretty neat!"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.9.2 ('RNAvigate')",
   "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.9.2"
  },
  "vscode": {
   "interpreter": {
    "hash": "9bc5b7d6fb91a4aeee0c6c593c16f1676dc0f90feb6b649cbd0762bccce1fa5e"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}