notebooks/get-started.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting Started"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's go over basic functionality and use cases of CanDI package. \n",
    "\n",
    "### Importing\n",
    "\n",
    "CanDI must be imported from from the main CanDI directory. The core CanDI objects are contained within the CanDI.candi module and are imported as follows. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import CanDI.candi as can\n",
    "#Can also be imported as \n",
    "from CanDI import candi as can"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Data Object\n",
    "The Data object is instantiated when CanDI and access as data within the candi module\n",
    "CanDI dataset paths are defined as attributes within the Data object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(can.data.gene_effect) # depmap ceres score\n",
    "print(can.data.expression) # ccle rna seq data\n",
    "print(can.data.gene_cn) # ccle copy number data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How to Directly Load a Dataset\n",
    "The load method of the Data object is used to load specific datasets into memory. The datasets are saved as pandas dataframes as attributes of the data object. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "can.data.load(\"expression\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Cell Lines\n",
    "The Cell Lines dataset contains all cell line metadata. This table is loaded automatically when candi is imported."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "can.data.cell_lines.head(5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Genes\n",
    "The genes dataset contains relevant gene metadata. \n",
    "The genes dataset is loaded into memory automatically when candi is imported. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "can.data.genes.head(5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Locations\n",
    "The locations dataset contains location annotations for all genes and their associated confidence scores. Confidence scores were crowd sourced from several protein localization papers and integrated into one scale. This dataset is automatically loaded into memory when candi is imported. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "can.data.locations.head(5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic Object Instantiation\n",
    "- The user input for object instantiation is used directly for indexing\n",
    "- This means if it is misspelled candi will not be able to retrieve the data in which the user is interested\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kras = can.Gene(\"KRAS\")\n",
    "lung = can.Cancer(\"Lung Cancer\")\n",
    "membrane = can.Organelle(\"Plasma membrane\")\n",
    "a549 = can.CellLine(\"A549\") "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Gene Object Methods and Attributes\n",
    "The following function prints the internal attributes and functions of CanDI objects. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def pretty_print_attr(obj):\n",
    "    attr = []\n",
    "    ls_attr = []\n",
    "    meth = []\n",
    "    for i in dir(obj):\n",
    "        if \"_\" != i[0]:\n",
    "            if type(getattr(obj, i)) == str or type(getattr(obj, i)) == int:\n",
    "                attr.append(i)\n",
    "            elif type(getattr(obj, i)) == list:\n",
    "                ls_attr.append(i)\n",
    "            else:\n",
    "                meth.append(i)\n",
    "                \n",
    "    print(\"Attributes:\\n\")\n",
    "    for i in attr: print(i+\":\", getattr(obj, i))\n",
    "    for i in ls_attr: print(i+\" list first item:\", getattr(obj, i)[0])\n",
    "    for i in ls_attr: print(i+\" length:\", len(getattr(obj, i)))\n",
    "    print(\"\\nMethods:\\n\")\n",
    "    for i in meth: print(i)\n",
    "\n",
    "pretty_print_attr(kras)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Gene Indexing examples\n",
    "If a dataset has not be loaded into memory candi will prompt you.\n",
    "Once a dataset is loaded, Gene.expression gives all the rna seq transcript data for that specific object.\n",
    "In this case we have already instantiated a gene object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kras.expression"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Basic CanDI filtering\n",
    "the Gene.expressed() method retrieves cell lines where the user defined gene has above 1 transcript per million\n",
    "the output is a list of cell line ids which can be used to instantiate CellLine or CellLineClbbuster objects\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kras.expressed()[0:10]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The user can specify if they want the tpm values with the depmap ids "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kras.expressed(style=\"values\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you input a depmap id as an argument to gene.expressed you will get a boolean showing the expression status of your gene"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kras.expressed(a549.depmap_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The user can use the gene.expression_of() method to check that gene's expression in a specific cell line.\n",
    "This method only, when called from a Gene object, accepts cell line depmap id's as an argument."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kras.expression_of(a549.depmap_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "CanDI is consistent in the way this works across all classes and data types"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kras.mutations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The gene.mutated() method allows very specific filtering.\n",
    "Using the variant argument one can select the column on which to filter. Then using the item argument the user can specifiy the specific value in which they're interested. The example below shows retrieval of all cell lines with kras missense mutations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kras.mutated(variant=\"Variant_Classification\", item=\"Missense_Mutation\")[0:10]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Users can use the unload method of the Data object to remove a dataset from memory and return it to a file path string."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "can.data.unload('mutations')\n",
    "can.data.mutations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## CellLine Methods and Attributes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pretty_print_attr(a549)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All methods work in essentially same way regardless of the candi object in use.\n",
    "The CellLine.expressed() method will return all genes which have expression above 1 transcript per million\n",
    "in that specific cell line."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a549.expressed()[:10]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Just like gene.expressed() the user can ask for the values"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a549.expressed(style=\"values\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And for specific genes expression status"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a549.expressed(\"KRAS\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "expressed with style=\"values\" gives the same result as expression_of"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a549.expression_of(\"KRAS\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a549.expressed(\"KRAS\", style=\"values\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The CellLine.mtuations attribute gives all mutation data for that specific cell line"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a549.mutations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# calling the CellLine.mutated() method works the same way with all CanDI objects\n",
    "a549.mutated(variant=\"Variant_Classification\", item=\"Nonsense_Mutation\")[:10]\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Cancer Methods and Attributes\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pretty_print_attr(lung)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cancer objects work essentially works as a group of cell line objects \n",
    "the Cancer.expression object returns a pandas dataframe rather than a pandas series since there are multiple cell lines to consider."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lung.expression"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cancer.expressed method uses an abitrary threshold to filter genes the default is if a gene is expressed in 100 percent of the cell lines within the cancer object it will read out as expressed"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lung.expressed()[0:10]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The user can relax this threshold as necessary"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lung.expressed(threshold=0.50)[0:10]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lung.expressed(threshold=0.50, style=\"values\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cancer and CellLineCluster objects have an additional method that outputs a binary matrix\n",
    "of which genes/cell lines have mutations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lung.mutation_matrix()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Organelle Methods and Attributes\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pretty_print_attr(membrane)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.12.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}