ALminer: ALMA Archive Mining & Visualization Toolkit

alminer is a Python-based code to effectively query, analyse, and visualize the ALMA science archive. It also allows users to directly download ALMA data products and/or raw data for further image processing.

Installation

The easiest way to install alminer is with pip:

pip install alminer

To obtain the most recent version of the code from GitHub:

pip install https://github.com/emerge-erc/ALminer/archive/refs/heads/main.zip

Or clone and install from source:

# If you have a Github account:
git clone git@github.com:emerge-erc/ALminer.git
# If you do not:
git clone https://github.com/emerge-erc/ALminer.git

# After cloning:
cd ALminer
pip install .

Note that depending on your setup, you may need to use pip3.

Dependencies

The dependencies are numpy, matplotlib, pandas, pyvo, astropy version 3.1.2 or higher, and astroquery version 0.4.2.dev6649 or higher. We only use the astroquery package for downloading data from the ALMA archive. The strict requirement to have its newest version is due to recent changes made to the ALMA archive. alminer works in Python 3.

Getting started

We have created an extensive tutorial Jupyter Notebook where all alminer features have been highlighted. This is an excellent starting point to get familiar with all the possibilities; a glossary of all functions is provided at the bottom of this notebook. We highly recommend working in a Jupyter notebook environment in order to make use of alminer’s visualization tools. We aim to keep adding new notebooks relevant for various sub-fields in the future.

Note that the Jupyter notebooks may be outdated. The most up-to-date information can be found on this documentation page.

Note

To work with the tutorial notebook interactively

Tutorials

• 1. Query tools
  • 1.1 Query by target name
  • 1.2 Query by position
  • 1.3 Query by ALMA keywords
• 2. Filter & explore results
  • 2.1 Explore results
  • 2.2 Summarize results
  • 2.3 Filter results
  • 2.4 Line coverage
  • 2.5 Coverage of CO, 13CO, and C18O lines
• 3. Plot results
  • 3.1 Plot an overview of the observations
  • 3.2 Plot an overview of a given line in the observations
  • 3.3 Plot observed frequencies in each band
  • 3.4 Plot observed frequencies in each band
  • 3.5 Plot sky distribution
• 4. Create reports
  • 4.1 Export results as a table
  • 4.2 Save overview plots
• 5. Download data
  • Example 5.1: download all data products (raw + products)
  • Example 5.2: download only continuum FITS images for the science target
• 6. Advanced query features
  • 6.1 Create and run your own TAP query
  • 6.2 Convert your own query results into ALminer format

What’s new

• You can now specify which archive mirror to download data from: [ESO](https://almascience.eso.org/aq) is the default, and other options are [NRAO](https://almascience.nrao.edu/aq) and [NAOJ](https://almascience.nao.ac.jp/aq). This option can be given through the ‘archive_mirror’ parameter in the download_data function.

• You can now specify which archive service to query: [ESO](https://almascience.eso.org/tap) is the default, and other options are [NRAO](https://almascience.nrao.edu/tap) and [NAOJ](https://almascience.nrao.edu/tap). This option can be given through the ‘tap_service’ parameter to all functions that do the query (e.g. keysearch, target, catalog). For example:

  • alminer.target(["TW Hya", "HL Tau"], tap_service='NRAO')

  • Note that currently the ESO service is not returning all results, hence it is advisable to test your queries with multiple services until further notice.

• It is now possible to query entire phrases with the keysearch function. For example:

  • alminer.keysearch({'proposal_abstract': ['"high-mass star formation" outflow disk']}) will query the proposal abstracts for the phrase high-mass star formation AND the words outflow AND disk.

  • alminer.keysearch({'proposal_abstract': ['"high-mass star formation" outflow disk', '"massive star formation" outflow disk']}) will query the the proposal abstracts for the phrase high-mass star formation AND the words outflow AND disk OR the phrase massive star formation AND the words outflow AND disk.

Acknowledgements

alminer has been developed through a collaboration between Allegro, the ALMA Regional Centre in The Netherlands, and the University of Vienna as part of the EMERGE-StG project. This project has received funding from the European Research Council (ERC) under the European Union’s Horizon 2020 research and innovation programme (Grant agreement No. 851435).

If you use alminer as part of your research, please consider citing this ASCL article (ADS reference will be added to the GitHub page when available).

alminer makes use of different routines in Astropy and Astroquery. Please also consider citing the following papers: - Astropy: Astropy Collaboration et al. 2013 - Astroquery: Ginsburg et al. 2019

We also acknowledge the work of Leiden University M.Sc. students, Robin Mentel and David van Dop, who contributed to early versions of this work.

Contact us

If you encounter issues, please open an issue.

If you have suggestions for improvement or would like to collaborate with us on this project, please e-mail Aida Ahmadi and Alvaro Hacar.