{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# The Transform Module\n",
    "\n",
    "The `transform` module of the `repytah` package holds functions used to transform matrix inputs into different forms that are of use in larger functions from other modules. The functions in the `transform` module focus mainly on overlapping repeated structures and annotation markers.\n",
    "\n",
    "The `transform` module includes the following functions:\n",
    "\n",
    "- `remove_overlaps`: Removes any pairs of repeats with the same length and annotation marker where at least one pair of repeats overlap in time\n",
    "\n",
    "The functions in the `repytah` package are meant to be used alongside other functions in the package, so many examples use functions from multiple modules. In the examples below, the following functions from the [`utilities`](https://github.com/smith-tinkerlab/repytah/blob/main/docs/utilities_vignette.ipynb) module are called:\n",
    "- `add_annotations`\n",
    "- `reconstruct_full_block`\n",
    "\n",
    "For more in-depth information on the function calls, an example function pipeline is shown below. Functions from the current module are shown in green.\n",
    "\n",
    "<img src=\"pictures/function_pipeline.jpg\" width=\"380\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Importing necessary modules"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# NumPy is used for mathematical calculations\n",
    "import numpy as np\n",
    "\n",
    "# Import transform\n",
    "from repytah.transform import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## remove_overlaps\n",
    "\n",
    "`remove_overlaps` removes any pairs of repeat length and specific annotation marker where there exists at least one pair of repeats that overlap in time.\n",
    "\n",
    "The inputs for the function are:\n",
    "- __input_mat__ (np.ndarray): A list of pairs of repeats with annotations marked. The first two columns refer to the first repeat, the second two columns refer to the second repeat, the fifth column denotes repeat length, and the last column contains the annotation markers.\n",
    "- __song_length__ (int): The number of audio shingles in the song\n",
    "\n",
    "The outputs for the function are:\n",
    "- __lst_no_overlaps__ (np.ndarray): A list of pairs of non-overlapping repeats with annotations marked. All the repeats of a given length and with a specific annotation marker do not overlap in time.\n",
    "- __matrix_no_overlaps__ (np.ndarray): A matrix representation of **lst\\_no\\_overlaps** where each row corresponds to a group of repeats\n",
    "- __key_no_overlaps__ (np.ndarray): A vector containing the lengths of the repeats in each row of **matrix\\_no\\_overlaps**\n",
    "- __annotations_no_overlaps__ (np.ndarray): A vector containing the annotations of the repeats in each row of **matrix\\_no\\_overlaps**\n",
    "- __all_overlap_lst__ (np.ndarray): A list of pairs of repeats with annotations marked removed from **input\\_mat**. For each pair of repeat length and specific annotation marker, there exists at least one pair of repeats that overlap in time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The input array is: \n",
      " [[ 1  4 11 14  4  1]\n",
      " [ 4  7 14 17  4  1]\n",
      " [ 2  3 12 13  2  1]]\n",
      "The number of shingles is: 20\n"
     ]
    }
   ],
   "source": [
    "input_mat = np.array([[1, 4, 11, 14, 4, 1],\n",
    "                      [4, 7, 14, 17, 4, 1],\n",
    "                      [2, 3, 12, 13, 2, 1]])\n",
    "song_length = 20\n",
    "\n",
    "print(\"The input array is: \\n\", input_mat)\n",
    "print(\"The number of shingles is:\", song_length)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The array of the non-overlapping repeats is: \n",
      " [[ 2  3 12 13  2  1]]\n",
      "The matrix representation of the non-overlapping repeats is: \n",
      " [[0 1 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0]]\n",
      "The lengths of the repeats in matrix_no_overlaps are: \n",
      " [2]\n",
      "The annotations from matrix_no_overlaps are: \n",
      " [1]\n",
      "The array of overlapping repeats is: \n",
      " [[ 1  4 11 14  4  1]\n",
      " [ 4  7 14 17  4  2]]\n"
     ]
    }
   ],
   "source": [
    "lst_no_overlaps, matrix_no_overlaps, key_no_overlaps, annotations_no_overlaps, all_overlap_lst = remove_overlaps(input_mat, song_length)\n",
    "\n",
    "\n",
    "print(\"The array of the non-overlapping repeats is: \\n\", lst_no_overlaps)\n",
    "print(\"The matrix representation of the non-overlapping repeats is: \\n\", matrix_no_overlaps)\n",
    "print(\"The lengths of the repeats in matrix_no_overlaps are: \\n\", key_no_overlaps)\n",
    "print(\"The annotations from matrix_no_overlaps are: \\n\", annotations_no_overlaps)\n",
    "print(\"The array of overlapping repeats is: \\n\", all_overlap_lst)"
   ]
  }
 ],
 "metadata": {
  "interpreter": {
   "hash": "f9558a7a9c0790c2334a9072034da5d30cf10fd46d803cfe3584dbca0180200c"
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
