Modules.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# ** Modules **\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Functions are a convenient way of packaging parts of the code that carry out a particular operation. However sometimes we want to package a series of functions and constants that help accomplish related tasks (for instance, read and write common bioinformatics file formats) into a separate file for convenience of reuse. In python, such a file is called a *module* and we can think of it as a library of functions. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# run this cell to show a video, use slider to resize it, type Esc-o to hide it\n",
    "from IPython.display import Video, clear_output; from ipywidgets import interactive, IntSlider\n",
    "def _play(resize): display(Video(filename=\"media/ECS780P_Modules_topicSummary.mp4\",data=\"\",width=resize))\n",
    "interactive(_play, resize=IntSlider(min=150, max=900, step=50, value=600, continuous_update=False, readout=False))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Importing modules"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Modules need to be imported before they can be used. This is done with the ```import``` keyword. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os # low level operating system functions\n",
    "dir(os)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(os.getcwd()) # a function that returns the current working directory"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "os.sep # a constant that represents the OS' path separator character"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that all references to constants, functions and variables defined by the module include the name of the module. We say that the module defines a *namespace*. This is to avoid variables and functions within the module to conflict with those you may have defined in your program, using the same name.\n",
    "\n",
    "We can just import a single function from the module and use it directly without the module name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from os import getcwd\n",
    "\n",
    "print(getcwd())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or we can import everything into the main namespace, but that is risky as it can override other definitions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from os import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**In general**, it is better to import a module into a separate namespace, using maybe an *alias* if the name is too long; let us see an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import time as tm # saves 2 keystrokes each time; the 'alias' here is tm\n",
    "now = tm.localtime()\n",
    "print(tm.asctime(now)) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Installing modules"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The [Python Standard Library](https://docs.python.org/3/library/) provides a rich selection of modules that you can use to perform all sorts of operations, from formatting text to accessing web sites programmatically and even processing multimedia files. These should be included with every Python installation.\n",
    "\n",
    "Most other Python libraries are in fact organised into packages and available online from the [PyPI](https://pypi.python.org/pypi) website. A description of what a package is can be found in the online\n",
    "[documentation](https://docs.python.org/3/tutorial/modules.html#packages), but for the time being don't worry about it - they are sets of modules, and by and large they\n",
    "work just like modules.\n",
    "\n",
    "Your machine should have *pip* installed, or you can install it as explained [here](https://pypi.org/project/pip/) (for Linux distributions, this may be as easy as installing a .rpm or .deb file).\n",
    "\n",
    "Once that is done, installing any Python packages you require from the repository is straightforward; just type\n",
    "```\n",
    "pip install PACKAGE_NAME\n",
    "```\n",
    "that's all that there is to it; *pip* will find the most recent version, download it and install it for you. It will also fetch and install any modules required by the one you want installed.\n",
    "\n",
    "**NOTE:** If you have installed the [Anaconda](https://www.anaconda.com/products/individual) Python distribution on your machine, you will have *conda* instead than *pip*. That is just as good; please refer to the [conda documentation](https://docs.conda.io/projects/conda/en/latest/) instead."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# run this cell to show a video, use slider to resize it, type Esc-o to hide it\n",
    "from IPython.display import Video, clear_output; from ipywidgets import interactive, IntSlider\n",
    "def _play(resize): display(Video(filename=\"media/ECS780P_Modules_ImportAndInstall.mp4\",data=\"\",width=resize))\n",
    "interactive(_play, resize=IntSlider(min=150, max=900, step=50, value=600, continuous_update=False, readout=False))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Writing modules"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Writing modules isn't more difficult than writing any other Python program. You can in fact put some code into a separate file and import it. For instance, we may want to package the function that reads a FASTA file into a function and put it into a module for easy reuse. We'll call this module *fastaio.py*. This example will be done in class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Ignore, this is just an IPython trick\n",
    "# that creates the link below\n",
    "from IPython.display import FileLink\n",
    "FileLink('fastaio.py')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once we have done this, we should be able to run the following code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import fastaio as fas\n",
    "\n",
    "protein = fas.read(\"P04637.fas\")\n",
    "print(protein)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Testing modules"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A module is, after all, only a piece of Python code. So there is nothing preventing you from running the *fastaio.py* module stand-alone by typing\n",
    "```\n",
    "python fastaio.py\n",
    "```\n",
    "on the command line. Since this module only defines a function and does not actually contain any instruction to call it, nothing will happen.\n",
    "\n",
    "Instructions within a module (outside functions) can be used to define constants and perform required initialisation within your module; these are run only once when the module is imported. \n",
    "\n",
    "Within a module, the name of the module is made available through the global variable ```__name__```. When the module is run stand-alone rather than imported, this variable is set to ```\"__main__\"```. This can be used to code some tests that shall only run when the module is invoked directly from the command line. Typically, one would write\n",
    "```\n",
    "if __name__== \"__main__\": # we have been launched stand-alone\n",
    "    # Do some tests here\n",
    "```\n",
    "This feature will be demonstrated in class if time allows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# run this cell to show a video, use slider to resize it, type Esc-o to hide it\n",
    "from IPython.display import Video, clear_output; from ipywidgets import interactive, IntSlider\n",
    "def _play(resize): display(Video(filename=\"media/ECS780P_Functions_WriteAndTest.mp4\",data=\"\",width=resize))\n",
    "interactive(_play, resize=IntSlider(min=150, max=900, step=50, value=600, continuous_update=False, readout=False))"
   ]
  }
 ],
 "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.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}