Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

ACT Basics

ARM Logo

ACT Basics


Goal

The goal of this notebook is to showcase ARM supported open-source software that can be included within your workflows.
You will learn how to download, quality control and display ARM data from the DUSTIEAIM campaign

Overview

The Atmospheric data Community Toolkit (ACT) is an open source Python toolkit for working with atmospheric time-series datasets of varying dimensions (theisen_act_2026). The toolkit is meant to have functions for every part of the scientific process:

  • discovery,

  • IO,

  • quality control,

  • corrections,

  • retrievals,

  • visualization,

  • and analysis.

It is meant to be a community platform for sharing code with the goal of reducing duplication of effort and better connecting the science community with programs such as the Atmospheric Radiation Measurement (ARM) User Facility.

This tutorial will provide an introduction to ACT using the Aerosol Particle Sizer to investigate haboobs during the Desert-Urban SysTem IntegratEd AtmospherIc Monsoon (DUSTIEAIM) ARM Mobily Facility deployment.

  1. Intro to ACT

  2. Instrument Overview

  3. Downloading and Reading in Data

  4. Quality Controlling Data

  5. Visualizing Data

  6. Monthly Temperature Trend Analysis

Prerequisites

This notebook will rely heavily on Python and the Atmospheric data Community Toolkit (ACT). Don’t worry if you don’t have experience with either, this notebook will walk you though what you need to know.

Warning

You will also need an account and token to download data using the ARM Live webservice.

Navigate to the webservice information page and log in to get your token.
Your account username will be your ARM username.
ConceptsImportanceNotes
ACTHelpful
Xarray BasicsHelpfulMulti-dimensional arrays
Matplotlib BasicsHelpfulBasic plotting
NumPy BasicsHelpfulBasic arrays
  • Time to learn: 15 Minutes

  • System requirements:

    • Python 3.11 or latest

    • ACT v2.0.0 or latest

    • numpy

    • xarray

    • matplotlib


Intro to ACT

The Atmospheric data Community Toolkit (ACT) is an open-source Python toolkit for exploring and analyzing atmospheric time-series datasets. Examples can be found in the ACT Example Gallery. The toolkit has modules for many different parts of the scientific process, including:

Enhanced Skew-T plot from ARM’s Southern Great Plains Site (SGP)

Data Discovery (act.discovery)

The discovery module houses functions to download or access data from different groups. Currently it includes function to get data for ARM, NOAA, EPA, NEON, and more!

Input/Output (act.io)

io contains functions for reading and writing data from various sources and formats.

Visualization (act.plotting)

plotting contains various routines, built on matplotlib, to help visualize and explore data. These include

  1. Time-series plots

  2. Distribution plots like histograms and heatmaps

  3. Geographic plots for moving systems like radiosondes or aircraft

  4. Skew-T plots for radiosonde data, built off MetPy

  5. Wind rose plots for wind and data roses

  6. Cross-section plots for working with 3-dimensional data

Corrections (act.corrections)

corrections apply different corrections to data based on need. A majority of the existing corrections are for lidar data.

Quality Control (act.qc)

The qc module has a lot of functions for working with quality control information, apply new tests, or filtering data based on existing tests. We will explore some of that functionality in this notebook.

Retrievals (act.retrievals)

There are many cases in which some additional calculations are necessary to get more value from the instrument data. The retrievals module houses some functions for performing these advanced calculations.

Utilities (act.utils)

The utils module has a lot of general utilities to help with the data. Some of these include adding in a solar variable to indicate day/night (useful in filtering data), unit conversions, decoding WMO weather codes, performing weighted averaging, etc...

NEON-ARM

ARM and NEON data from Utquivaik, AK

SONDE

DUSTIEAIM Overview

The focus of the DUSTIEAIM project is to characterize interactions between the land surface and the atmosphere and over a desert megalopolis (Phoenix) set in complex topography that results in steep gradients. DUSTIEAIM will interrogate the interaction between storms and aerosol during the summer North American Monsoon (NAM) in the context of spatial contrasts at the urban interface with agricultural and drylands in the Sonoran Desert. The DUSTIEAIM science focus is to quantify the bimodal water cycle and energy budgets at the urban/rural/agricultural interface of the southwestern U.S. as regional air masses and meteorological patterns change throughout the year in response to the seasonal cycle, including winter Pacific storms and the NAM.

Instrument Overview

Aerodynamic Particle Sizer (APS)

The aerodynamic particle sizer (APS) is a particle size spectrometer that measures both the particle aerodynamic diameter based on particle time of flight and optical diameter based on scattered light intensity. The APS provides the number size distribution for particles with aerodynamic diameters from 0.5 to 20 micrometers and with optical diameters from 0.3 to 20 micrometers.

Imports

Let’s get started with some data! But first, we need to import some libraries.

Downloading and Reading ARM’s NetCDF Data

ARM’s standard file format is NetCDF (network Common Data Form) which makes it very easy to work with in Python! ARM data are available through a data portal called Data Discovery or through a webservice. If you didn’t get your username and token earlier, please go back and see the Prerequisites!

Let’s download some of the APS data first!

[DOWNLOADING] dstaosapsM1.b1.20260804.000000.nc

If you use these data to prepare a publication, please cite:

Singh, A., Oliveira, D., Koontz, A., Sedlacek, A., & Kuang, C. Aerodynamic
Particle Sizer (AOSAPS), 2026-08-04 to 2026-08-04, ARM Mobile Facility (DST),
Phoenix, AZ: AMF1 (Main Site for DUSTIEAIM) (M1). Atmospheric Radiation
Measurement (ARM) User Facility. https://doi.org/10.5439/1407135

[DOWNLOADING] dstmetM1.b1.20260804.000000.cdf

If you use these data to prepare a publication, please cite:

Kyrouac, J., Shi, Y., & Tuftedal, M. Surface Meteorological Instrumentation
(MET), 2026-08-04 to 2026-08-04, ARM Mobile Facility (DST), Phoenix, AZ: AMF1
(Main Site for DUSTIEAIM) (M1). Atmospheric Radiation Measurement (ARM) User
Facility. https://doi.org/10.5439/1786358

Note

Did you notice the dataset DOIs?
Loading...
Loading...
<Figure size 640x480 with 1 Axes>
<Figure size 640x480 with 1 Axes>

Quality Controlling Data

ARM has multiple methods that it uses to communicate data quality information out to the users. One of these methods is through “embedded QC” variables. These are variables within the file that have information on automated tests that have been applied. Many times, they include Min, Max, and Delta tests but as is the case with the Aerosol Observing System (AOS) instruments, there can be more complicated tests that are applied.

The results from all these different tests are stored in a single variable using bit-packed QC. We won’t get into the full details here, but it’s a way to communicate the results of multiple tests in a single integer value by utilizing binary and bits! You can learn more about bit-packed QC here but ACT also has many of the tools for working with ARM QC.

Other Sources of Quality Control

ARM also communicates problems with the data quality through Data Quality Reports (DQR). These reports are normally submitted by the instrument mentor when there’s been a problem with the instrument. The categories include:

  • Data Quality Report Categories

    • Missing: Data are not available or set to -9999

    • Suspect: The data are not fully incorrect but there are problems that increases the uncertainty of the values. Data should be used with caution.

    • Bad: The data are incorrect and should not be used.

    • Note: Data notes are a way to communicate information that would be useful to the end user but does not rise to the level of suspect or bad data

Additionally, data quality information can be found in the Instrument Handbooks, which are included on most instrument pages. Here is an example of the MET handbook.

Loading...
<Figure size 1500x1000 with 2 Axes>
<Figure size 1500x1000 with 2 Axes>

Visualizing Data

We’ve already worked with visualizing the data in basic ways but what other options are there in ACT? This section will show you how to create a variety of different plots. More plotting examples can be found in ACT’s Documentation.

Multi-Panel Plot

This example shows how to plot multiple datastreams together (APS and the MET) on a multi-panel plot. The top panel is the APS number size distribution (dN_dlogDp), a 2D field (time x diameter). Since particle concentrations span several orders of magnitude and the aerodynamic diameter bins are log-spaced, we use a log-scaled colorbar and a log-scaled y-axis to keep both the fine- and coarse-mode particles visible. The bottom panel shows MET wind speed for comparison - watch for coarse-mode particle spikes that line up with wind gusts, a signature of blowing dust or haboob activity.

<Figure size 1500x1000 with 3 Axes>

Cumulative Precipitation

Another common question is how precipitation accumulates over the course of a day. ACT’s act.utils.data_utils.accumulate_precip turns an instantaneous rain-gauge variable into a running total, which we can overlay on the original time series using a second y-axis. The DUSTIEAIM day shown here (2026-08-04) is a dust/haboob case, not a monsoon rain day, so the accumulated total stays flat at zero - a useful contrast with what this same function would show on an active North American Monsoon storm day.

<Figure size 1500x500 with 2 Axes>

Distribution Display

For the example, we will go over some functions within ACT’s distribution display. Functions such as, the stacked bar plot, scatter and groupby.

<Figure size 640x480 with 1 Axes>

More Information on Combining Data with Xarray

Find more information on combining data with xarray [here]
<Figure size 640x480 with 2 Axes>

Distribution Heatmap

The scatter plot above gets crowded once a lot of points overlap - a 2D histogram (heatmap) makes it easier to see where the data actually cluster. DistributionDisplay.plot_heatmap bins both variables and colors by point count, using the same box_temperature vs temp_mean comparison as above.

<Figure size 640x480 with 2 Axes>

Data Rose Plots

If your data may be wind speed or direction dependent, these plots can help inform where the influences may be coming from (or confirm there are no blocking QC issues). For this example, let’s see if tipping bucket rain guage data are dependent on wind direction

/Users/jrobrien/dev/ARM-Notebooks/.micromamba/envs/arm-tutorial-dev/lib/python3.14/site-packages/act/plotting/windrosedisplay.py:358: RuntimeWarning: Mean of empty slice
  arr.append(np.nanmean(data[idx]))
<Figure size 640x480 with 1 Axes>
/Users/jrobrien/dev/ARM-Notebooks/.micromamba/envs/arm-tutorial-dev/lib/python3.14/site-packages/act/plotting/windrosedisplay.py:429: RuntimeWarning: Mean of empty slice
  mean_data[i, j] = np.nanmean(data[idx])
<Figure size 640x480 with 2 Axes>