-
Notifications
You must be signed in to change notification settings - Fork 13
/
README.Rmd
160 lines (111 loc) · 6.74 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
---
output:
github_document:
html_preview: true
---
<!--
Copyright 2018 Province of British Columbia
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and limitations under the License.
-->
```{r setup, echo = FALSE, warning = FALSE, message = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/"
)
library(bcdata)
```
# bcdata <a href='https://bcgov.github.io/bcdata/'><img src='man/figures/logo.png' align="right" height="139" /></a>
<!-- badges: start -->
[](https://opensource.org/license/apache-2-0/)
[](https://cran.r-project.org/package=bcdata) [](https://CRAN.R-project.org/package=bcdata) [](https://CRAN.R-project.org/web/checks/check_results_bcdata.html)
[](https://github.com/bcgov/repomountie/blob/master/doc/lifecycle-badges.md)
[](https://doi.org/10.21105/joss.02927)
[](https://doi.org/10.5281/zenodo.4737824)
[](https://app.codecov.io/gh/bcgov/bcdata?branch=main)
[](https://github.com/bcgov/bcdata/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
An R package 📦 for searching & retrieving data from the [B.C. Data Catalogue]( https://catalogue.data.gov.bc.ca).
- `bcdc_browse()` - Open the catalogue in your default browser
- `bcdc_search()` - Search records in the catalogue
- `bcdc_search_facets()` - List catalogue facet search options
- `bcdc_get_record()` - Print a catalogue record
- `bcdc_tidy_resources()` - Get a data frame of resources for a record
- `bcdc_get_data()` - Get catalogue data
- `bcdc_query_geodata()` - Get & query catalogue geospatial data available through a [Web Feature Service](https://en.wikipedia.org/wiki/Web_Feature_Service)
**Note:** The `bcdata` package supports downloading _most_ file types, including zip archives. It will do its best to identify and read data from
zip files, however if there are multiple data files in the zip, or data files that `bcdata` doesn't know how to import, it will fail.
If you encounter a file type in the B.C. Data Catalogue not currently supported by `bcdata` please file an [issue](https://github.com/bcgov/bcdata/issues/).
### Reference
[bcdata package 📦 home page and reference guide](https://bcgov.github.io/bcdata/)
### Installation
You can install `bcdata` directly from [CRAN](https://cran.r-project.org/package=bcdata):
```{r eval=FALSE}
install.packages("bcdata")
```
To install the development version from GitHub, use the [remotes](https://cran.r-project.org/package=remotes) package:
```{r eval=FALSE}
install.packages("remotes")
remotes::install_github("bcgov/bcdata")
library(bcdata)
```
### Vignettes
- [Get Started with bcdata](https://bcgov.github.io/bcdata/articles/bcdata.html)
- [Querying Spatial Data with bcdata](https://bcgov.github.io/bcdata/articles/efficiently-query-spatial-data-in-the-bc-data-catalogue.html)
- [Exploring Silviculture Data with bcdata](https://bcgov.github.io/bcdata/articles/explore-silviculture-data-using-bcdata.html)
### Methods for `bcdc_promise`
The `bcdc_query_geodata()` returns an object of the class `bcdc_promise`. We have written an ever growing list methods for this class. You can use these methods directly on a object returned by `bcdc_query_geodata()`. Here are all the methods for the `bcdc_promise` class:
```{r echo=FALSE, results='asis'}
bcdc_methods <- methods(class = "bcdc_promise")
bcdc_methods <- sort(attributes(bcdc_methods)$info[,c("generic"), ])
cat(paste0("- `", bcdc_methods, "`", collapse = "\n"))
```
### BCDC Authentication
If you are an authorized editor of the B.C. Data Catalogue you may want to
access records that are not publicly available (e.g., in DRAFT, waiting to be
published). This can be done by authenticating with the catalogue with an API
key.
_**Important Note:**_ *Your API key is like a password and you must take care to
keep it private. Do not share it, and be careful to not include it in any
scripts or accidentally commit it to GitHub.*
You can log in to the catalogue to obtain your API key, then store it as an
environment variable in your [`.Renviron` file](https://rstats.wtf/r-startup.html#renviron).
The environment variable must be called `BCDC_KEY`, set like this:
```
BCDC_KEY=your-api-key
```
This way, the relevant bcdata functions will read that key and use it to
authorize your calls to the catalogue, allowing you to access additional records
that you are authorized to see if you were logged into the catalogue web
interface. Functions that benefit from this are:
- `bcdc_search()`
- `bcdc_list()`
- `bcdc_get_record()`
- `bcdc_get_data()`
### Getting Help or Reporting an Issue
To report bugs/issues/feature requests, please file an [issue](https://github.com/bcgov/bcdata/issues/).
### How to Contribute
If you would like to contribute to the package, please see our
[CONTRIBUTING](https://github.com/bcgov/bcdata/blob/master/CONTRIBUTING.md) guidelines.
Please note that this project is released with a [Contributor Code of Conduct](https://github.com/bcgov/bcdata/blob/master/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
### Citation
```{r, echo=FALSE, comment=""}
citation("bcdata")
```
### License
Copyright 2018 Province of British Columbia
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and limitations under the License.
---
*This project was created using the [bcgovr](https://github.com/bcgov/bcgovr) package.*