Real Time Geospatial (RETIGO) Tutorials
RETIGO is a free, web-based tool that shows air quality data that you've collected while you are stationary or in motion (walking, biking, or on a vehicle). In addition to viewing your data, RETIGO allows you to view data from nearby air quality and meteorological stations.
This page contains both video and interactive tutorials on RETIGO basics: preparing and loading a data file, navigating the interface, and using the data repository. The videos were developed for a previous version of RETIGO, however the majority of the content is relevant for the current version. The written tutorial has been updated to reflect the most current version of RETIGO.
Video tutorials
These video tutorials will show you how to use the features of RETIGO. The videos include voice narration and closed captioning.
Online Tutorial
- Step 1: Prepare a Data File
- Step 2: Load Data or Select from Data Repository
- Step 3: View the Data
- Step 4: Investigate the Data
- Step 5: Merging in other data
Step 1: Prepare a Data File
You can load a data file directly from RETIGO's data repository, or prepare a file using your own data. If you want to use the data repository, proceed to step 2.
RETIGO reads plain text data files, which can be either space or comma delimited. Here is an example of what a RETIGO data file should look like. Two complete example files can be downloaded below.
## Sampling day: July 18 2012 ## Operator: Jane Doe ## Location: Raleigh NC ## Notes: Weather is clear, light traffic Timestamp(UTC) EAST_LONGITUDE(deg) NORTH_LATITUDE(deg) ID(-) ozone(ppb) pm2.5(ug/m^3) 2012-07-18T15:44:00-00:00 -78.9979 35.9508 route1 49.0491 32.6768 2012-07-18T15:44:19-00:00 -78.9947 35.9470 route1 43.2706 26.7231 2012-07-18T15:44:57-00:00 -78.9896 35.9361 route1 42.3130 34.1504 2012-07-18T15:45:58-00:00 -78.9846 35.9172 route1 47.7046 33.2918 2012-07-18T15:46:17-00:00 -78.9733 35.9048 route1 47.7046 -9999 [etc...]
The first four lines in the example are comment lines (denoted by two hash symbols: ##). Comment lines can occur anywhere in the file, and can be used to make whatever annotations you wish. There is no limit to the number of comment lines allowed since they are completely ignored by the RETIGO program.
The next line is the header line, which identifies each column of data. The first four columns must be present in every file in the order listed in the example. They describe the time and position of each measurement, along with an identifier which can be used to sort the data when it is being analyzed. There should be at least one additional column that contains measurement data, and there can be up to ten such columns. The variable names should not include spaces. It is also suggested that units be included in the variable name. The exact format of each column is as follows:
Column 1: | Timestamp that conforms to the UTC/ISO 8601 international standard. The timestamp should have the form YYYY-MM-DDThh:mm:ssTZD*, where YYYY = four-digit year MM = two-digit month (01=January, etc.) DD = two-digit day of month (01 through 31) hh = two digits of hour (00 through 23) (am/pm NOT allowed) mm = two digits of minute (00 through 59) ss = two digits of second (00 through 59) TZD = time zone designator (+hh:mm or -hh:mm) For example, 2012-07-18T15:44:00-00:00 corresponds to July 18, 2012, 3:44:00pm Greenwich Mean Time (GMT). The exact same instant of time could be represented in different US timezones as: 2012-07-18T11:44:00-04:00 for Eastern Daylight Time (EDT) 2012-07-18T10:44:00-05:00 for Central Daylight Time (CDT) 2012-07-18T09:44:00-06:00 for Mountain Daylight Time (MDT) 2012-07-18T08:44:00-07:00 for Pacific Daylight Time (PDT) 2012-07-18T10:44:00-05:00 for Eastern Standard Time (EST) 2012-07-18T09:44:00-06:00 for Central Standard Time (CST) 2012-07-18T08:44:00-07:00 for Mountain Standard Time (MST) 2012-07-18T07:44:00-08:00 for Pacific Standard Time (PST) * Extra precision: For many users, the specification of time to the nearest second will be adequate. However, it is possible to add two decimal places of precision (hundredths of a second) by using a timestamp of the form YYYY-MM-DDThh:mm:ss.ssTZD |
---|---|
Column 2: | East longitude in decimal degrees. |
Column 3: | North latitude in decimal degrees. |
Column 4: | Identifier string. |
Column 5+: | Measurement data, with data descriptor and units in the header. |
At least one column of measurement data is required, but there can be additional data columns if desired. In the example above, two data columns are included (ozone and pm2.5). Use -9999 to indicate missing variable data.
To get started, you may want to download this sample file and proceed to the Step 2. You can also view a separate tutorial on how to create a RETIGO file from an Excel spreadsheet.
Sample concentration data: MobileData_RETIGO.csv
This data is related to the recent publication On-road black carbon instrument intercomparison and aerosol characteristics by driving environment, A.L. Holder et al., Atmos. Environ., 88 (2014), pp. 183-191. https://doi.org/10.1016/j.atmosenv.2014.01.021
Wind Data
Wind data can be included as separate vector components (magnitude and direction). In general, the wind data can have different temporal and spatial sampling than the pollution data. However, to create pollution rose plots, the wind data needs to be collected at the same time and location as the measurement data. The format of wind data is similar to that of the regular RETIGO data file outlined above. However, since wind is a vector quantity, both the magnitude and direction must be specified. For example:
Timestamp(UTC) EAST_LONGITUDE(deg) NORTH_LATITUDE(deg) ID(-) wind_magnitude(m/s) wind_direction(deg) 2008-11-05T07:14:00-05:00 -78.6140 35.8229 Sonic_anemometer 2.1729 0.0 2008-11-05T07:14:05-05:00 -78.6140 35.8229 Sonic_anemometer 2.1998 45.0 2008-11-05T07:14:10-05:00 -78.6140 35.8229 Sonic_anemometer 2.6970 90.0 [etc...]
The units of the wind magnitude can be defined by the user (e.g. m/s, mi/hr), but the direction must be in degrees using the standard meteorological convention: the heading indicates the direction from which the wind originates (clockwise from North). A heading of 0 degrees indicates wind coming from the North, 90 degrees indicates wind from the East, etc.
RETIGO displays the wind in a vector sense, where the tip of the arrow points in the direction the wind is going. So a wind direction of 90 degrees specified in the file (from the East) would be pointing toward the West in the visualization.
Step 2: Load Data or Select from Data Repository
Once you have a data file to view, go to the RETIGO application page and click "Choose File" to browse to the file. Or you can select a file from RETIGO's data repository. Once you have selected your options, select the View button.
Step 3: View the Data
After you click the View button, your data is displayed on a map as shown here. Colors indicate the value of the selected variable, ranging from dark blue (low) to red (high). RETIGO automatically determines the lowest and highest values of the selected variable, and adjusts the color scale accordingly. You can also customize the colorbar by setting the minimum and maximum values for each variable.
Data Control Toggle
When the Data Control Toggle is set to "MyData", you are presented with controls that allow you to choose how to display your data. When the Data Control Toggle is set to "Merge", the menu options change to allow you to bring in air quality data from the AirNow network, or temperature/wind data from the World Meteorological Organization Global Surface Meteorology Monitoring Network. If you choose to show nearby monitoring data, RETIGO will automatically retrieve the data if it is available and display it alongside your measurements. Depending upon the time and spatial extent of your dataset, it may take a minute or two to retrieve the air quality data. You can also choose to show a weather condition summary, which will list meteorological conditions from the nearest METAR monitor.
Time control
The time control is a horizontal slider that is used to pinpoint a particular datapoint in time. The selected time is shown above the slider, referenced to the desired timezone. The corresponding data value is shown below the slider. Dragging the slider allows you to track the dataset over time.
Toolbar
The toolbar allows you to interact with the map in various ways:
- The "home" button automatically centers the map around your data, and sets the optimal zoom level to show the entire dataset.
- The "move map" button lets you recenter the map. With the "move map" icon selected, simply left-click anywhere in the map and drag the mouse while keeping the left mouse button down. Once the map is in the desired position, let go of the mouse button.
- The "drop analysis point" function lets you designate a point on the map, denoted by a pushpin. You can then plot your data as a function of distance from the point (see below). This might be useful if you know the location of a pollutant source. To designate a point, select the icon and then left-click anywhere on the map. A pushpin will appear to mark the selected point. The pushpin can be dragged to a new location by simply left-clicking on it, moving it to a new location, and letting go of the mouse button. To delete the pushpin, right click on it.
- The "create analysis polyline" function is similar to the analysis point, except you create a polyline instead of a point. Left-click to create the starting point, and then again to create the ending point. The polyline can be modified into any shape by clicking on the center of the line and displacing it, creating two new line segments each with a new center. By repeatedly adjusting the location of the centers, the polyline can take on any shape. For example, the polyline could be made to approximate the contour of a road. To delete the polyline, right click on it.
- The "crop region" function lets you exclude all data outside of the defined box. With the crop region icon selected, simply left click and drag on the map to define the region of interest. Any analysis plots that are active (see below) will automatically update to reflect the selection. To delete the crop region, right click on it.
Select Variable
All of the measured variable names (column 5 and beyond in the data file) are shown in the "select variable" area. Simply left-click on the variable that you would like to see. RETIGO will automatically show the data on the map and update the colorbar accordingly. You can also adjust the range of the variable by entering values into the appropriate text boxes.
Step 4: Investigate the Data
RETIGO provides a few simple ways to investigate your data:
- Plot data as a function of time.
- Plot data vs. distance from a point.
- Plot data vs. minimum distance from a polyline.
- Plot data in a polar wind-pollution format.
You can turn the analysis plots on and off using the checkboxes underneath the toolbar. It is possible to have any combination of the map, timeseries plot, analysis plot, and wind-pollution plot active at once.
Timeseries Plot
The timeseries plot shows the selected variable as a function of time. As you move the time control slider, the corresponding datapoint is highlighted in the timeseries plot with a black circle. You can also add a second variable to the plot, which will be shown with a black triangle.
Analysis Plot
The analysis plot shows the selected variable as a function of distance from the designated analysis point or polyline. See the Toolbar controls above for how to designate these. As you move the time control slider, the corresponding datapoint is highlighted in the analysis plot with a black circle (marker) or triangle (polyline). You can also cloose to aggregate the data into bins of a designated size; the mean and standard deviation are automatically computed and displayed.
Wind-Pollution Plot
If wind vector data is present in your data, you can view a wind-pollution plot for the selected variable. This is a polar plot, where the angle is equal to the wind heading, the distance from the center is equal to the wind magnitude, and the color corresponds to the value of the selected variable. For example, the marker located within the square on the image below represents a measurement that occurred when the wind was from the southeast, with an approximate wind speed of 4 m/s, and the color can be matched to the colorbar representing the pollution concentration range, in this case about 50 ppb. The wind-pollution plot is best suited for stationary data.
Show Connecting Line
This option connects your data with a red line to better visualize the path that was taken during the data collection. It is useful if you are viewing data in "single point" mode.
Crop Region
Use the crop region function to exclude data outside of a region of interest. After clicking on the crop region icon, simply left click and drag on the map to define the region. When the mouse button is released the map and analysis plots will automatically be updated. The crop box can be deleted by right-clicking anywhere inside it.
Using IDs
The RETIGO file specification allows you to tag each data point with an identifier (ID), which is composed of alphanumeric characters. You can use the IDs to group your data in any way you like, and isolate them in the visualization.
Time Mode / Large File Support
For efficiency, RETIGO only shows 1000 points at a time. If your dataset contains more points, say 100,000, you can look at the dataset in one of two ways. Using average mode (default), the data is time averaged into bins, such that there will be approximately 1000 bins. In this example, every 100 points would be time-averaged, yielding 1000 points to be shown on the map. If you want to see your un-averaged data, select block mode. Here, the data can be accessed 1000 points at a time in blocks. The starting time of each block is listed in the menu. You can click through the list of blocks one by one to view the entire dataset. There is no limit to the number of data points that your dataset may have; larger files will simply have more blocks. If you are using the timeseries plot, you can extend the range by clicking "Extend blocks" and selecting the number of additional blocks to view (up to five).
Other Features
The map display is a fully functioning Google Map™ display.
The map selector lets you switch between a regular roadmap, a terrain map, or a satellite view. The zoom control allows you to zoom in or out using the slider or the plus and minus buttons at the top and bottom of the slider. Sometimes the terrain view limits the zoom level, so you may need to choose a different map if you want to zoom all the way in.
To use Google Street View™, left-click on the Street View icon and drag it to your location of interest on the map. Everywhere that Street View is available will be highlighted in blue. When you let go of the mouse, the RETIGO view will automatically change to Street View. The view can be rotated and navigated using the mouse. To return to the main map, click the "x" in the upper right hand corner.
Note: The satellite map and Street View images are collected at different times (sometimes months or years apart), but both are updated periodically by Google, Inc. Both may not reflect the exact conditions present at the time of your data collection, so care must be taken when interpreting the imagery.
Step 5: Merging in Other Data
Click on the Merge tab to add data to either the map or timeseries plot. You can add various AirNow monitoring sites to the map, as well as weather monitoring (METAR) sites. You may have to zoom out the map in order to see the sites on the map. RETIGO will automatically pull in data from the same location and time period as your data.
The same AirNow or METAR data can be added to the timeseries plot. For flexibility, the added data uses a separate y-axis and data range. When comparing to your data, be sure to adjust the data ranges accordingly.