📓

Getting Started with the QuantAQ data and analysis tools

Twitter Github QuantAQ Home

Jump into understanding your data and analysis with our tools!⚡ Pardon our dust, this is a work in progress!

Introduction

Your QuantAQ cloud subscription includes access to your final, cleaned data. In this guide, we’ll walk through how to download data from the QuantAQ Cloud and what the variables mean.

If you’re familiar with or are learning programmatic tools, our data tools can help you speed up and supercharge your data analysis! We’ll take a look at our data analysis tools, including:

  • Our command line tool, quantaq-cli, lets users quickly manipulate data files into the formats you need for successful analysis.
  • Our API allows users to access their data in a programmatic way for continual analysis in external programs or scripts

We link tutorials and additional resources throughout for your reference now and in the future!

Introduction to your QuantAQ data: downloading and variables

🔆
We recommend that you have access to at least one downloaded file of data to follow along!

Your final, cleaned data is reported on a one-minute resolution and is downloadable as a csv file within your QuantAQ Cloud account.

🔆
You can only download data from one sensor at a time from the Cloud

Downloading data from the QuantAQ Cloud

To download data, go to the team that has the sensor you want to get data from. Click on the ‘Devices’ tab within the team, and click on the sensor. Select ‘Download Data’ at the top, choose the date range you want to download, provide a quick description if needed, and click ‘Download Selected Data’. Navigate to the ‘Data’ tab under the ‘Console’ section and click ‘Download’ to get a csv downloaded to your computer.

Understanding your data files

Once you’ve downloaded a data file, open it up to see what variable are available! You can learn about the variables in your file here for MODULAIRs or here for MODULAIR-PMs. Units for all final particulate matter (PM) variables are ug/m3, for all gas phase variables except CO2 are ppb, and for CO2 are ppm.

There are two timestamp variables, ‘timestamp’ and ‘timestamp_local’. ‘timestamp’ reports UTC time and ‘timestamp_local’ reports the local time that the sensor owner defined. To update the sensor’s timezone, see this article!

Power up your data analysis: working with your QuantAQ data programmatically

We have a number of data analysis tools for both general users and researchers. While there is no need to use any of the QuantAQ data tools to successfully analyze your data, we have built these tool specifically to make your analyses faster and smoother.

This table briefly summarizes our tools. Below we dig more deeply into our most commonly used tools: quantaq-cli, the QuantAQ Cloud API, and py-quantaq.

Data tool
Purpose
Suggested users
Documentation
quantaq-cli
Manipulate downloaded csv data files
Users who wish to work with downloaded data
QuantAQ Cloud API
Programmatically access your data for continuous analysis
Users who wish to read in their data into a continuous application
py-quantaq
Python wrapper for the QuantAQ Cloud API
Users who wish to read in their data into a continuous application within Python scripts
py-smps
Analyze and plot size-resolved aerosol data from any aerosol sizing instrumentation (tip: apply to be a researcher to access size-resolved raw data)
Researchers who wish to work with size-resolved data

QuantAQ Command Line Interface: speed up your data munging

The quantaq-cli is a command line interface tool that can allow you to quickly concatenate and merge files, and flag, expunge, and resample files to different timebases. For example, you may have 5 files that you wish were combined into one file that reports hourly data. You could concatenate (’concat’) these 5 files into one file, and then create a file at hourly time resolution (’resample’), all in two lines of code on the command line!

Check out the GitHub page and our documentation for more on quantaq-cli or keep reading!

🔆
If you’ve never used a command line tool before, we have sprinkled in some ‘getting started’ shortcuts for you!

Requirements:

  1. Python version 3.8 or higher and pip

Don’t have Python? No problem! There are several easy ways to set up Python. We recommend you ask your IT department for their preferred way to install it on your computer. If you don’t have an IT department, the Anaconda Distribution works well for both MacOS and Windows.

If your Python installation doesn’t come with pip, check out the Installation section of the pip documentation.

🔆
Even though you must have Python installed to install and run quantaq-cli, you do not have to perform your subsequent data analysis in Python! quantaq-cli simply helps you prepare your csv data files for analysis in any software or coding language that you prefer.
  1. A terminal emulator

Commonly pre-installed terminal emulator software include Terminal (MacOS), Command Prompt (also called CMD; Windows), and PowerShell (Windows). If these are not available, reach out to your IT department for assistance on setting up a new terminal emulator or research best terminal emulators for your operating system.

Install quantaq-cli:

Simply install the quantaq-cli tool by typing pip install -U quantaq-cli

into your terminal emulator and hit enter.

Example use case: using quantaq-cli to resample your data to a 5 minute timebase

In this video, we walk through how to use quantaq-cli to resample (change the timebase) QuantAQ data that you have downloaded from the website from 1 minute to 5 minutes.

First we walk through how to find the folder that your data is in using your terminal program. When you first open up a terminal program, it shows your base directory. You can type ls and hit return (enter) to see all the folders and files that are available in that directory. Then you can move into a folder by typing cd and the file name and hit return. Keep cd ‘ing into folders until you reach where your data is being stored. Tip: you can hit tab after typing the first few letters of a folder name to autofill in the rest of the name!

Once you are in the folder where your QuantAQ data is in your terminal emulator, type:

quantaq-cli resample -v [your_file_name.csv] 5min -o [new_file_name.csv]

where [your_file_name.csv] is the name of the file you want to resample and [new_file_name.csv] is the name of the new file that you are creating. Hit return and the new file is made!

Opening up your newly created file ([new_file_name.csv] ), we see that the file has 5 minute data. Note that any columns that have text in them are dropped, such as the ‘sn’ (serial number) column.

Going to the resample section of the documentation, we find a list of how to use different time bases, such as hours, weeks, and months.

QuantAQ Cloud API: easily access your data for continuous analyses

The QuantAQ Cloud Application Programming Interface (API) allows you to manage your air quality sensors and data in a simple, programmatic way using conventional HTTP requests. Check out our documentation on how to use our API.

Use cases for the API include continuously pulling data for self-hosted websites or ongoing data analysis. You can retrieve data for your sensors and use advanced queries to limit, sort, and filter your data.

Obtain an API key for your API by visiting the ‘API Keys’ tab under the ‘Console section of your QuantAQ Cloud account and click ‘Generate New Key’.

image

py-quantaq: the QuantAQ API python wrapper

If you are a Python user, py-quantaq is an easy-to-use way to access the QuantAQ API within your Python environment. All of the commands that are available from the API are available in a Pythonic fashion in py-quantaq. Check out the GitHub page and documentation, including example use cases!

Additional resources

Check out our blog and community page! We like to take a deeper dive in our blog posts into understanding air quality sensors, data, and data analysis tools. In our community page, you can ask for the community for input on any of our tools or air quality concepts that you want more information on. You can also request tutorials from us on any of our tools.