docs/source/instantiating_objects.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Instantiating BioCantor objects"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Instantiate a `Location` object"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`Location` objects store coordinates and a `Strand`. Here we demonstrate the two main subclasses of the abstract base class `Location`: `SingleInterval` (a single contiguous interval) and `CompoundInterval` (a set of possibly disjoint contiguous blocks).\n",
    "\n",
    "`Location`s can optionally be situated within a coordinate system or hierarchy of coordinate systems by passing `Parent` information to them."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# NOTE: Currently this import order matters, because there is a circular dependency between inscripta.biocantor.sequence and inscripta.biocantor.parent\n",
    "from inscripta.biocantor.location.location_impl import SingleInterval, CompoundInterval, Strand\n",
    "from inscripta.biocantor.sequence import Sequence, Alphabet\n",
    "from inscripta.biocantor.parent import Parent"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `SingleInterval` without parent\n",
    "\n",
    "A simple interval with start, end and strand; no coordinate system is specified."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "simple_interval = SingleInterval(3, 5, Strand.MINUS)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `SingleInterval` with parent\n",
    "\n",
    "`Location` constructors include an optional `parent` argument. A full `Parent` object can be passed to this argument. Alternatively, if that `Parent` object would be simple, shortcuts are provided to pass other object types for the parameter, avoiding having to call the `Parent` constructor directly. See below for examples of this."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Construct a sequence that locations will be defined relative to\n",
    "seq = Sequence(\"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\", Alphabet.NT_STRICT)\n",
    "# Construct an interval relative to the sequence. Pass a Parent object to its constructor which specifies\n",
    "# parent ID and the sequence\n",
    "interval_on_seq = SingleInterval(3, 5, Strand.MINUS, parent=Parent(id=\"parent\", sequence=seq))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here are some examples where the parent has only one attribute. The shortcut can be used, passing the one attribute directly instead of calling the Parent constructor.\n",
    "\n",
    "(Note: this shortcut works for all `parent`s that have only one attribute with the exception of the `sequence_type` argument to the `Parent` constructor.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Parent has an ID (name) only\n",
    "interval_with_parent_id = SingleInterval(3, 5, Strand.MINUS, parent=\"parent\")\n",
    "\n",
    "# Parent has a sequence only\n",
    "interval_with_parent_seq = SingleInterval(3, 5, Strand.MINUS, parent=seq)\n",
    "\n",
    "# Note: if only a string is passed for parent, that string is assumed to represent the parent ID.\n",
    "# The parent constructor has one other string argument: sequence_type. In the event you want to construct\n",
    "# a Location with a parent that has only a sequence_type attribute, you need to call the Parent constructor.\n",
    "interval_with_parent_type = SingleInterval(3, 5, Strand.MINUS, parent=Parent(sequence_type=\"chromosome\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `CompoundInterval` from start and end coordinates, no parent"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "simple_compound_interval = CompoundInterval([5, 10, 20, 30], [6, 15, 22, 35], Strand.PLUS)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `CompoundInterval` from list of `SingleInterval`s, no parent"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "compound_interval_from_blocks = CompoundInterval.from_single_intervals([\n",
    "    SingleInterval(2, 5, Strand.PLUS), SingleInterval(8, 11, Strand.PLUS)])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `CompoundInterval` with parent\n",
    "\n",
    "Parent information can be passed to `CompoundInterval`s in the same way as `SingleInterval`s."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Instantiate a `Sequence` object"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`Sequence` objects store sequence data, an `Alphabet`, and several optional attributes. `Sequence`s can optionally be situated within a coordinate system or hierarchy of coordinate systems by passing `Parent` information to them."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Minimal `Sequence`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "simple_sequence = Sequence(\"AAACCCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\", Alphabet.NT_STRICT)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Sequence with parent"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this example, a `Sequence` represents a slice of a chromosome and has `parent` attribute reflecting this. The `location` argument to the `Parent` constructor represents the location of the child relative to that parent. In this case, it is the location of the chromosome slice relative to the chromosome."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "chromosome_slice = Sequence(\"TTTTTTT\", Alphabet.NT_STRICT, \n",
    "                            parent=Parent(id=\"chr1\", \n",
    "                                          location=SingleInterval(1000, 1007, Strand.PLUS),\n",
    "                                          sequence_type=\"chromosome\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Other optional `Sequence` attributes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sequences can also have an optional `id` (name) and `type` (string representing a sequence type, for downstream calculations). Finally, the `Sequence` constructor has an optional parameter `validate_alphabet` which, when set to `False`, disables the requirement that the sequence data conform to the provided `Alphabet`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "seq_with_all_attributes = Sequence(data=\"AAAAAAA\", \n",
    "                                   alphabet=Alphabet.NT_STRICT, \n",
    "                                   id=\"my_sequence\",\n",
    "                                   type=\"chromosome_slice\",\n",
    "                                   parent=Parent(id=\"chr1\", location=SingleInterval(33, 40, Strand.MINUS)))\n",
    "\n",
    "seq_with_no_alphabet_validation = Sequence(\"XXXXXXX\", Alphabet.NT_STRICT, validate_alphabet=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Instantiate a `Parent` object"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`Parent` is a fairly abstract concept in BioCantor. `Parent` objects can represent different aspects of a relationship between an implied child and the given parent. `Parent` objects do not store pointers to children; a child is implied but cannot be directly accessed from the `Parent`. Instead, objects store pointers to their `Parent`s. `Location`s, `Sequence`s, and `Parent`s can have `Parent`s.\n",
    "\n",
    "All arguments to the `Parent` constructor are optional and any combination of them may be passed. The important thing to understand is that some `Parent` attributes describe the `Parent` object in its own right, while some describe the relationship of an implied child to the parent.\n",
    "\n",
    "`Parent` attributes that describe the parent object itself:\n",
    "\n",
    "- `id`\n",
    "- `sequence_type`\n",
    "- `sequence`\n",
    "- `parent` (Parent of this parent)\n",
    "\n",
    "`Parent` attributes that define the relationship of the implied child to the parent:\n",
    "\n",
    "- `location` (The location of the child relative to this parent)\n",
    "- `strand` (The strand of the child relative to this parent)\n",
    "\n",
    "Furthermore, some arguments are redundant; for example, if `location` is passed then it will include a strand and `strand` is not needed. The reason both are offered is for the case where the child has a strand relative to its parent but no further location data. Similarly, `sequence` and `sequence_type` are mutually redundant if `sequence` includes a sequence type. For these cases, there is no problem with passing both arguments, and conflicting values will cause an exception to be raised."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `Parent` with an ID only"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is useful when multiple child objects need to be associated with a parent (say, for purposes of coordinate calculations requiring that locations refer to the same coordinate system), but no other parent data is required. For example, this could be used to associate many features annotated to the same chromosome without needing to hold the chromosome sequence in memory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "parent_with_id_only = Parent(id=\"chr1\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `Parent` representing a sequence with an ID, and a location for the implied child"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "parent_with_seq_and_location = Parent(id=\"seq\", sequence=seq, location=SingleInterval(11, 18, Strand.PLUS))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `Parent` with its own parent, establishing a multi-layer hierarchy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This `Parent` object represents a chunk of a chromosome and is associated with the full chromosome as its own parent. Note the location of the chromosome slice relative to the chromosome is specified in the parent of this parent. This is because the `location` argument defines the location of the child relative to the parent."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "parent_with_parent = Parent(id=\"chr1:1000-2000\", \n",
    "                            sequence_type=\"chromosome_slice\", \n",
    "                            parent=Parent(id=\"chr1\", \n",
    "                                          sequence_type=\"chromosome\",\n",
    "                                          location=SingleInterval(1000, 2000, Strand.PLUS)))"
   ]
  },
  {
   "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
}