Merge pull request #267 from uwescience/253-chore-document-order-of-location-columns-in-crosswalkmd-and-doctrings-for-crosswalk_spatial

updated funcs and docs for crosswalk_spatial

Author: Jihyeonbae

code/crosswalk/crosswalk_geom.R

@@ -5,13 +5,14 @@ crosswalk_geom <- function(data, target, location_columns = NULL, extensive = FA
     #' 
     #' @param data: point data (lat, lon) or a shapefile containing shapes (polygons, lines, etc.)
     #' @param target: shapefile containing shapes (polygons, lines, etc.). This is for the target boundaries/geographic levels (assumes larger than the starting level I think). 
-    #' @param location_columns: required for points (e.g c("LATITUDE", "LONGITUDE") or c("lat", "lon") depending on data format), not required for shapefile data. 
+    #' @param location_columns: required for points (e.g c("LONGITUDE", "LATITUDE") or c("lon", "lat") depending on data name format), not required for shapefile data. 
     #' @param extensive: TRUE if data of interest is spatially extensive, (e.g population) or FALSE if spatially intensive (e.g population density) 
     #' @param join_method: in the case of shapefile to shapefile (multipoint and polygons, not points) crosswalks, choose "max_area" 
     #'                    or "areal-weighted" to inherit values of source data based on maximum intersection or a area-weighted average
     #'                    of all intersecting polygons. NULL in other cases, where the mean is taken by default.  
     #' @output 
     #' Returns a joined dataset on the target scale (a shapefile). 
+    #' @export
 
   if (length(location_columns) == 2) {
 
@@ -35,7 +36,7 @@ crosswalk_geom <- function(data, target, location_columns = NULL, extensive = FA
         data <- st_transform(data, crs = st_crs(target))
         data <- st_make_valid(data)
         # Perform the spatial join using areal aggregation extensive = TRUE (spatially extensive, e.g population) or extensive = FALSE (spatially intensive, e.g population density) 
-        joined <- st_interpolate_aw(data, target, extensive = extensive)
+        joined <- st_interpolate_aw(data, target, extensive = extensive, na.rm = TRUE, keep_na = TRUE)
   }
 
   return(joined)

code/crosswalk/crosswalk_raster.R

@@ -4,7 +4,7 @@ crosswalk_raster <- function(data, target, location_columns = NULL, extensive =
   #' 
   #' @param data: point data (lat, lon) or a shapefile containing shapes (polygons, lines, etc.)
   #' @param target: shapefile containing shapes (polygons, lines, etc.). This is for the target boundaries/geographic levels (assumes larger than the starting level I think). 
-  #' @param location_columns: required for points (e.g c("LATITUDE", "LONGITUDE") or c("lat", "lon") depending on data format), not required for shapefile data. 
+  #' @param location_columns: required for points (e.g c("LONGITUDE", "LATITUDE") or c("lon", "lat") longitude first, latitude second). Not required for shapefile data. 
   #' @param extensive: TRUE if data of interest is spatially extensive, (e.g population) or FALSE if spatially intensive (e.g population density) 
   #' @param join_method: in the case of shapefile to shapefile (multipoint and polygons, not points) crosswalks, choose "max_area" 
   #'                    or "areal-weighted" to inherit values of source data based on maximum intersection or a area-weighted average
@@ -17,7 +17,7 @@ crosswalk_raster <- function(data, target, location_columns = NULL, extensive =
   #' Point data is maintained as points. User must rasterize resulting dataframe if they want the output of a point/raster join to be in raster form.
   #' Raster/shapefile combinations will output a shapefile, not a raster. User must rasterize polygon data if they want the output to be a raster. 
   #' Raster/raster combinations take the mosaic mean of the two files. The output is a raster. Users must combine with another shapefile if they want a shapefile output. 
-  #' 
+  #' @export
 
 
   # Function for Raster/Raster
@@ -71,7 +71,7 @@ crosswalk_raster <- function(data, target, location_columns = NULL, extensive =
         polygonized_raster <- st_make_valid(data)
 
         #take the areal-weighted mean/sum of the polygonized raster and shapefile polygons
-        new_shapefile <- st_interpolate_aw(polygonized_raster, shapefile, extensive = extensive)
+        new_shapefile <- st_interpolate_aw(polygonized_raster, shapefile, extensive = extensive, na.rm = TRUE, keep_na = TRUE)
         return(new_shapefile)
       }
 

code/crosswalk/crosswalk_spatial.R

@@ -13,7 +13,7 @@ crosswalk_spatial <- function(data, target, location_columns = NULL, extensive =
   #' @param data: data on the source geographic scale. Can be a shapefile, raster, or in the case of point data, a table with lat/lon columns. 
   #' point data (lat, lon) or a shapefile containing shapes (polygons, lines, etc.). For point data crosswalking to a target polygon geometry, data is maintained on the point scale and assigned to a geometry (requires users to perform aggregation of choice outside the function
   #' @param target: shapefile containing shapes (polygons, lines, etc.). This is for the target boundaries/geographic levels. 
-  #' @param location_columns: only required for points (e.g c("LATITUDE", "LONGITUDE") or c("lat", "lon") depending on data format), not required for shapefile or raster data. 
+  #' @param location_columns: only required for points (e.g ("LONGITUDE", "LATITUDE") or c("lon", "lat"), longitude first and latitude second). Not required for shapefile or raster data. 
   #' @param extensive: TRUE if data of interest is spatially extensive, (e.g population, function = SUM) or FALSE if spatially intensive (e.g population density, function = MEAN). 
   #' @param join_method: in the case of shapefile to shapefile (multipoint and polygons, not points) crosswalks, choose "max_area" 
   #'                    or "areal_weighted" to inherit values of source data based on maximum intersection assignment or a area-weighted average/sum
@@ -22,12 +22,20 @@ crosswalk_spatial <- function(data, target, location_columns = NULL, extensive =
   #' Returns a shapefile on the target scale (except raster/raster combinations, which output a stacked raster). Please check that your data is correctly aggregated and adjust input parameters as needed. 
   #' @Notes
   #' Relies on functions crosswalk_geom.R (data, target, location_columns, extensive, join_method) and crosswalk_raster.R (data, target, location_columns, extensive). 
+  #' 
   #' This function will automatically detect geometry columns associated with shapefiles. 
+  #' 
+  #' Please be mindful of NA values prior to performing spatial crosswalks/joins. When taking areal-weighted averages and sums, all target geometries will be maintained even
+  #'  if the resulting interpolation is NA. Prior to calculating the interpolation, NA values in the source data will be removed so as to not cause calculations to return NA. You will need to check your NAs and handle them in the way you see appropriate before using the crosswalked data output by this function.  
+  #'  
+  #' When assigning points to shapes, all points will be returned with their associated shapes (left join where points are maintained). When assigning point values to a raster, you will end up with a polygonized raster with appended values for points contained by the raster squares.
+  #' 
+  #'  
   #' Notes on using raster data in combination with other data: 
   #'  Point data is set on the raster scale but maintains its original values. NA values for polygonized rasters not containing a point. Will double count polygons containing multiple points. 
   #'  Raster/shapefile combinations will output a shapefile, not a raster. User must rasterize polygon data if they want the output to be a raster. 
   #'  Raster/raster combinations stack the two files to be a stacked raster object. The output is a stacked raster. Users must combine with another shapefile if they want a shapefile output. 
-  #' 
+  #' @export
 
   require(sf)
   require(raster)