---
title: "Available Data"
author: "Mazama Science"
date: "2020-11-30"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Available Data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Available Data for MazamaSpatialUtils

This document provides documentation for the most important of the available
datasets that can be used with **MazamaSpatialUtils**.

Spatial datasets that have been converted to objects of class
\code{SpatialPolygonsDataFrame} and adhere to the **MazamaSpatialUtils**
standards are considered to be "harmonized". 

For reproducibility, the R code that ingests and harmonizes each spatial dataset
is included in the package as a \code{convert<dataset>()} function.
Most of the resulting datasets have been been pre-generated and can be downloaded from
[http://data.mazamascience.com/MazamaSpatialUtils/Spatial_0.7/](http://data.mazamascience.com/MazamaSpatialUtils/Spatial_0.7/).

### Built in data

**MazamaSpatialUtils** has three built-in datasets which are included with the 
package when it is installed. Each of these is a simplified dataset suitable for
quick identification of \code{countryCode} or \code{timezone}.

* `SimpleCountries` -- Country outlines
* `SimpleCountriesEEZ` -- Country outlines including Exclusive Economic Zones over water
* `SimpleTimezones` -- Time zones

### Downloadable data

Running `installSpatialData()` allows users to install the following 
pre-generated datasets, which can then be loaded with `loadSpatialData(<dataset>)`

 * `CA_AirBasins` -- California regional air basin boundaries
 * `EEZCountries` -- Country boundaries including Exclusive Economic Zones
 * `EPARegions` -- US EPA region boundaries
 * `GACC` -- Geographic Area Coordination Center (GACC) boundaries
 * `GADM` -- GADM administrative area boundaries
 * `HIFLDFederalLands` -- US federal lands
 * `HMSSmoke` -- NOAA Hazard Mapping System Smoke (HMSS) areas
 * `HouseLegislativeDistricts` -- US state legislative districts, by chamber
 * `MTBSBurnAreas` -- MTBS burn areas from 1984 - 2017
 * `NaturalEarthAdm1` -- State/province/oblast level boundaries
 * `NWSFireZones` -- NWS fire weather forecast zones
 * `OSMTimezones` -- OpenStreetMap time zones
 * `PHDs` -- Public Health Districts for Washington, Oregon, Idaho, and California
 * `SimpleCountries` -- Simplified version of the TMWorldBorders
 * `SimpleCountriesEEZ` -- Simplified version of EEZCountries
 * `SimpleTimezones` -- Simplified version of WorldTimezones
 * `TerrestrialEcoregions` -- Terrestrial eco-regions
 * `TMWorldBorders` -- Country level boundaries
 * `USCensus116thCongress` -- US congressional districts
 * `USCensusCBSA` -- US Core Based Statistical Areas
 * `USCensusCounties` -- US county level boundaries
 * `USCensusStates` -- US state level boundaries
 * `USCensusUrbanAreas` -- US urban areas
 * `USFSRangerDistricts` -- US Forest Service ranger districts
 * `USIndianLands` -- US tribal boundaries
 * `WBDHU2` -- Watershed boundary level-2 hydrologic units
 * `WBDHU4` -- Watershed boundary level-4 hydrologic units
 * `WBDHU6` -- Watershed boundary level-6 hydrologic units
 * `WBDHU8` -- Watershed boundary level-8 hydrologic units
 * `WBDHU10` -- Watershed boundary level-10 hydrologic units
 * `WBDHU12` -- Watershed boundary level-12 hydrologic units
 * `weatherZones` -- NWS public weather forecast zones
 * `WorldEEZ` -- Country boundaries including Exclusive Economic Zones over water
 * `WorldTimezones` -- Timezone

## Dataset Descriptions

 * [`CA_AirBasins`:](#ca_airbasins) California regional air basin boundaries
 * [`EPARegions`:](#eparegions) US EPA region boundaries
 * [`GACC`:](#gacc) Geographic Area Coordination Center (GACC) boundaries
 * [`GADM`:](#gadm) GADM administrative area boundaries
 * [`HIFLDFederalLands`:](#hifldfederallands) US Federal Lands
 * [`HMSSmoke`:](#hmssmoke) NOAA Hazard Mapping System Smoke (HMSS) areas
 * [`MTBSBurnAreas`:](#mtbsburnareas)  MTBS Burn Areas from 1984 - 2017
 * [`NWSFireZones`:](#nwsfirezones) NWS fire weather forecast zones
 * [`PHDs`:](#phds) Public Health Districts for Washington, Oregon, Idaho, and California
 * [`SimpleCountries`:](#simplecountries) Simplified version of the TMWorldBorders shapefile
 * [`SimpleCountriesEEZ`:](#simplecountriesEEZ) Simplified version of EEZCountries
 * [`SimpleTimezones`:](#simpletimezones) Simplified version of WorldTimezones
 * [`HouseLegislativeDistricts`:](#houselegislativedistricts) US State Legislative Districts, by chamber
 * [`TMWorldBordersSimple`:](#tmworldborderssimple) Simplified version of TMWorldBorders
 * [`USCensusCBSA`:](#uscensuscbsa) US Core Based Statistical Areas
 * [`USCensusUrbanAreas`:](#uscensusurbanareas) US urban areas
 * [`USFSRangerDistricts`:](#usfsrangerdistricts) US Forest Service ranger districts
 * [`WBDHU`:](#wbdhu) Watershed boundary hydrologic units
 * [`weatherZones`:](#weatherzones) NWS public weather forecast zones
 * [`WorldEEZ`:](#worldeez) Country boundaries including Exclusive Economic Zones

#### CA_AirBasins:
Use `convertCARBAirBasins()` to download and convert this dataset.

The California Air Basins dataset is a `SpatialPolygonsDataFrame` representing the 
15 California air basins.  Air Basins are designated pursuant to California 
statute and regulation and identify regions of similar meteorological and 
geographic conditions.  Political boundaries are also considered in determining 
the air basin boundaries.  

_See the California Health and Safety Code, Section 39606 et seq. and California 
Code of Regulations, Title 17, Section 60100 et seq._

March, 2004 version.

#### EPARegions
Use `convertEPARegions()` to download and convert this dataset.

The EPARegions dataset is a  `SpatialPolygonsDataFrame` representing the 
boundaries of the ten Regional Offices of the United States Environmental 
Protection Agency in the United States. Each regional office monitors the 
environmental regulations within a group of states.

7/26/2019 Version

#### GACC
Use `convertGACC()` to download and convert this dataset.

The GACC dataset is a  `SpatialPolygonsDataFrame` representing the Geographic 
Area Coordination Center (GACC) boundaries.  GACCs are defined as, "The physical 
location of an interagency, regional operation center for the effective 
coordination, mobilization and demobilization of emergency management resources."  
A coordination center serves federal, state and local wildland fire agencies 
through logistical coordination of resources throughout the geographic area, and 
with other geographic areas, as well.

The United States and Alaska are divided into 11 Geographic Areas for the purpose 
of incident management and mobilization of resources (people, aircraft, ground 
equipment). Within each Area, an interagency Geographic Area Coordinating Group 
(GACG), made up of Fire Directors from each of the Federal and State land 
management agencies from within the Area, is established.

(NOTE: the current geojson download link seems to be dead.  A new, shapefile based, link to the data is https://opendata.arcgis.com/datasets/7dc5f4a286bd47e0aaafa0ab05302fe9_0.zip)

#### GADM
Use `convertGADM()` to download and convert this dataset.

The GADM dataset is a  `SpatialPolygonsDataFrame` representing the administrative 
divisions of a specific country at a specific administrative level.  GADM, the 
_Database of Global Administrative Areas_, is a high-resolution database of 
country administrative areas.

**NOTE:** This script will generate .rda files named 
`GADM_<countryCode>_<admLevel>.rda` and requires user input to specify the 
country and admin level desired.  For example, to generate Admin 1 level 
boundaries for Belgium, run `convertGADM(countryCode = "BE", admLevel = 1`.  
This will create `GADM_BE_1.rda`. Not all countries have the same number of 
levels. Many just have two levels while France has five.

#### HIFLDFederalLands
Use `convertHIFLDFederalLands()` to download and convert this dataset.

The HIFLDFederalLands dataset is a  `SpatialPolygonsDataFrame` representing the 
federally owned or administered lands and Indian Reservations of the United 
States, Puerto Rico, and the US Virgin Islands.  Only areas of 640 acres or more 
are included in this dataset.

#### HMSSmoke
Use `convertHMSSmoke()` to download and convert this dataset.

The HMSSmoke dataset is a  `SpatialPolygonsDataFrame` representing the areas of 
smoke identified for a specific day.  This data is derived from analysis of 
visible satellite imagery obtained during daylight hours.

**NOTE:** This script will generate .rda files named `HMSSmoke_<datestamp>` 
and requires user input to specify the date of interest using the `datestamp` 
parameter in the format of `datestamp = "YYYYmmdd"`.

#### MTBSBurnAreas
Use `convertMTBSBurnArea()` to download and convert this dataset.

The MTBSBurnAreas dataset is a  `SpatialPolygonsDataFrame` representing all 
large wildland fires (includes wildfire, wildland fire use, and prescribed fire) 
in the conterminous United States (CONUS), Alaska, Hawaii, and Puerto Rico for 
the period of 1984 through 2017.  All fires reported as greater than 1,000 acres 
in the western US and greater than 500 acres in the eastern US are mapped across 
all ownerships.

August 22, 2019 Version

#### NWSFireZones
Use `convertNWSFireZones()` to download and convert this data set.

The NWSFireZones dataset is a  `SpatialPolygonsDataFrame` representing weather 
forecast zones.  These areas are used to delineate the Fire Weather Zones that 
are used by National Weather Service (NWS) in the fire weather forecast program.

#### PHDs
Use `convertPHDs()` to download and convert this data set.

The PHDs dataset is a  `SpatialPolygonsDataFrame` representing Public Health 
Districts for Washington, Oregon, Idaho, and California.  This is Mazama internal 
data obtained from USFS AirFire.

#### SimpleCountries
Use `convertSimpleCountries()` to download and convert this data set.

The SimpleCountries dataset is a `SpatialPolygonsDataFrame` representing 
country borders.  It is a greatly simplified version of the TMWorldBorders 
shapefile and is especially suited for spatial searches. Users may wish to use a 
higher resolution dataset when plotting.

30 July 2008 Version

#### SimpleCountriesEEZ
Use `convertSimpleCountriesEEZ()` to download and convert this data set.

The SimpleCountriesEEZ dataset is a  `SpatialPolygonsDataFrame` representing 
simple world divisions which match those in the EEZCountries layer. Polygons 
for coastal countries include a 200 mile buffer, corresponding to their Exclusive 
Economic Zones, so this layer is especially suited for spatial searches.   This 
is the default dataset used in `getCountry()` and `getCountryCode()`.

#### SimpleTimeZones
Use `convertSimpleTimezones()` to download and convert this data set.

The SimpleTimeZones dataset is a  `SpatialPolygonsDataFrame` representing 
timezones of the world.

May 28, 2016 Version

#### HouseLegislativeDistricts
Use `convertStateLegislativeDistricts()` to download and convert this data set.

This creates a `SpatialPolygonsDataFrame` for US State Legislative Districts.  
User input is required to specify the `stateCode` (2-digit ISO 3166) and which 
`house` (Upper or Lower chamber) the data should represent.  For example, to 
obtain data on the Washington State Senate Legislative Districts, run 
`convertStateLegislativeDistricts(stateCode = "WA", house = "Upper")`.  This 
will generate a file named `WA_upperHouseLegislativeDistricts.rda`

#### TMWorldBordersSimple
Use `convertTMWorldBordersSimple()` to download and convert this data set.

The TMWorldBordersSimple dataset is a  simplified version of the TMWorldBorders 
layer which is useful for spatial searches.  Users may wish to use a higher 
resolution dataset when plotting.

#### USCensusCBSA
Use `convertUSCensusCBSA()` to download and convert this data set.

The USCensusCBSA dataset is a  `SpatialPolygonsDataFrame` which represents Core 
Based Statistical Areas (CBSAs) as defined by the Office of Management and Budget 
(OMB).  CBSAs consist of the county or counties or equivalent entities associated 
with at least one core (urbanized area or urban cluster) of at least 10,000 
population, plus adjacent counties having a high degree of social and economic 
integration with the core as measured through commuting ties with the counties 
associated with the core.

2017 Version

#### USCensusUrbanAreas
Use `convertUSCensusUrbanAreas()` to download and convert this data set.

The USCensusUrbanAreas dataset is a  SpatialPolygonsDataFrame which represent 
the urban areas delineated by the US Census that represent densely developed 
territory.  There are two types of urban areas: urbanized areas (UAs) that 
contain 50,000 or more people and urban clusters (UCs) that contain at least 
2,500 people, but fewer than 50,000 people.

2018 Version

#### USFSRangerDistricts
Use `convertUSFSRangerDistricts()` to download and convert this data set.

The USFSRangerDistricts dataset is a  SpatialPolygonsDataFrame representing US 
Forest Service ranger district administrative boundaries.  Ranger districts are 
sub units of National Forests intended to identify the specific organizational 
units that administer areas.

Feb 3, 2020 Version

#### WBDHU
Use `convertWBDHUC()` to download and convert this data set.

This creates a `SpatialPolygonsDataFrame` that represents a specific level of 
hydrologic unit  from national Watershed Boundary Dataset (WBD).  This is a 
seamless, national dataset which represents the area of the landscape that 
drains to a portion of the stream network.

User input is required to specify the `level` of data to generate.   The `level` 
must be one of the following: [2, 4, 6, 8, 10, 12 or 14].  To generate a Level 8 
data set, run `convertWBDHUC(level = 8)` which will generate a file named 
`WBDHU8.rda`.

#### WeatherZones
Use `convertWeatherZones()` to download and convert this data set.

This creates a `SpatialPolygonsDataFrame` that represents public zone weather 
forecast areas.  The NWS issues forecasts, and some watches and warnings, for 
public zones which are usually the same as counties but in many cases are 
subsets of counties. Counties are subset into smaller zones to allow for more 
accurate forecasts because of differences in weather within a county due to such 
things as elevation, or proximity to large bodies of water.

#### WorldEEZ
Use `convertWorldEEZ()` to download and convert this data set.

This creates a `SpatialPolygonsDataFrame` that represents World Exclusive 
Economic Zones Boundaries.  An exclusive economic zone is a sea zone prescribed 
by the 1982 United Nations Convention on the Law of the Sea over which a state 
has special rights regarding the exploration and use of marine resources, 
including energy production from water and wind.

Version 8

----
