Read simple features from file or database, or retrieve layer names and their geometry type(s)

Read PostGIS table directly through DBI and RPostgreSQL interface, converting Well-Know Binary geometries to sfc

st_read(dsn, layer, ...)

# S3 method for character
st_read(dsn, layer, ..., options = NULL, quiet = FALSE,
  geometry_column = 1L, type = 0, promote_to_multi = TRUE,
  stringsAsFactors = default.stringsAsFactors(), int64_as_string = FALSE,
  check_ring_dir = FALSE)

read_sf(..., quiet = TRUE, stringsAsFactors = FALSE)

# S3 method for DBIObject
st_read(dsn = NULL, layer = NULL, query = NULL,
  EWKB = TRUE, ...)

Arguments

dsn

data source name (interpretation varies by driver - for some drivers, dsn is a file name, but may also be a folder, or contain the name and access credentials of a database); in case of GeoJSON, dsn may be the character string holding the geojson data. It can also be an open database connection.

layer

layer name (varies by driver, may be a file name without extension); in case layer is missing, st_read will read the first layer of dsn, give a warning and (unless quiet = TRUE) print a message when there are multiple layers, or give an error if there are no layers in dsn. If dsn is a database connection, then layer can be a table name or a database identifier (see Id). It is also possible to omit layer and rather use the query argument.

...

parameter(s) passed on to st_as_sf

options

character; driver dependent dataset open options, multiple options supported.

quiet

logical; suppress info on name, driver, size and spatial reference, or signaling no or multiple layers

geometry_column

integer or character; in case of multiple geometry fields, which one to take?

type

integer; ISO number of desired simple feature type; see details. If left zero, and promote_to_multi is TRUE, in case of mixed feature geometry types, conversion to the highest numeric type value found will be attempted. A vector with different values for each geometry column can be given.

promote_to_multi

logical; in case of a mix of Point and MultiPoint, or of LineString and MultiLineString, or of Polygon and MultiPolygon, convert all to the Multi variety; defaults to TRUE

stringsAsFactors

logical; logical: should character vectors be converted to factors? The `factory-fresh' default is TRUE, but this can be changed by setting options(stringsAsFactors = FALSE).

int64_as_string

logical; if TRUE, Int64 attributes are returned as string; if FALSE, they are returned as double and a warning is given when precision is lost (i.e., values are larger than 2^53).

check_ring_dir

logical; if TRUE, polygon ring directions are checked and if necessary corrected (when seen from above: exterior ring counter clockwise, holes clockwise)

query

SQL query to select records; see details

EWKB

logical; is the WKB is of type EWKB? if missing, defaults to TRUE

Value

object of class sf when a layer was successfully read; in case argument layer is missing and data source dsn does not contain a single layer, an object of class sf_layers is returned with the layer names, each with their geometry type(s). Note that the number of layers may also be zero.

Details

for geometry_column, see also https://trac.osgeo.org/gdal/wiki/rfc41_multiple_geometry_fields

for values for type see https://en.wikipedia.org/wiki/Well-known_text#Well-known_binary, but note that not every target value may lead to successful conversion. The typical conversion from POLYGON (3) to MULTIPOLYGON (6) should work; the other way around (type=3), secondary rings from MULTIPOLYGONS may be dropped without warnings. promote_to_multi is handled on a per-geometry column basis; type may be specified for each geometry column.

In case of problems reading shapefiles from USB drives on OSX, please see https://github.com/r-spatial/sf/issues/252.

read_sf and write_sf are aliases for st_read and st_write, respectively, with some modified default arguments. read_sf and write_sf are quiet by default: they do not print information about the data source. read_sf returns an sf-tibble rather than an sf-data.frame. write_sf delete layers by default: it overwrites existing files without asking or warning.

if table is not given but query is, the spatial reference system (crs) of the table queried is only available in case it has been stored into each geometry record (e.g., by PostGIS, when using EWKB)

The function will automatically find the `geometry` type columns for drivers that support it. For the other drivers, it will try to cast all the character columns, which can be slow for very wide tables.

Note

The use of system.file in examples make sure that examples run regardless where R is installed: typical users will not use system.file but give the file name directly, either with full path or relative to the current working directory (see getwd). "Shapefiles" consist of several files with the same basename that reside in the same directory, only one of them having extension .shp.

Examples

nc = st_read(system.file("shape/nc.shp", package="sf"))
#> Reading layer `nc' from data source `/home/travis/build/r-spatial/sf/inst/shape/nc.shp' using driver `ESRI Shapefile' #> Simple feature collection with 100 features and 14 fields #> geometry type: MULTIPOLYGON #> dimension: XY #> bbox: xmin: -84.32385 ymin: 33.88199 xmax: -75.45698 ymax: 36.58965 #> epsg (SRID): 4267 #> proj4string: +proj=longlat +datum=NAD27 +no_defs
summary(nc) # note that AREA was computed using Euclidian area on lon/lat degrees
#> AREA PERIMETER CNTY_ CNTY_ID NAME #> Min. :0.0420 Min. :0.999 Min. :1825 Min. :1825 Alamance : 1 #> 1st Qu.:0.0910 1st Qu.:1.324 1st Qu.:1902 1st Qu.:1902 Alexander: 1 #> Median :0.1205 Median :1.609 Median :1982 Median :1982 Alleghany: 1 #> Mean :0.1263 Mean :1.673 Mean :1986 Mean :1986 Anson : 1 #> 3rd Qu.:0.1542 3rd Qu.:1.859 3rd Qu.:2067 3rd Qu.:2067 Ashe : 1 #> Max. :0.2410 Max. :3.640 Max. :2241 Max. :2241 Avery : 1 #> (Other) :94 #> FIPS FIPSNO CRESS_ID BIR74 SID74 #> 37001 : 1 Min. :37001 Min. : 1.00 Min. : 248 Min. : 0.00 #> 37003 : 1 1st Qu.:37050 1st Qu.: 25.75 1st Qu.: 1077 1st Qu.: 2.00 #> 37005 : 1 Median :37100 Median : 50.50 Median : 2180 Median : 4.00 #> 37007 : 1 Mean :37100 Mean : 50.50 Mean : 3300 Mean : 6.67 #> 37009 : 1 3rd Qu.:37150 3rd Qu.: 75.25 3rd Qu.: 3936 3rd Qu.: 8.25 #> 37011 : 1 Max. :37199 Max. :100.00 Max. :21588 Max. :44.00 #> (Other):94 #> NWBIR74 BIR79 SID79 NWBIR79 #> Min. : 1.0 Min. : 319 Min. : 0.00 Min. : 3.0 #> 1st Qu.: 190.0 1st Qu.: 1336 1st Qu.: 2.00 1st Qu.: 250.5 #> Median : 697.5 Median : 2636 Median : 5.00 Median : 874.5 #> Mean :1050.8 Mean : 4224 Mean : 8.36 Mean : 1352.8 #> 3rd Qu.:1168.5 3rd Qu.: 4889 3rd Qu.:10.25 3rd Qu.: 1406.8 #> Max. :8027.0 Max. :30757 Max. :57.00 Max. :11631.0 #> #> geometry #> MULTIPOLYGON :100 #> epsg:4267 : 0 #> +proj=long...: 0 #> #> #> #>
# NOT RUN { library(sp) example(meuse, ask = FALSE, echo = FALSE) try(st_write(st_as_sf(meuse), "PG:dbname=postgis", "meuse", layer_options = "OVERWRITE=true")) try(st_meuse <- st_read("PG:dbname=postgis", "meuse")) if (exists("st_meuse")) summary(st_meuse) # }
# read geojson from string: geojson_txt <- paste("{\"type\":\"MultiPoint\",\"coordinates\":", "[[3.2,4],[3,4.6],[3.8,4.4],[3.5,3.8],[3.4,3.6],[3.9,4.5]]}") x = read_sf(geojson_txt) x
#> Simple feature collection with 1 feature and 0 fields #> geometry type: MULTIPOINT #> dimension: XY #> bbox: xmin: 3 ymin: 3.6 xmax: 3.9 ymax: 4.6 #> epsg (SRID): 4326 #> proj4string: +proj=longlat +datum=WGS84 +no_defs #> geometry #> 1 MULTIPOINT (3.2 4, 3 4.6, 3...
# NOT RUN { library(RPostgreSQL) try(conn <- dbConnect(PostgreSQL(), dbname = "postgis")) if (exists("conn") && !inherits(conn, "try-error")) { x = st_read(conn, "meuse", query = "select * from meuse limit 3;") x = st_read(conn, table = "public.meuse") print(st_crs(x)) # SRID resolved by the database, not by GDAL! dbDisconnect(conn) } # }