diff --git a/_toc.yml b/_toc.yml index 57b637a12..3fdf06934 100644 --- a/_toc.yml +++ b/_toc.yml @@ -19,6 +19,8 @@ - file: foundations/Hello - file: foundations/how-to-run-python sections: + - file: foundations/terminal + - file: foundations/jupyter - file: foundations/conda - file: foundations/getting-started-jupyter sections: diff --git a/foundations/conda.md b/foundations/conda.md index c75f73447..14274b728 100644 --- a/foundations/conda.md +++ b/foundations/conda.md @@ -1,5 +1,95 @@ -# Using the conda package manager +# Installing and Managing Python with Conda -```{note} -This content is under construction! +Conda is an open-source, cross-platform, language-agnostic package manager and environment management system that allows you to quickly install, run, and update packages within your work environment(s). + +Here we will cover: + +- What are packages? +- Installing Conda +- Creating a Conda environment +- Useful Conda commands + +## What are Packages? + +A Python package is a collection of modules, which in turn, are essentially Python scripts that contain published functionality. There are Python packages for data input, data analysis, data visualization, etc. Each package offers a unique toolset and may have its own unique syntax rules. + +Package management is useful because you may want to update a package for one of your projects, but keep it at the same version in other projects to ensure that they continue to run as expected. + +## Installing Conda + +We recommend you install Miniconda. You can do that by following the [instructions for you machine](https://docs.conda.io/en/latest/miniconda.html). + +Miniconda only comes with the `conda` package management system; it is a pared-down version of the full Anaconda Python distribution. + +[Installing Anaconda](https://docs.anaconda.com/anaconda/install/) takes longer and takes up more disk space, but provides you with more functionality: Jupyter, Spyder (a Python-specific integrated development platform or IDE), as well as other immediately installed packages. The interface of Anaconda is great if you are uncomfortable with the terminal. + +We recommend Miniconda for two reasons: + +1. It's quicker and takes up less disk space. +2. It encourages you to install only the packages you need in reproducible isolated environments for specific projects. This is generally a more robust way to work with open source tools. + +Once you have `conda` via the Miniconda installer, the next step is to create an environment and install packages. + +## Creating a Conda Environment + +A conda environment is an interoperable collection of specific versions of packages or libraries that you install and use for a specific workflow. The conda package manager takes care of dependencies so everything works together in a predictable way. One huge advantage of using environments is that any changes you make to one environment will not affect your other environments at all, so you are much less likely to "break" something! + +To create a new Conda environment, type `conda create --name` and the name of your environment in your terminal, and then specify any packages that you would like to have installed. For example, to install a Jupyter-ready environment called `sample_environment`, type + +``` +conda create --name sample_environment python jupyterlab ``` + +Once the environment is created, you need to _activate_ it in the current terminal session (see below) + +It is a good idea to create new environments for different projects because since Python is open source, new versions of the tools are released very frequently. Isolated environments help guarantee that your script will use the same versions of packages and libraries and should run the same as you expect it to. Similarly, it is best practice to NOT modify your `base` environment. + +## Useful Conda commands + +Some other Conda commands that you will find useful include: + +- Activating a specific environment + +``` +conda activate sample_environment +``` + +- Deactivating the current environment + +``` +conda deactivate +``` + +- Checking what packages/versions are installed in the current environment + +``` +conda list +``` + +- Installing a new package into current environment + +``` +conda install somepackage +``` + +- Installing a specific version of a package + +``` +conda install somepackage=0.17 +``` + +- Checking what conda environments you have + +``` +conda env list +``` + +- Deleting an environment + +``` +conda env remove --name sample_environment +``` + +Lots more information is in the [conda documentation](https://docs.conda.io/) or this handy [conda cheat sheet](https://docs.conda.io/projects/conda/en/latest/_downloads/843d9e0198f2a193a3484886fa28163c/conda-cheatsheet.pdf) + +If you're not a command line user, the Anaconda navigator offers GUI functionality for selecting environments and installing packages. diff --git a/foundations/getting-started-python.md b/foundations/getting-started-python.md index 7c1ad9890..33266b751 100644 --- a/foundations/getting-started-python.md +++ b/foundations/getting-started-python.md @@ -9,4 +9,4 @@ This is the starting point for a new user who wants to learn how to get started. ## Topics - [Quickstart: what is Python?](basic-python): Basic tutorials on the Python language -- [How to run Python code](how-to-run-python): Instructions for installing Python on a laptop or running in the cloud +- [Installing and Running Python](how-to-run-python): Instructions for installing Python on a laptop diff --git a/foundations/how-to-run-python.md b/foundations/how-to-run-python.md index 6e94f9d68..bbf7e25fd 100644 --- a/foundations/how-to-run-python.md +++ b/foundations/how-to-run-python.md @@ -1,10 +1,46 @@ -# How to run Python +# Installing and Running Python -```{note} -This content is under construction! -``` +This section provides an overview of different ways to run Python code, and quickstart guides for -This section will give an overview of different ways to run Python code, and quickstart guides for +- Choosing a Python platform +- Installing and running Python on various local platforms +- Installing and managing Python with Conda -- Installing Python on a laptop with the conda package manager -- Running Python in the cloud +## Choosing a Python Platform + +There is no single official platform for the Python language. Here we provide a brief rundown of 3 popular platforms: + +1. The terminal, +2. Jupyter notebooks, and +3. IDEs (integrated development environment). + +Here we hope to provide you with enough information to understand the differences and similarities between each platform so that you can make the best chose for your work environment and learn along effectively, regardless of your Python platform preference. + +In general, it is always best to test your programs in the same environment in which they will be run. The biggest factors to consider when choosing your platform are: + +- What are you already comfortable with? +- What are the people around you using (peers, coworkers, instructors, etc)? + +### Terminal + +For learners who are familiar with basic [Linux commands](https://cheatography.com/davechild/cheat-sheets/linux-command-line/) and text editors (such as Vi/Cim or Nano), running Python in the terminal is the quickest route straight to learning Python syntax without the covering the bells and whistles of a new platform. If you are running Python on a super computer, through an HTTP request, or ssh tunneling you might want to consider learning in the terminal. + +[How to Run Python in the Terminal](terminal.md) + +### Jupyter Notebooks + +We highly encourage the use of Jupyter notebooks; a free, open-source, interactive tool running inside a web browser that allows you to run Python code in "cells." This means that your workflow can alternate between code, output, and even Markdown-formatted explanatory sections that create an easy to follow analysis or "computational narrative" from start to finish. Jupyter notebooks are a great option for presentations or learning tools. For these reasons Jupyter is very popular among scientists. Most lessons in this book will be taught via Jupyter notebooks. + +[How to Run Python in a Jupyter Session](jupyter.md) + +### Other IDEs + +If you code in other languages you might already have a favorite IDE that will work just as well in Python. [Spyder](https://www.spyder-ide.org) is a Python specific IDE that comes with the [Anaconda download](https://www.anaconda.com/products/individual). It is perhaps the most familiar IDE if you are coming from languages such as [Matlab](https://www.mathworks.com/products/matlab.html) that have a language specific platform and display a list of variables. [PyCharm](https://www.jetbrains.com/pycharm/) and [Visual Studio Code](https://code.visualstudio.com) are also popular IDEs. Many IDEs offer support for terminal execution, scripts, and Jupyter display. To learn about your specific IDE visit its official documentation. + +_We recommend eventually learning how to develop and run Python code in each of these platforms._ + +## Installing and managing Python with Conda + +Conda is an open-source, cross-platform, language-agnostic package manager and environment management system that allows you to quickly install, run, and update packages within your work environment(s). Conda is a vital component of the Python ecosystem, and understanding it is important regardless of the platform you chose to run your Python code. + +[Learn more about Conda here](conda.md) diff --git a/foundations/jupyter.md b/foundations/jupyter.md new file mode 100644 index 000000000..e64517f37 --- /dev/null +++ b/foundations/jupyter.md @@ -0,0 +1,83 @@ +# Python in Jupyter + +You'd like to learn to run Python in a Jupyter session. Here we will cover: + +- Installing Python in Jupyter +- Running Python code in Jupyter +- Saving your notebook and exiting + +## Installing Python in Jupyter + +To run a Jupyter session you will need to install some necessary packages into your Conda environment. + +You can install `miniconda`. You can do that by following the [instructions for you machine](https://docs.conda.io/en/latest/miniconda.html). + +[Learn more about Conda here](conda.md) + +Then create a Conda environment with Jupyter Lab installed. In the terminal type: + +``` +$ conda create --name pythia_foundations_env jupyterlab +``` + +Test that you have installed everything correctly by first activating your environment and then launching a Jupyter Lab session: + +``` +$ conda activate pythia_foundations_env +$ jupyter lab +``` + +Or you can install the full [Anaconda](https://www.anaconda.com/products/individual), and select **LAUNCH** under the Jupyter panel in the GUI. + +![Anaconda Navigator](../images/Anaconda.png) + +In both methods, a new window should open automatically in your default browser. You can change the browser when launching from the terminal with (for example): + +``` +jupyter lab —browser=chrome +``` + +## Running Python in Jupyter + +1. With your Conda environment activated and Jupyter session launched (see above), create a directory to store our work. Let's call it `pythia-foundations`. + + ![Jupyter GUI](../images/jupyter_gui.png) + + You can do this in the GUI left side bar by clicking the new-folder icon. If you prefer to use the command line you can access a terminal by clicking the icon under the "Other" heading in the Launcher. + +2. Create a new `mysci.ipynb` file within the `pythia-foundations` folder: + + Do this in the GUI on the left side bar by clicking the "+" icon. + + This will open a new launcher window where you can select a Python kernel under the "Notebooks" heading for your project. _You should see "Python 3" as in the screenshot above._ Depending on the details of your system, you might see some additional buttons with different kernels. + + Selecting a kernel will open a Jupyter notebook instance and add an untitled file to the left side bar navigator, which you can then rename to `mysci.ipynb`. + + Select "Python 3" to use the Python version you just installed in the `pythia_foundations_env` conda environment. + +3. Change the first notebook cell to include the classic first command - printing, "Hello, world!". + + ```python + print("Hello, world!") + ``` + +4. Run your cell with **SHIFT ENTER** and see that the results are printed below the cell. + + ![Jupyter - Hello World](../images/mysci.png) + +**Congratulations!** You have just set up your first Python environment and run your first Python code in a Jupyter notebook. + +## Saving your notebook and exiting + +When you are done with your work, it is time to save and exit. + +To save your file, you can click the disc icon in the upper left Jupyter toolbar or use keyboard shortcuts. + +Jupyter allows you to close the browser tab without shutting down the server. When you're done working on your notebook, _it's important to **click the "Shutdown" button** on the dashboard_ to free up memory, especially on a shared system. + +Then you can quit Jupyter by: + +- clicking the "Quit" button on the top right, or +- typing `exit` into the terminal + +Alternatively you can simultaneously shutdown and exit the Jupyter session by typing `Ctrl-C` in the terminal and confirming that you do want to "shutdown this notebook server." diff --git a/foundations/terminal.md b/foundations/terminal.md new file mode 100644 index 000000000..57bade832 --- /dev/null +++ b/foundations/terminal.md @@ -0,0 +1,73 @@ +# Python in the Terminal + +You'd like to learn to run Python in the terminal. Here we will cover: + +- Installing Python in the terminal +- Running Python code in the terminal + +## Installing Python in the Terminal + +If running Python in the terminal, it is best to install Miniconda. You can do that by following the [instructions for you machine](https://docs.conda.io/en/latest/miniconda.html). + +[Learn more about Conda here](conda.md) + +Then create a Conda environment with Python installed by typing the following into your terminal: + +``` +$ conda create --name pythia_foundations_env python +``` + +You can test this by running `python` in the command line. + +## Running Python in the Terminal + +On Windows, open **Anaconda Prompt**. On a Mac or Linux machine, simply open **Terminal**. + +1. Activate your Conda environment: + + ``` + $ conda activate pythia_foundations_env + ``` + +2. Create a directory to store our work. Let's call it `pythia-foundations`. + + ``` + $ mkdir pythia-foundations + ``` + +3. Go into the directory: + + ``` + $ cd pythia-foundations + ``` + +4. Create a new Python file: + + ``` + $ touch mysci.py + ``` + +5. And now that you've set up our workspace, edit the `mysci.py` script using your favorite text editor (nano, e.g.): + + ``` + $ nano mysci.py + ``` + +6. Change the script to include the classic first command - printing, "Hello, world!". + + ```python + print("Hello, world!") + ``` + +7. Save your file and exit the navigator. How to do this is dependent on your chosen text editor. + + - In Vim the command is `:wq`. + - In Nano it is `Ctrl + O` to save and `Ctrl + X` to exit (where you will be prompted if you want to save it, if modified). + +8. In the terminal, execute your script: + + ``` + $ python mysci.py + ``` + +**Congratulations!** You have just set up your first Python environment and run your first Python script in the terminal. diff --git a/images/Anaconda.png b/images/Anaconda.png new file mode 100644 index 000000000..7cb61c0f2 Binary files /dev/null and b/images/Anaconda.png differ diff --git a/images/jupyter_gui.png b/images/jupyter_gui.png new file mode 100644 index 000000000..8ac5dfe39 Binary files /dev/null and b/images/jupyter_gui.png differ diff --git a/images/mysci.png b/images/mysci.png new file mode 100644 index 000000000..ffd37a733 Binary files /dev/null and b/images/mysci.png differ