{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": "# Libraries and documentation\n\n```{admonition} Interactive page\n:class: warning, dropdown\nThis is an interactive book page. Press launch button at the top right side.\n```\n\n## Python packages\n\n**Packages are building blocks of programming**.\nPackages consist of **reusable pieces of code** so that you do not have to program everything from scratch (and, thereby, you don't have to keep \"reinventing the wheel\"). \nSometimes we refer to published packages as **libraries**.\nAccording to [Python packages](https://py-pkgs.org/01-introduction.html), there is over 350,000 Python packages (based on data from 2022), and the number keeps growing. This means that there is **a lot of code out there for you to reuse**!" }, { "cell_type": "markdown", "metadata": {}, "source": [ "```{admonition} Why use packages?\n", ":class: note, dropdown\n", "Imagine you are working with a vector of numbers and, using Python, you wish to calculate the average of the numbers in your vector.\n", "As you can imagine, many people before you have wanted to do the same thing in Python.\n", "\n", "To prevent programmers from reinventing the same pieces of code time and again, there are Python packages available, each containing pre-made code (such as code for calculating an average). Another good reason to use packages is computational efficiency - the code from the packages often runs much faster than the code you would write yourself (due to some Python features). More on this in a [later section on vectorization](../chapter-10-numpy/vectorization.ipynb).\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": "\n```{admonition} Useful packages\n:class: tip, dropdown\nPython packages often focus on a **specific problem or domain**. Sometimes several libraries offer options that will result in the same outcome, e.g., you can make an xy scatter plot with more than one library. \\\nHere we offer an overview of some widely used Python packages that will likely come handy in your nanobiology studies and research. Packages that we will use **in this book** are shown in bold.\n* Plotting and visualization\n * **Matplotlib**\n * **seaborn** \n * Plotly \n * **NaNoPy**\n* Scientific computing\n * **NumPy**\n * SciPy\n* Bioinformatics\n * Biopython\n* Data analysis\n * **pandas**\n* Machine learning\n * Scikit-learn\n * PyTorch\n* Utilities and tools\n * os\n * re\n * **pathlib**\n\n```" }, { "cell_type": "markdown", "metadata": {}, "source": [ "```{admonition} Naming conflicts\n", ":class: warning\n", "**DO NOT** use variable names that are the same as function names or package names. Examples are `list`, `str`, `print`, or `numpy`. This can **override the original meaning** and cause **unexpected errors**.\n", "\n", "Similarly, **AVOID** naming your **Python files** (e.g., `numpy.py`) after libraries or third-party packages. Doing so can **confuse the import system** and **prevent you from using the real package** in your code.\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": "### Importing a package\n\nWhen you want to use a package in your code, you have to tell that to Python explicitly. We call this **importing a package** into the *namespace* of your kernel. Namespace is a container that holds a collection of functions and variable names.\n\nYou typically do this at the very beginning of your Python script by using a line such as this:\n\n```\nimport random\n```\n\nIf you have multiple packages to import, you put several import lines one beneath the other:\n\n```\nimport numpy\nimport random\n```\n\nIn order to use a package, you have to make sure it's actually **installed**. Some packages, such as `random` and `math`, are part of Python's **standard library**: they come with Python itself, so you never need to install them. Other packages, such as NumPy, have to be installed separately. For this course, you already did that when you [created a conda environment](../chapter-02-installation/setting-up-environment.md) from the file env.yaml: it installs all packages needed for this course from [conda-forge](https://conda-forge.org/), a community-maintained collection of packages.\n\nIn case you want to install a package on your own, two popular tools to do that are `pip` and `conda`. In practice, installing a package (such as NumPy) is as simple as **opening your terminal and running one of these lines**:\n\n```\nconda install numpy\n```\n\nor \n\n```\npip install numpy\n```\n\n```{admonition} Installation into your current environment\n:class: important\nRunning `conda install numpy` installs NumPy into the currently active environment. If you want to install NumPy into a different environment, make sure to run `conda deactivate`, then `conda activate ` before running `conda install numpy`. \n```\n\n```{admonition} Windows vs. macOS/Linux\n:class: important\nWhen needed, run the package installation commands in your Bash terminal for macOS/Linux, and in Anaconda Prompt terminal for Windows.\n```\n\nIf you're unsure **whether a Python package is installed**, you can also simply check it in your terminal using `pip list` or `conda list`. Check with `conda` - do you already have NumPy installed in `pf-env`?\n\n```{admonition} Pip vs. conda\n:class: note, dropdown\nBoth `pip` and `conda` can be used to install packages, so what are the differences between them?\nThere are [three differences](https://numpy.org/install/):\n1. `conda` is cross-language, meaning that it can also install non-Python libraries and tools, while `pip` is for Python only.\n2. `conda` installs from its own channels, while `pip` installs from the Python Packaging Index. The latter is the largest collection of packages, but all popular ones are also available with `conda`.\n3. `conda` is an integrated tool for managing packages, dependencies, and environments, while with `pip` you may need other tools for dealing with environments (see below) or complex dependencies.\n```" }, { "cell_type": "markdown", "metadata": {}, "source": "### Packages contain functions\n\nBut what does a package actually look like, what's inside it?\nA package contains **functions**, with each function performing a specific **task**.\nA function typically also has a set of **arguments**, which allow you to pass information into the function to tailor what exactly it will do. \nDepending on a function, the arguments can be:\n- **mandatory** - you **have to** specify this for a function to work\n- **optional** - you **can** set this parameter yourself; if you don't, there is a **default** value that the function uses\n\nThis is actually also true for Python's built-in functions, such as `print()` and `input()`, which we've seen earlier.\n\n\n#### Reading documentation\n\nWhen you encounter a new function, you will wonder \"how do I use it exactly?\" This is where **documentation** becomes immensely useful, and it's crucial to know **how to read it**.\n\nYou can access documentation online or directly in Python (such as in code cells here in the book and in your VS Code).\nThe online Python [documentation](https://docs.python.org/3/library/index.html) contains information about built-in functions and more. \nThere are also dedicated package documentations such as the one for NumPy, which has information about NumPy's functions.\n\nLet's look at an example of a function from the `random` package called `random.choices()`, which picks random elements from a list. \nTo learn which arguments this function takes, you can either type `?random.choices` to ask Python here in the book or in your VS Code, or check this function's [online documentation](https://docs.python.org/3/library/random.html#random.choices).\nIf you do that, you will see\n\n```\nrandom.choices(population, weights=None, *, cum_weights=None, k=1)\n```\n\nfollowed by explanations about each argument, as well as information on whether it's mandatory or optional (in `random.choices()`, only the first one is mandatory). Depending on the argument, you will also be able to read what is its default value. At the end, there are a few concrete examples of usage of this function.\n\n```{admonition} AI tip\n:class: ai\nNeed a more detailed explanation of a function, or wish to see more examples of its usage? Refer to AI.\n```\n\nLet's try using `random.choices()` ourselves:\n" }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [ "remove-output" ] }, "outputs": [], "source": [ "# First we have to import random\n", "import random\n", "\n", "# Pick 10 random nucleotides\n", "random.choices(['A', 'C', 'G', 'T'], k=10)\n", "\n", "# To see help for random.choices, type ?random.choices" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "````{admonition} Asterisk * in function descriptions\n", ":class: tip\n", "\n", "The asterisk `*` in a Python function description indicates that all the **following parameters are keyword-only**. This means they must be specified using their names when calling the function.\n", "\n", "For example, with our function `random.choices(population, weights=None, *, cum_weights=None, k=1)`, if we want to use the last argument, we have to write:\n", "\n", "```\n", "random.choices(['A', 'C', 'G', 'T'], None, k=5)\n", "```\n", "\n", "rather than just:\n", "\n", "```\n", "random.choices(['A', 'C', 'G', 'T'], None, None, 5)\n", "```\n", "\n", "Therefore, for the parameter `k` which is listed after the asterisk, we have to explicitly write `k=`.\n", "\n", "````" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In general, when you wish to use a function from a specific library, such as `random.choices()`, you need to define a library by using (in this case) `random.` in its name.\n", "To save you from some typing, you can also tell Python how you want to refer to functions from a specific package. For example, with this import line:\n", "\n", "```\n", "import random as rnd\n", "```\n", "\n", "you can invoke its functions using `rnd.`, e.g., `rnd.choices()` rather than the longer `random.choices()`. For some packages, a short name is a widely used convention, such as `import numpy as np`, which you will see in the next chapter.\n", "Try recreating the code from above, but using `rnd` for random." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [ "remove-output" ] }, "outputs": [], "source": [ "# Your code here - pick 10 random nucleotides with rnd.choices" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Importing a single function\n", "\n", "When we import random with `import random as rnd`, we get access to all its functions by adding `rnd.` in front of the function name.\n", "To see which functions are in the library, type `dir(random)`, which will generate a list of available functions.\n", "The list of functions can be quite long and exhaustive.\n", "\n", "If you **need only a single function from a library**, there is a second commonly used way to import only that single function, e.g.:\n", "\n", "```\n", "from random import choices\n", "```\n", "\n", "When you do this, the function `choices()` will be available directly, without any prefix:" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [ "remove-output" ] }, "outputs": [], "source": [ "from random import choices\n", "sequence = choices(['A', 'C', 'G', 'T'], k=10)\n", "print(sequence)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If you look around on the internet, you will also find people that do the following:\n", "\n", "```\n", "from random import *\n", "```\n", "\n", "(Remember: `*` is a [wildcard](../chapter-03-terminal/bash-commands.ipynb) and here replaces a function with *any* name.)\n", "\n", "This will import all the functions from random directly into the namespace with no `rnd.` or `random.` prefix. You might think: what a great idea, this will save me loads of typing! Instead of typing `random.choices()` I could just type `choices()`, and so on for all the other functions in random. \n", "\n", "While it's true that it will save typing, it also comes with a high risk: sometimes **different packages have functions that have the same name**, but do different things. A concrete example is the function `sqrt()`, which is available in both `math` and `numpy` libraries. Unfortunately, `math.sqrt()` will give an error when using NumPy arrays. \n", "\n", "If you import both of these libraries with the command above (using `*`), you will overwrite these functions by the second import, and if you're not careful, you will forget which one you are using. This could cause your code to \"break\". It will also \"crowd\" your namespace: you suddenly have hundreds or even thousands of functions, instead of just a library. \n", "\n", "For these reasons, it is generally **advised not to use `import *`**, and it is considered a **poor coding practice** in Python." ] } ], "metadata": { "jupytext": { "formats": "ipynb,md" }, "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.10.18" } }, "nbformat": 4, "nbformat_minor": 4 }