docs/source/location_operations.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# `Location` operations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Instantiate a `Location`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from inscripta.biocantor.location.location_impl import SingleInterval, CompoundInterval, EmptyLocation, Strand\n",
    "from inscripta.biocantor.sequence import Sequence, Alphabet\n",
    "from inscripta.biocantor.parent.parent import Parent\n",
    "\n",
    "# No parent\n",
    "single_interval = SingleInterval(5, 10, Strand.PLUS)\n",
    "compound_interval = CompoundInterval([2, 8], [5, 13], Strand.PLUS)\n",
    "\n",
    "# With parent sequence\n",
    "compound_interval_with_sequence = CompoundInterval([2, 8], [5, 13], Strand.PLUS,\n",
    "                                                   parent=Sequence(\n",
    "                                                       \"CTACGACTTCCGAGTCCAAAGTGTCCGTGT\", \n",
    "                                                       Alphabet.NT_STRICT,\n",
    "                                                       type=\"chromosome\",\n",
    "                                                   ))\n",
    "\n",
    "# Empty location (implemented as a singleton)\n",
    "# Rarely needs to be directly instantiated, but is returned from method calls where appropriate\n",
    "empty = EmptyLocation()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Data access"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Start, end, strand"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(2, 13, <Strand.PLUS: 1>)"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "compound_interval.start, compound_interval.end, compound_interval.strand"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Other basic properties"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "compound_interval.num_blocks"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "compound_interval.is_contiguous"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "single_interval.is_empty"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "EmptyLocation().is_empty"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "single_interval.parent is None"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Parent: id=None, type=chromosome, strand=+, location=CompoundInterval <2-5:+, 8-13:+>, sequence=<Sequence;\n",
       "  Alphabet=NT_STRICT;\n",
       "  Length=30;\n",
       "  Parent=None;\n",
       "  Type=chromosome>, parent=None>"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "compound_interval_with_sequence.parent"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### List of contiguous blocks"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<SingleInterval 2-5:+>, <SingleInterval 8-13:+>]"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "compound_interval.blocks"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Iterator over contiguous blocks in strand-relative order"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<SingleInterval 8-10:->, <SingleInterval 1-3:->]"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "block_iter = CompoundInterval([1, 8], [3, 10], Strand.MINUS).scan_blocks()\n",
    "list(block_iter)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Extract underlying spliced sequence"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Sequence=ACGTCCGA;\n",
       "  Alphabet=NT_STRICT;\n",
       "  Length=8;\n",
       "  Parent=None;\n",
       "  Type=None>"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "compound_interval_with_sequence.extract_sequence()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Set theoretic operations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Overlap"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "SingleInterval(5, 10, Strand.PLUS).has_overlap(SingleInterval(9, 20, Strand.PLUS))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "SingleInterval(5, 10, Strand.PLUS).has_overlap(SingleInterval(9, 20, Strand.MINUS))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "SingleInterval(5, 10, Strand.PLUS).has_overlap(SingleInterval(9, 20, Strand.MINUS), match_strand=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Intersection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "CompoundInterval <4-5:+, 8-10:+>"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "CompoundInterval([2, 8], [5, 13], Strand.PLUS).intersection(SingleInterval(4, 10, Strand.PLUS))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "EmptyLocation"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "SingleInterval(0, 3, Strand.PLUS).intersection(SingleInterval(5, 8, Strand.PLUS))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Union"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "CompoundInterval <0-7:+, 8-9:+, 10-15:+>"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "CompoundInterval([0, 10], [5, 15], Strand.PLUS).union(CompoundInterval([0, 8], [7, 9], Strand.PLUS))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Contains\n",
    "\n",
    "Check if each block of other location is contained in a block of this location"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "compound_interval.contains(CompoundInterval([2, 10], [4, 11], Strand.PLUS))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Minus"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "CompoundInterval <10-13:+, 15-20:+>"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "SingleInterval(10, 20, Strand.PLUS).minus(SingleInterval(13, 15, Strand.PLUS))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Gaps (introns)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<SingleInterval 25-30:->, <SingleInterval 15-20:->]"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# List of gaps as SingleInterval objects, ordered relative to location strand\n",
    "CompoundInterval([10, 20, 30], [15, 25, 35], Strand.MINUS).gap_list()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "CompoundInterval <15-20:-, 25-30:->"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# All gaps as one Location object\n",
    "CompoundInterval([10, 20, 30], [15, 25, 35], Strand.MINUS).gaps_location()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other feature arithmetic operations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Distance to another location"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "7"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "compound_interval.distance_to(SingleInterval(20, 30, Strand.MINUS))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Extend endpoints, returning a new `Location`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<SingleInterval 1-13:->"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "SingleInterval(5, 10, Strand.MINUS).extend_relative(3, 4)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<SingleInterval 2-14:->"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "SingleInterval(5, 10, Strand.MINUS).extend_absolute(3, 4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Reverse or reset strand"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "CompoundInterval <2-5:-, 8-13:->"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "compound_interval.reverse_strand()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "CompoundInterval <2-5:-, 8-13:->"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "compound_interval.reset_strand(Strand.MINUS)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Reverse feature, flipping strand and block structure"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "CompoundInterval <2-7:-, 10-13:->"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "compound_interval.reverse()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Shift entire location left or right"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<SingleInterval 1-3:->"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "SingleInterval(3, 5, Strand.MINUS).shift_position(-2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Iterator over (spliced) windows"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "window_iter = CompoundInterval([1, 8], [6, 15], Strand.MINUS).scan_windows(window_size=3, step_size=2, start_pos=0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<SingleInterval 12-15:->,\n",
       " <SingleInterval 10-13:->,\n",
       " <SingleInterval 8-11:->,\n",
       " CompoundInterval <4-6:-, 8-9:->,\n",
       " <SingleInterval 2-5:->]"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(window_iter)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Operations on `Parent` hierarchy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Identify ancestors in `Parent` hierarchy"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Parent: id=None, type=chromosome, strand=+, location=CompoundInterval <2-5:+, 8-13:+>, sequence=<Sequence;\n",
       "  Alphabet=NT_STRICT;\n",
       "  Length=30;\n",
       "  Parent=None;\n",
       "  Type=chromosome>, parent=None>"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "compound_interval_with_sequence.first_ancestor_of_type(\"chromosome\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "compound_interval_with_sequence.has_ancestor_of_type(\"other_seq_type\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "compound_interval_with_sequence.has_ancestor_sequence(\n",
    "    Sequence(\"CTACGACTTCCGAGTCCAAAGTGTCCGTGT\", Alphabet.NT_STRICT, type=\"chromosome\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Coordinate conversion"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Establish a 3-level hierarchy\n",
    "\n",
    "- Highest level: all of chr1\n",
    "- Middle level: 30nt slice of chr1\n",
    "- Lowest level: a 10nt feature initially defined relative to the 30nt slice"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# A Parent object representing a full chromosome\n",
    "chr1 = Parent(id=\"chr1\", sequence_type=\"chromosome\")\n",
    "\n",
    "# A slice of chr1 lying at positions 1000-1030\n",
    "chromosome_slice_location = SingleInterval(1000, 1030, Strand.PLUS, parent=chr1)\n",
    "chromosome_slice = Sequence(\"CTGATAGGGGATGCAGTATATCCCTGGATA\", Alphabet.NT_STRICT, \n",
    "                            parent=chr1.reset_location(location=chromosome_slice_location))\n",
    "\n",
    "# A feature defined relative to the slice\n",
    "feature = SingleInterval(5, 15, Strand.MINUS, parent=chromosome_slice)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Convert the feature to chromosome coordinates"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<SingleInterval <Parent: id=chr1, type=chromosome, strand=-, location=<SingleInterval 1005-1015:->, sequence=None, parent=None>:1005-1015:->"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "feature.lift_over_to_first_ancestor_of_type(\"chromosome\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Convert a feature-relative position to slice-relative"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "8"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "feature.relative_to_parent_pos(6)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Convert a feature-relative interval to slice-relative"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<SingleInterval <Parent: id=None, type=None, strand=+, location=<SingleInterval 6-8:+>, sequence=<Sequence;\n",
       "  Alphabet=NT_STRICT;\n",
       "  Length=30;\n",
       "  Parent=<Parent: id=chr1, type=chromosome, strand=+, location=<SingleInterval <Parent: id=chr1, type=chromosome, strand=+, location=<SingleInterval 1000-1030:+>, sequence=None, parent=None>:1000-1030:+>, sequence=None, parent=None>;\n",
       "  Type=None>, parent=<Parent: id=chr1, type=chromosome, strand=+, location=<SingleInterval <Parent: id=chr1, type=chromosome, strand=+, location=<SingleInterval 1000-1030:+>, sequence=None, parent=None>:1000-1030:+>, sequence=None, parent=None>>:6-8:+>"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "feature.relative_interval_to_parent_location(7, 9, Strand.MINUS)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Convert a chromosome-relative position to slice-relative"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "7"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "chromosome_slice.\\\n",
    "  location_on_parent.\\\n",
    "  parent_to_relative_pos(1007)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Convert a chromosome-relative feature to slice-relative"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<SingleInterval 0-10:->"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "chromosome_slice.\\\n",
    "  location_on_parent.\\\n",
    "  parent_to_relative_location(SingleInterval(990, 1010, Strand.MINUS, parent=chr1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Location of one feature relative to another feature\n",
    "\n",
    "Express the intersection of two locations in coordinates relative to one of the locations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<SingleInterval 0-4:->"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "feature.location_relative_to(SingleInterval(11, 20, Strand.PLUS, parent=chromosome_slice))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "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.7.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}