Skip to content

Home

Jump to bottom Edit New page
Emmanuel Blondel edited this page Jun 14, 2021 · 22 revisions

ows4R - R Interface to OGC Web-services

ows4R intends to provide an interface in R for using OGC web-services, and associated standards. These standards are designed to provide a common way to access and manage geographic data on the web.

At now The services covered with ows4R are:

  • WFS (Web Feature Service) - versions 1.0.0,1.1.1, 2.0.0 for accessing vector data. The Transaction mode of WFS (to perform Insertions, Updates or Deletions) is not yet enabled in ows4R
  • CSW (Catalogue Service for the Web) - version 2.0.2 (with Transaction mode) for managing geographic metadata

The associated standard formats include:

  • the Filter Encoding (except version 2.0) allows to define filters for query geographic information

If you wish to sponsor ows4R, do not hesitate to contact me

Table of contents

1. Overview
2. Package status
3. Credits
4. User guide
   4.1 Installation
   4.2 Catalogue Service (CSW)
      4.2.1 Create CSW Client
      4.2.2 Get Capabilities (GetCapabilities)
      4.2.3 Describe a Record (DescribeRecord)
      4.2.4 Get a Record (GetRecordById)
      4.2.5 Get Records (GetRecords)
         ├ Basic query
         ├ Query with maxRecords parameter
         ├ Query with CQL filters
         └ Query with OGC filters
      4.2.6 Transactions (Insert, Update, Delete) (Transaction)
   4.3 Web Feature Service (WFS)
      4.3.1 Create WFS Client
      4.3.2 Get Capabilities (GetCapabilities)
      4.3.3 Find a FeatureType by name
      4.3.4 Get FeatureType description (DescribeFeatureType)
      4.3.5 Get Features (GetFeature)
      4.3.6 Transactions (Insert, Update, Delete) (Transaction)
   4.4 Web Coverage Service (WCS)
5. Issue reporting

1. Overview and vision

Until now, equivalent tools were existing for other programming languages (e.g. Java, Python) but not in R. ows4R intends to provide facilities to exploit OGC web-services in R. In principle, whatever standard (service or associated format) approved by OGC and referenced on the official OGC website is a potential candidate for integration into ''ows4R''. Focus will be given to standards for which no implementation is available in the R spatial community in other package.

2. Development status

ows4R is under active development, and is a new project born in 2018. A first version has been released to CRAN which will focus on:

  • Web Feature Service (WFS), the OGC standard service for vector data handling, and
  • the Catalogue Service (CSW), the OGC standard service for metadata management

3. Credits

(c) 2018, Emmanuel Blondel

Package distributed under MIT license.

If you use ows4R, i would be very grateful if you can add a citation in your published work. By citing ows4R, beyond acknowledging the work, you contribute to make it more visible and contribute to its growing and sustainability.

You can get the preferred citation by using the ows4R Document Object Identifier (DOI): DOI

4. User guide

4.1 How to install ows4R in R

The package is available on CRAN, and be installed with:

install.packages("ows4R")

The development version can be installed from GitHub

install.packages("devtools")

Once the devtools package loaded, you can use the install_github to install ows4R. By default, package will be installed from master which is the current version in development (likely to be unstable).

require("devtools")
install_github("eblondel/ows4R")

4.2 R Interface to Catalogue Service (CSW)

An overview of the Catalogue Service (CSW) can be found on the official OGC webpage: http://www.opengeospatial.org/standards/cat

4.2.1 Create CSW Client

In order to operate on a Catalogue Service, you need to create an interface in R to this WFS. This is done with the class CSWClient, as follows:

csw <- CSWClient$new("http://localhost:8080/csw", "2.0.2", logger = "INFO")

You can define the level of logger: "INFO" to get ows4R logs, "DEBUG" for all internal logs (such as as Curl details). It is also possible to define a username and credentials in case operations would require an authentication to use the Catalogue Service.

For operations that require authentication (e.g. CSW Transaction operations on GeoNetwork), you may need to specify the user and pwd parameters.

4.2.2 Get Capabilities (GetCapabilities)

When create the CSWClient, ows4R will run a GetCapabilities request. To access the CSW Capabilities and its sections, you can use the following code:

caps <- csw$getCapabilities()

4.2.3 Describe a record (DescribeRecord)

NOT YET SUPPORTED

4.2.4 Get a record (GetRecordById)

The below example shows how to get a metadata record by ID, and bind it with geometa classes.

#supposing a metadata identified as "my-metadata-identifier"
md <- csw$getRecordById("my-metadata-identifier", outputSchema = "http://www.isotc211.org/2005/gmd")

4.2.5 Get records (GetRecords)

This section gives several examples how to get records with the ows4R CSW client.

Basic query

A basic GetRecords request can be done with the following code:

records <- csw$getRecords()

By default, this request will return the 5 first metadata records. These records are returned in the Dublin Core metadata format, handled as list in R.

Query with maxRecords parameter

To change the maximum number of records to be returned, use the maxRecords parameter

records <- csw$getRecords(maxRecords = 20L)
Query with CQL filters

To query records based on a filter, we introduce 2 notions inherited from the CSW specification: a query handled in ows4R that will accept as parameter a constraint (corresponding to a given filter).

Query with CQL Filter on metadata title

The example below shows you:

  • how to create a CSWConstraint specifying a CQL text filter on metadata title. Here the properties refer to the Dublin Core metadata format, hence the notation dc:title.
  • how to set a CSWQuery based on this constraint/filter
  • how to get get metadata records based on the query
cons <- CSWConstraint$new(cqlText = "dc:title like '%ips%'")
query <- CSWQuery$new(constraint = cons)
records <- csw$getRecords(query = query)

Query with CQL Filter on metadata title and abstract

Another example of GetRecords query with a CQL filter based on two properties (title, abstract):

cons <- CSWConstraint$new(cqlText = "dc:title like '%ips%' and dct:abstract like '%pharetra%'")
query <- CSWQuery$new(constraint = cons)
records <- csw$getRecords(query = query)

Query with CQL Filter on metadata identifier

We may also try to perform a ``GetRecords``` based on a metadata identifier. In case there is an existing metadata record with such identifier, we expect to get a list of length 1.

cons <- CSWConstraint$new(cqlText = "dc:identifier = 'my-metadata-identifier'")
query <- CSWQuery$new(constraint = cons)
records <- csw$getRecords(query = query)
Query with OGC filters

Instead of using a CQL text filter, ows4R allows to specify an OGC Filter as basis to build the CSWConstraint. OGC Filters can be created with the class/function OGCFilter specifying an expression, among the following:

  • Simple OGC expressions
    • PropertyIsEqualTo / PropertyIsNotEqualTo
    • PropertyIsLessThan / PropertyIsGreaterThan
    • PropertyIsLessThanOrEqualTo / PropertyIsGreaterThanOrEqualTo
    • PropertyIsLike
    • PropertyIsNull
    • PropertyIsBetween
    • BBOX
  • Combinations of OGC expressions
    • And
    • Or
    • Not

Query with OGC filter - PropertyIsLike

The below example constructs a constraint with an OGCFilter made of a PropertyIsLike predicate on CSW AnyText. The result will be a list of records for which _any text is like '%Physio%' (all records for which the string 'Physio' is included):

filter <- OGCFilter$new( PropertyIsLike$new("csw:AnyText", "%Physio%"))
cons <- CSWConstraint$new(filter = filter)
query <- CSWQuery$new(constraint = cons)
records <- csw2$getRecords(query = query)

Query with OGC filter - PropertyIsEqualTo

filter <- OGCFilter$new( PropertyIsEqualTo$new("csw:AnyText", "species"))
cons <- CSWConstraint$new(filter = filter)
query <- CSWQuery$new(constraint = cons)
records <- csw$getRecords(query = query)

4.2.6 Transaction - Insert,Update,Delete (Transaction)

If the CSW server used supports Transaction operations (Insert, Update, Delete), ows4R allows you to perform these operations. The following examples highlight the different operations available:

Insert

mdfile <- system.file("extdata/data", "metadata.xml", package = "ows4R")
md <- geometa::ISOMetadata$new(xml = XML::xmlParse(mdfile))
insert <- csw$insertRecord(record = md)
insert$getResult() #TRUE if inserted, FALSE otherwise

Update (Full)

md$identificationInfo[[1]]$citation$setTitle("a new title")
update <- csw$updateRecord(record = md)
update$getResult() #TRUE if updated, FALSE otherwise

Update (Partial)

recordProperty <- CSWRecordProperty$new("apiso:Title", "NEW_TITLE")
filter = OGCFilter$new(PropertyIsEqualTo$new("apiso:Identifier", md$fileIdentifier))
constraint <- CSWConstraint$new(filter = filter)
update <- csw$updateRecord(recordProperty = recordProperty, constraint = constraint)
update$getResult() #TRUE if updated, FALSE otherwise

Delete

delete <- csw$deleteRecordById(md$fileIdentifier)
delete$getResult() #TRUE if deleted, FALSE otherwise

The methods insertRecord and updateRecord also support options to deal with geometa ISOMetadata objects. The option geometa_validate is set by default to TRUE and operates a validation vs. ISO/TC 19139 schemas. The option geometa_inspire can be enabled to test the metadata with INSPIRE. Records inserted/updated through CSW-T will then include a footer of XML comments containing the validation details. See the geometa documentation

4.3 R interface to Web Feature Service (WFS)

The Web Feature Service (WFS) is official OGC standard service for handling geospatial vector data. Documentation on WFS can be found on the official OGC webpage: http://www.opengeospatial.org/standards/wfs

4.3.1 Create WFS Client

In order to operate on a Web Feature Service, you need to create an interface in R to this WFS. This is done with the class WFSClient, as follows:

wfs <- WFSClient$new("http://localhost:8080/geoserver/wfs", "2.0.0", logger = "INFO")

You can define the level of logger: "INFO" to get ows4R logs, "DEBUG" for all internal logs (such as as Curl details). It is also possible to define a username and credentials in case operations would require an authentication to use the Web Feature Service.

4.3.2 Get Capabilities (GetCapabilities)

When create the WFSClient, ows4R will run a GetCapabilities request. To access the WFS Capabilities and its sections, you can use the following code:

caps <- wfs$getCapabilities()

4.3.3. Find a FeatureType by name

ows4R gives the possibliity to find a FeatureType ("layer") by specifying its name.

ft <- caps$findFeatureTypeByName("topp:tasmania_water_bodies")

4.3.4 Get FeatureType description (DescribeFeatureType)

Once you get a featuretype, you may get its description (which corresponds to the result of a WFS DescribeFeatureType request). The pretty argument allows to return as data.frame output for human reading.

desc <- ft$getDescription(pretty = TRUE)

4.3.5 Get Features(GetFeature)

And finally you may want to get the actual features (geospatial data) for the given feature type (which corresponds to the the result of a WFS GetFeature request). By default, ows4R follows the OGC Simple Feature Specification. The output of the getFeatures() function will be an object of class sf (see package sf for more details).

sf <- ft$getFeatures()

If you are more familiar with spatial objects managed with the sp package. You may want to coerce the object into "Spatial" object:

sp <- as(sf, "Spatial")

4.3.6 Transactions (Insert,Update,Delete) (Transaction)

NOT YET SUPPORTED!

4.3 R interface to Web Coverage Service (WCS)

The Web Coverage Service R interface is under prototyping. If you require such interface for your needs, please consider sponsoring the project.

5. Issue reporting

Issues can be reported at https://github.com/eblondel/ows4R/issues

Add a custom footer
Add a custom sidebar
Clone this wiki locally