SKOPE User’s Guide

R. Kyle Bocinsky, Andrew Gilreath-Brown, Keith Kintigh, Timothy A. Kohler, Allen Lee, Bertram Ludaescher, Timothy McPhillips
 2021-09-03

Note: The documentation below is for the soon to be released production SKOPE app. Documentation for the Prototype App Users Guide is here.

Introduction. SKOPE is a Web application that provides easy access to paleoenvironmental data.  Currently, data are available for the contiguous 48 US states. Notably, high spatial and temporal resolution precipitation and temperature data from PaleoCAR (Bocinsky 2015) are provided for the last 2000 years for the Four Corners region of the southwestern United States (Arizona, Colorado, New Mexico, and Utah) and portions of adjoining states. For example, using SKOPE, one can obtain estimates of the water year (October-September) precipitation and growing season Fahrenheit growing degree days (GDD) for any period between 1 C.E. and 2000 C.E. for any 800m x 800m grid cell in the region.  For entire contiguous 48 states, SKOPE offers the Palmer Modified Drought Index (PDMI), the successor to the Palmer Drought Severity Index (PDSI) that has been widely used in archaeology.  Static elevation data at 90m resolution are also provided.

SKOPE Data are Modeled.  It is important to recognize that the SKOPE datasets provide modeled, not measured, values for gridded data for a series of minimal time steps.  Information about the models is provided in the dataset metadata (click on the blue circled “i”) to the right of the dataset title and in publications referenced in the metadata.  The dataset metadata also includes a discussion of the sources of uncertainty in the values provided.  In general, there are a number of interacting sources of uncertainty and it is not possible to provide a single quantitative measure of uncertainty (which in some cases can vary from year to year and spatial cell to spatial cell). In interpreting the both raw and summarized data provided by SKOPE, it is essential that uncertainty in the provided values be taken into account.

If you have a dataset you would like to contribute, please contact us using the CONTACT link at the bottom of the web site footer.  Also please email us if you discover any bugs or have any suggestions.  The GITHUB link takes you to the project GitHub site. [what would someone do there?]

The spatial grid units in the SKOPE datasets are referred to as “cells”, each of which refers to a defined, rectangular (generally approximately square) area. For example, in the PaleoCAR dataset, pixels are 10 arc-seconds by 10 arc-seconds or about 800m x 800m. The pixel size defines the maximum resolution of the dataset.

Using the App

Start the app. Click on the Run the SKOPE Application link on the SKOPE Home Page  or navigate directly to https://openskope.org/app.

Navigate within the app.  Within the app, navigation is accomplished by clicking on the available buttons in the navigation bar across the top of the page: Select Dataset, Select Area, Visualize Data, and Analyze Data.  Some options may be hidden because you must first choose a dataset before you can select an area, and you must select an area before you can visualize or analyze data. You can, at any point, return to choose a new study area or to switch datasets. 

The LOAD ANALYSIS button at the right of the navigation bar allows you resume a previous  analysis where you left off, assuming that you downloaded the analysis file from the Analyze Data Page before you exited SKOPE.  Load Analysis restores the dataset, selected area, selected variable, and time range [anything else?].

If SKOPE is running in a particularly narrow window, rather than arrayed horizontally, the navigation options will appear in a dropdown menu accessed from the menu (hamburger) icon to the left of the SKOPE title in the navigation bar.   

Select Dataset Page

SKOPE opens to the Select Dataset page.   Select a dataset by clicking on the dataset title in the right pane of the app window. You can scroll though the available datasets on the right side of the window.  The displayed map for each dataset shows its spatial coverage and the description on the right provides some detail including its temporal scope, variables included, and spatial and temporal resolution.

View Metadata. Clicking on the “i” icon next to the dataset title opens a window that displays the additional details of the dataset metadata. (Also available on other pages).

Filter Datasets. You can filter the view of available datasets by selecting a variable, entering a keyword, and/or a time range of interest in the filter options below the navigation bar. 

Select Area Page

Once you have selected a dataset, you are automatically moved to the Select Area Page.  This page is used to define the area over which the paleoclimatic data is displayed and statistics are calculated and graphed.  For high spatial resolution datasets (such as PaleoCAR), the application will be more responsive for smaller study areas.  And, for those datasets, some areas may be too large for SKOPE to process interactively.  For PaleoCAR, Grid cells are 30 arc seconds  (~800m x 880m), 1/2 degree (~50km) for the Living Blended Drought Atlas (PMDI), and 3 arc seconds (~90m) for the SRTM 90m Digital Elevation Model.

Manipulating the Map. You can drag the map left and right and up and down by holding down the left mouse button and moving the mouse. You can zoom using the + and – controls on the upper left corner of the map or by using a mouse scroll wheel. 

Outline your specific area of interest. Zoom (+) the map as much as possible while still displaying your complete area of interest.  Changing the base maps using the globe icon in the upper right of the screen, may also aid in outlining your area of interest. By clicking on a shape icon in the upper left of the screen, you can select a point, draw a circle, or outline a rectangle, or arbitrary polygon on the screen.  Once an area has been selected it can be edited (one vertex at a time) or discarded using the edit or trash can icons below the shape icons 

Save or Restore your Area Selection. At any time, you can save your area selection (useful especially for painstakingly drawn polygons. This saves the selected area to your computer so that it can be reused in this or a later session.  Use the upload or download icons above the map on the far right.

Visualize Data Page 

The Visualize Data page has two main panels: an animated map on the left and a graph on the right.  Using color shading, the animated map shows the value of the selected variable, for each grid cell (which is why the colors appear n squares or rectangles) , for the year displayed below the graph and shown with the vertical orange line on the graph.  The graph shows the selected variable’s values across the selected time range.  Note that the selected area can also be modified using the controls on the map.

Select a Variable.  Just below the blue navigation bar, SKOPE displays the dataset title and, in a dropdown menu, the variable being graphed and analyzed.  If the dataset offers more than one variable, you should first select the variable of interest using the dropdown menu.

Identify the Time Period of Interest. By default, the map animation is set to start with the first year available for the dataset and the graph displays the full time-range available in the dataset.  You will usually want to look at a more restricted time range.   Immediately above the left side of the graph, you can change the beginning (Min Year) and ending year (Max Year) of interest. Be sure to click on the Apply button or press Enter to register your change.  SKOPE displays the number of time steps that are modeled between these two values (inclusive). The time step is the minimal temporal interval that is modeled.  For example, in PaleoCAR, the time step is one year.

  Run the Map Animation. Using the Animation control bar (located above and to the right of the graph), the colored overlay of the value of the selected variable shows the spatial distribution of values for the entire mapped area, time step by time step. The legend is shown on the lower left of the map.  As the map animation runs (once you press the play button) , the year is displayed below the graph and a vertical orange line on the graph shows the current year.  Clicking a location on the graph changes the current year. You may run, pause, step forward or back a year, or go to the beginning or end of the interval using the animation control.   If you wish, you can interactively drag or zoom the map display. 

It may be preferable to use a non-colored base map (change the base map using the globe icon in the upper right of the map) for careful analysis of these maps; otherwise the base map colors may conflate the variable overlay coloring. 

Adjust the Opacity of the Variable Value Overlay.  The opacity of the colored overlay of variable values is adjusted with the Opacity control above the middle of the map.  By default, some or all features of the base map are visible through the variable value display.  With an opacity of 100, the base map is thoroughly obscured; at 0 only the base map shows.The default is a compromise and you may achieve a better visualization with a different opacity (and a non-colored base map). 

Examine Graphed Data for the Area of Interest. To the right of the map, a graph displays the value of the selected variable averaged over the selected area, for the stated temporal interval.  The graphed value is the mean value of the selected variable calculated over all grid cells enclosed within or intersected by the area boundary for the year. For points, the graphed value is the value for the grid cell in which the point resides.

If you move the cursor into the graph, you will see the year and climate value pop up for particular year corresponding to your cursor position.

Analyze Data Page

On the Analyze Data page, you can tailor the data display to most effectively address your particular research questions.

Select a Variable.  Just below the blue navigation bar SKOPE displays the dataset title and, in a dropdown menu, the variable being graphed and analyzed.  If the dataset offers more than one variable, you will first want to select the variable of interest using the dropdown menu. (If you selected a variable or time period in a previous step, it should be carried over here.)

Identify the Time Period of Interest. Unless you modified the temporal range on the Visualize Data page, the graph displays the full time-range available in the dataset.  You will usually want to look at a more restricted time range.  Immediately above the left side of the graph, you can change the beginning (Min Year) and ending year (Max Year) of interest. Be sure to click on the Apply button press Enter to register your change.  SKOPE displays the number of time steps that are modeled between these two values (inclusive). The time step is the minimal temporal interval that is modeled. 

Spatial Grid/Cells. SKOPE’s raw data are modeled values for a specific time step and spatial grid cell.  Above the graph on the left, SKOPE displays the area in km2 of the selected study area as outlined on the maps. Next to that, it reports the number of cells and the area covered by the cells that are included within or intersected by the selected area outline.  While you can precisely specify a study area on the SKOPE map or via an uploaded study area outline, SKOPE computations are based on computations over all grid cells that are contained within or are intersected by the area or point you have selected.  This means that the area considered in the computations is generally larger than your actual selection. 

Graph Panel. By default, what is plotted for each time step is the mean, over the selected cells, of the modeled values of the selected variable.  For example, in PaleoCAR, each point on the default graph might represent the mean across the study area pixels of modeled mm of water year precipitation for a given year.

Customizing the Graphical Display. You can customize the graphical display in several ways.  First, the graph will be recalculated whenever you redefine the study area, change the temporal interval, or change the variable being analyzed (in the dropdown menu). Second, you can change the display by modifying parameters listed in the Statistics for the Temporal Interval displayed to the right of the graph (see below) once you click on the Update button.  Finally, you can use the Plotly functions (icons that appear when you put the cursor in the upper right of the graph), to zoom in or out on the graph. Use the reset axes button (tiny home icon) to restore the graph

Temporal Interval Statistics.  At the top of the Statistics panel, in the line starting with “Original,” SKOPE displays the mean, median, and standard deviation of the summarized values for the selected area over all time steps. In these calculations, at each time step the value used for the selected area is the summary value (mean by default) of all selected pixels.   If the values are Z-score transformed as described below, the mean median, and standard deviation of that fixed interval are displayed in the line beginning with “Transformed”.  If the values are smoothed, the mean median, and standard deviation of the smoothed or transformed and smoothed) data are displayed in the line beginning with “Smoothed”.   

For Each Time Step Summarize Selected Area As.You can change how the values for the selected area at each time step are summarized from the default, mean, to the median.  If the median is selected, the graph and Temporal Interval Mean, Median, and Standard Deviation will change to reflect that at each time step the median is used as the modeled value for the selected area at each time. While the mean is commonly used, the median provides a robust summary that is less sensitive to extreme values within the selected area at each time step. 

Transformation. The data may be Z-score transformed in three ways.  In a Z-score transformation, each value is subtracted from the mean value over a relevant time range and divided by the standard deviation of the values over that same time range. 

  • None: Modeled Values Displayed.  The modeled values are graphed without any transformation. 
  • Z-score wrt [with respect to] Selected Interval.  Instead of the summary values, the graph displays Z-score transformed values relative to the selected temporal interval. The Z-score value for a given year is the summary value for that year minus the mean summary value over all time steps in the selected interval with the result divided by the standard deviation of the summary values over all time steps in the selected interval.  The Z-score for a year is the number of standard deviations above (+) or below (-) the longer term mean for that interval. 
  • Z-score wrt Fixed Interval.  Instead of the summary values, the graph displays Z-score transformed values relative to a fixed interval entered by the user. The Z-score value for a given year is the summary value for that year minus the mean summary value over all time steps in the specified fixed interval with the result divided by the standard deviation of the summary values over all time steps in the fixed interval.  The Z-score for a year is the number of standard deviations above (+) or below (-) the fixed (often longer term) interval mean.  One might, for example, set the interval to be the span of the preceding time period.  Thus, in PaleoCAR  if the selected interval were AD900-1100, the fixed interval for the Z-score calculation might be  AD700 to 900.  In this case a Z-score value of -2.3 for precipitation for the year 1021 for would indicate that for the selected study area the modeled precipitation value for that year is substantially below (2.3 standard deviations below) the average computed for the AD 700 to 900 (previous time period) interval.
  • Z-score wrt Moving Interval.  Instead of the summary values, the graph displays Z-score transformed values relative to a moving window of a size selected by the user.  If the window size is n time steps, the value graphed for a given year is the Z-score (number of standard deviations above or below the mean, with both the mean and the standard deviation calculated over the calculated over the given year and the preceding n-1 years).  Thus, in PaleoCAR a Z-score value of +1.6 for precipitation for a given year using a 40 year moving window would indicate that for the selected study area the modeled precipitation value for that year is notably higher than (1.6 standard deviations above) average computed over the preceding two generations. The moving window is likely more relevant to on-the-ground perceptions of environmental conditions than either the modeled value themselves or Z-scores over a large range of past and/or future values. 

SmoothingThe graphed data can be smoothed in two ways. If the smoothing window extends before or after the period for which the dataset has modeled data, the smoothed value is Missing. 

  • None.  No smoothing the summary values for a given year are graphed.
  • Centered running average.  If the window width entered is n the graphed value for a given year is the mean of the n step summary values for the selected area centered on that year (n must be an odd number).
  • Trailing average. If the window width entered is n the graphed value for a year is the mean of the n time stepsummary values for the current year and the n-1 preceding years.

Note that the Areal Summary, Smoothing, and Transformation settings operate independently can be combined as desired. Thus, one could plot a trailing running average of robust (median based) values displayed as Z-scores relative to a moving temporal window.

Save the graph and the graphed data to your computer. The Download button  will download to your browser, in a ZIP file: the graph (plot) in svg and png formats, the raw and transformed data values (timeseries) behind the graph in tabular (json and csv) format, a readme file, a file with summary statistics (summary.Statistics.json), and a file that saves all parameters used to generate the graph (request.json).  Note that If the Areal Summary is the mean, then the raw data will be (default) mean values by time step, otherwise they will be median values by time step. 

Restore an Analysis State of the SKOPE Application. If you have downloaded the graph metadata in a previous session with the app (see description immediately above), you can restore the SKOPE app to that state.  To do this, extract the request.json file from the downloaded ZIP file (for example, drag it to your desktop).  Then, on any page in the SKOPE app click on the load analysis button (on the right  of the navigation bar or from the menu found on the left of the navigation bar menu) and load the request.json file from your computer.  You cannot load the request.json file directly from the zip file.

PaleoCAR – Methods

Paleoclimate reconstructions are created using the analytical package Paleoclimate Reconstruction from Tree Rings using Correlation-Adjusted corRelation (PaleoCAR) which is developed in R, a free software environment for statistical computing (Bocinsky 2015). PaleoCAR relies on published tree-ring chronologies and PRISM’s spatially modeled historical climate signals to generate long-term reconstructions (Bocinsky and Kohler 2014; Bocinsky et al. 2016). Tree ring chronologies were selected from the publicly available International Tree Ring Data Bank (ITRDB; Grissino-Mayer 2015; and Fritts 1997) and were geographically limited to include only chronologies within a 10-degree buffer of the Four Corners states, including Arizona, New Mexico, Utah, and Colorado. ITRDB data were downloaded and processed using the FedData package in R (Bocinsky 2016). Historical climate signals were selected from PRISM’s spatially interpolated monthly 800m x 800m grid cells (which take into account elevation and several aspects of topography; PRISM Climate Group 2004; Daly et al. 2008). The historical calibration data set was limited to A.D. 1924–1983 (Bocinsky and Kohler 2014).

PaleoCAR utilizes the CAR (Correlation-Adjusted corRelation) variable ranking and selection method to identify grid-cell specific combinations of tree ring chronologies that best estimate PRISM’s historical (1924–1983) values for that cell. PaleoCAR uses the long-term tree ring chronologies to create reconstructions of precipitation and growing-degree days that extend back to 1 C.E. (see Bocinsky and Kohler 2014 for complete methodology; Bocinsky et al. 2016). The result is an ~800m (30 arc-second) resolution data grid of a 2,000 year (1–2000 C.E.) spatiotemporal paleoclimate reconstruction for each climate signal.

Caveat: Uncertainty/Error. The retrodictions provided by this tool are, of course, estimates subject to error. There is some error in the spatial interpolation done by PRISM. There is also retrodiction model error that is dependent both on the location and the year, with earlier years generally having larger errors than more recent ones (when more tree ring chronologies can be referenced). In this version, we do not provide specific error estimates but see Bocinsky et al. (2016) for a discussion of the error.

Caveat: Need for Spatial Smoothing. Each grid cell independently selects the best-fitting set of tree-ring chronologies to use in the retrodiction in a given year. However, because the selections are done independently, adjacent cells can pick different chronologies. A single difference in the chronologies selected can have a substantial impact on the retrodicted values, especially if the cell is in an area that has a weaker association between chronologies and the historic PRISM climate signal. This is more of problem with temperature than with precipitation, especially in lower-elevation areas. Thus, one should be cautious about relying on between-cell differences within a small area.  If a study area larger than one cell is selected, the graphed data provide spatial smoothing by taking the mean (or median) of the value across the selected cells.

<<Do we need a discussion of the problem of low frequency signal in the temperature data. Other referencs?.>>

References Cited

Bocinsky, R. Kyle
2015     PaleoCAR: Paleoclimate Reconstruction from Tree Rings using Correlation Adjusted correlation. R package version 2.1. https://github.com/bocinsky/PaleoCAR/archive/2.1.tar.gz. <<Note, this just downloads a graphic of some sort.  Should we just refer to https://github.com/bocinsky/paleocar/ that has a readme file. I can’t figure out how to get a URL for the readme directly>>

Bocinsky, R. Kyle
2016     FedData: Functions to Automate Downloading Geospatial Data Available from Several Federated Data Sources. R package version 2.0.4.
http://CRAN.R-project.org/package=FedData

Bocinsky, R. Kyle, and Timothy A. Kohler
2014     A 2,000-year reconstruction of the rain-fed maize agricultural niche in the US Southwest. Nature Communications 5:5618. DOI: 10.1038/ncomms6618

Bocinsky, R. Kyle, Johnathan Rush, Keith W. Kintigh, and Timothy A. Kohler.
2016     Exploration and exploitation in the macrohistory of the prehispanic Pueblo Southwest. Science Advances 2(4): e1501532 (01 Apr 2016) DOI: 10.1126/sciadv.1501532 http://advances.sciencemag.org/content/2/4/e1501532

Daly, Christopher, Michael Halbleib, Joseph I. Smith, Wayne P. Gibson, Matthew K. Doggett, George H. Taylor, Jan Curtis and Phillip P. Pasteris
2008     Physiographically sensitive mapping of climatological temperature and precipitation across the conterminous United States. International Journal of Climatology. DOI: 10.1002/joc.1688

Grissino-Mayer, H.D.
2015     The International Tree Ring Data Bank. Accessed and available at http://web.utk.edu/~grissino/itrdb.htm .

Grissino-Mayer, Henri D. and Harold C. Fritts
1997     The International Tree-Ring Data Bank: An enhanced global database serving the global scientific community, The Holocene 7: 235–238.