Please come to the workshop with a laptop already configured as described below. If you have any problems with any of these steps, please check if your problem has already been reported at the issue tracker. If not, ask your question in the issue tracker.
For the commands shown, % (and anything to the left of it) represents the
terminal prompt. You do not need to copy it; instead only copy the command to the
right of %.
Download the workshop folder using git:
% git clone https://github.com/astropy/astropy-workshop.git
If you don't have git installed, you can download the ZIP file by pressing the green Clone or download button at https://github.com/astropy/astropy-workshop and selecting Download ZIP. However, this option is not recommended because it impedes the ability to update your copy of the repository if updates are made.
Miniconda is a free minimal installer for conda. It is a small, bootstrap version of Anaconda that includes only conda, Python, the packages they depend on, and a small number of other useful packages, including pip, zlib and a few others. Note, though, that if you have either Miniconda or the full Anaconda already installed, you can skip to the next step.
Check if Miniconda is already installed.
% conda info
If Miniconda is not already installed, follow these instructions for your operating system: https://docs.conda.io/en/latest/miniconda.html
On Windows, you might also need additional compilers.
Miniconda includes an environment manager called conda. Environments allow you to have multiple sets of Python packages installed at the same time, making reproducibility and upgrades easier. You can create, export, list, remove, and update environments that have different versions of Python and/or packages installed in them.
Create a conda environment for this workshop using a yml file. The python version and all needed packages, including astropy, are listed in the environment.yml file.
On Mac or Linux, open your terminal and verify your shell environment:
% echo $SHELL
If the output text does not contain bash, switch to the bash shell before
being able to run anything related to conda.
On Windows, open the Anaconda Prompt terminal app.
Now navigate to this directory in the terminal. For example, if you installed the astropy-workshop directory in your home directory, you could type the following.
On a Mac/Linux:
% cd astropy-workshop/00-Install_and_Setup/
On Windows:
% cd astropy-workshop\00-Install_and_Setup\
And finally, on any platform, to install and activate the astropy-workshop environment, type:
% conda env create -n astropy-workshop --file environment.yml
% conda activate astropy-workshop
Note, you will need conda version 4.6 and later. If you need to update your version use conda update conda.
The name of the new conda environment created above should be displayed next
to the terminal prompt: (astropy-workshop) %
Run the check_env.py script to check the Python environment and some of the
required dependencies:
(astropy-workshop) % python check_env.py
If the script reports that some of the versions do not match, check first
whether the package was installed using conda or pip, then update accordingly.
The example below a fake package called packagename; replace it with the
actual package that you need to update.
(astropy-workshop) % conda list packagename
If it was installed with conda, you will see (the channel column might or might not be populated):
# packages in environment at .../miniconda/envs/astropy-workshop:
#
# Name Version Build Channel
packagename X.Y.Z py37hf484d3e_1000
Otherwise, if it was installed with pip, you will see the channel stating the
name pypi:
# packages in environment at .../miniconda/envs/astropy-workshop:
#
# Name Version Build Channel
packagename X.Y.Z pypi_0 pypi
To update the reported package with conda:
(astropy-workshop) % conda update packagename
Otherwise, to update with pip:
(astropy-workshop) % pip install packagename --upgrade
The exception to this is if the astroquery package is reported as
out-of-date, always update to its pre-release version with pip:
(astropy-workshop) % pip install astroquery --pre --upgrade
In the conda environment created above, go into the directory
of one of the chapters with notebooks (files ending with .ipynb)
and start Jupyter notebook:
(astropy-workshop) % jupyter notebook
If successful, your browser would open a new page/tab pointing to
localhost and show you a listing of the directory.
Click on a notebook and wait for it to launch. On the top right corner,
if you see a blue "Kernel Ready" message appear and disappear,
then all is well. However, if you see a red "Kernel Error," click on it
and scroll down to see the error message. If it says FileNotFoundError,
shut down the notebook server on your terminal and run this command:
(astropy-workshop) % python -m ipykernel install --user
Now, try run jupyter notebook again as above, and the "Kernel Error"
should be gone. Just to be sure, run the first cell (usually an import)
and see if it is successful.
Furthermore, to ensure that the notebook is picking up astropy from
the correct environment, create a new cell in the notebook (use the +
button in the top menu) and run the following code:
import astropy
print(astropy.__version__)
If the reported astropy version is older than expected and you have
not run the python -m ipykernel install --user command, then run it
as instructed above.