This repository contains tools and instructions for accessing and interacting with the data cubes (often referred to as "grids") from the Arecibo Legacy Fast ALFA (Arecibo L-band Feed Array) survey, or ALFALFA. Below are the basic instructions for getting started, and more details about accessing the data, the metadata, and the survey can be found in the Wiki associated with this repository. We strongly recommend reviewing this material if you plan to use these data.
The ALFALFA grids are stored in the NRAO data archive. The tools in this repository are intended to be used with data cubes downloaded from this archive. These tools are all based in Python (mostly Jupyter notebooks) and in order for them to run as intended, we recommend building a dedicated Python environment using the environment.yml file in this repository (instructions below). The notebooks folder contains these notebooks which show worked examples of standard tasks that user are likely to want to perform. For example, identifying which ALFALFA grid is needed to a particular position on the sky, extracting a 1-dimensional spectrum from a data cube, or producing a moment zero map and overlaying it on an optical image. The scripts folder includes a Python file defining a function to read in data cubes. We recommend using this function if interacting with the cubes in Python as this updates the FITS headers to the latest standards and applies an approximate correction to the world coordinate system in the header.
Although it is strongly recommended to download this repository and build the Python environment if you wish to use or adapt the code hosted here, if you don't want to install or download anything then the simplest way to use this repository is to launch it in the cloud using mybinder by clicking this button:
Note that when you close (or lose) your connection to mybinder, all of the open work that you haven't manually downloaded and saved will be lost. This interface is generally intended for testing things out, not for seriously working on code or data.
If you use git then the easiest way to get this repo is to run the following command in a terminal in a suitable location:
git clone https://github.com/ALFALFAsurvey/ALFALFA_Legacy.gitIf you are new to git, installation instructions can be found here, and here are some examples of basic git commands.
If you just want to download the repo, but don't want to use git, then you can simply download it as a zip file at the following url:
https://github.com/ALFALFAsurvey/ALFALFA_Legacy/archive/refs/heads/main.zip
The Python environment is defined in the file environment.yml. This is a YAML file that lists all of the specific package versions such that the software environment used can be common and reproducible.
If you already know what you're doing then you can use whatever tool you want to build and launch this environment. However, we recommend using conda. If you already have a version of conda installed (see below) then navigate to where you downloaded this repo and in a terminal run the command:
conda env create -f environment.ymlThis will create a new conda environment called "AALegacy". Note that if running on a newer Mac, the environment may fail to build, in which case you should try instead using the command:
conda env create -f environment.yml --platform osx-64Once you have successfully created the environment, you can then activate it with:
conda activate AALegacyIf you don't already have a version of conda installed then you can follow the instructions at the following links to install either Miniconda or Anaconda. Both will work the same, but Miniconda might save a little space, if that is a concern.
Most of the notebooks require an ALFALFA grid as input to run. To obtain the grid used in most of our examples navigate in your terminal to the scripts directory as run the following command:
python download_example_data.pyThis script will automatically download a tar file (approximately 1.5 GB) containing a grid and extract it into a new directory where the notebooks expect to find the data.
After building and activating the AALegacy environment, navigate to your local version of this repository in your terminal and run the command:
jupyter notebookThis will launch a notebook server in your default browser (if the browser fails to open, then try clicking the link for the notebook server in the terminal output), after which you should be able to open the notebooks folder and launch any of the example notebooks.