nc_data_dl | R Documentation |
Download data records from various collections filtered by various options.
In order to ease the load on the server, note that only three of
collections
/project_ids
, species
, years
, doy
, region
, and
site_type
can be used in any one request. See the vignette for filtering
your data after download for more options:
vignette("filtering_data", package = "naturecounts")
.
nc_data_dl(
collections = NULL,
project_ids = NULL,
species = NULL,
years = NULL,
doy = NULL,
region = NULL,
site_type = NULL,
fields_set = "minimum",
fields = NULL,
username,
info = NULL,
request_id = NULL,
sql_db = NULL,
warn = TRUE,
timeout = 120,
verbose = TRUE
)
collections |
Character vector. The collection codes from which to download data. NULL (default) downloads data from all available collections |
project_ids |
Character/Numeric vector. The |
species |
Numeric vector. Numeric species ids (see details) |
years |
Numeric vector. The start/end years of data to download. Can use NA for either start or end, or a single value to return data from a single year. |
doy |
Character/Numeric vector. The start/end day-of-year to download (1-366 or dates that can be converted to day of year). Can use NA for either start or end |
region |
List. Named list with one of the following options:
|
site_type |
Character vector. The type of site to return (e.g., |
fields_set |
Character. Set of fields/columns to download. See details. |
fields |
Character vector. If |
username |
Character vector. Username for http://naturecounts.ca. If provided, the user will be prompted for a password. If left NULL, only public collections will be returned. |
info |
Character vector. Short description of reason for the download.
E.g., "COSEWIC report", "Impact Assessment Study", "School project", etc.
This kind of information helps NatureCounts.ca justify the utility of the
database. Required unless resuming/re-downloaded with a |
request_id |
Numeric. Specific request id to check or download. |
sql_db |
Character vector. Name and location of SQLite database to either create or add to |
warn |
Logical. Interactive warning if request more than 1,000,000 records to download. |
timeout |
Numeric. Number of seconds before connecting to the server times out. |
verbose |
Logical. Show messages? |
Data frame or connection to SQLite database
All public data is available with a username/password
(sign up
for a free NatureCounts account). However, to access private/semi-public
projects/collections you must request access. See the Access and
request_id
s section for more information.
species
)Numeric species id codes can determined from the functions
search_species()
or search_species_code()
. See also the article on
species codes
for more information.
doy
)The format for day of year (doy
) is fairly flexible and can be a whole
number between 1 and 366 or anything recognized by
lubridate-package
's ymd()
function. However, it must have the order of year, month, day. Note that
year is ignored when converting to day of year, except that it will result
in a 1 day offset for leap years.
region
)Regions are defined by codes reflecting the country, state/province,
subnational (level 2), Important Bird Areas (IBA), and Bird Conservation
Regions (BCR) (see search_region()
for codes). They can also be defined
by providing specific UTM squares to download or a bounding box area which
specifies the min/max longitude and min/max latitude (bbox
). See the
article on regional filters
for more information.
fields_set
and fields
)By default data is downloaded with the minimum
set of fields/columns.
However, for more advanced applications, users may wish to specify which
fields/columns to return. The Bird Monitoring Data Exchange (BMDE) schema
keeps track of variables used to augment observation data. There are
different versions reflecting different collections of variables which can
be specified for download in one of four ways:
fields_set
can be a specific shorthand reflecting a BMDE version:
core
, extended
or minimum
(default). See meta_bmde_versions()
to see
which BMDE version the shorthand refers to.
fields_set
can be default
which uses the default BMDE version for a
particular collection (note that if you download more than one collection,
the field sets will expand to cover all fields/columns in the combined
collections)
fields_set
can be the exact BMDE version. See meta_bmde_versions()
for options.
fields_set
can be custom
and the fields
argument can be a
character vector specifying the exact fields/columns to return. See
meta_bmde_fields()
) for potential fields
values.
Note that in all cases there are a set of fields/columns that are always
returned, no matter what fields_set
is used.
request_id
sAccess to a data collection is either available as "full" or "by request".
Use nc_count(username = "USER", show = "all")
, to see the accessibility of
collections.
"Full" access means that data can be immediately requested directly through
the naturecounts
R package. "By request" means that a request must be
submitted online and
approved before the data can be downloaded through naturecounts
.
This means that there are two types of data requests: ones made through this
naturecounts
R package (API requests) and those made through the online
Web Request Form (Web
requests). Every request (from either method) generates a request_id
which
identifies the filter set and collections requested. Details of all of
requests can be reviewed with the nc_requests()
function.
To download data with "full" access, users can either specify filters, or if
they are repeating a download, can use the request_id
from nc_requests()
.
Otherwise, if the user doesn't have "full" access, they must supply an
approved request_id
to the nc_data_dl()
function (e.g.,
nc_data_dl(request_id = 152000, username = "USER")
). Use nc_requests()
to
see request_id
s, filters, and approval status.
Requests for "full" access to additional collections can be made online through the Web Request Form by checking the "Full access?" box in Step 2 of the form.
# All observations part of the SAMPLE1 and SAMPLE2 collections
sample <- nc_data_dl(collections = c("SAMPLE1", "SAMPLE2"),
username = "sample", info = "nc_example")
# All observations part of project_id 1042 accessible by "testuser"
p1042 <- nc_data_dl(project_ids = 1042, username = "testuser",
info = "nc_example")
# Black-capped Chickadees (BCCH) in SAMPLE2 collection in 2013
search_species("black-capped chickadee") # Find the species_id
bcch <- nc_data_dl(collection = "SAMPLE2", species = 14280, year = 2013,
username = "sample", info = "nc_example")
# All BCCH observations since 2015 accessible to user "sample"
bcch <- nc_data_dl(species = 14280, years = c(2015, NA), username = "sample",
info = "nc_example")
# All BCCH observations from mid-July to late October in all years for user "sample"
bcch <- nc_data_dl(species = 14280, doy = c(200, 300), username = "sample",
info = "nc_example")
# All BCCH observations from a specific bounding box for user "sample"
bcch <- nc_data_dl(species = 14280, username = "sample",
region = list(bbox = c(left = -100, bottom = 45,
right = -80, top = 60)),
info = "nc_example")
# All American Bittern observations from user "sample"
search_species("american bittern")
bittern <- nc_data_dl(species = 2490, username = "sample", info = "nc_example")
# Different fields/columns
bittern <- nc_data_dl(species = 2490, fields_set = "core",
username = "sample", info = "nc_example")
bittern <- nc_data_dl(species = 2490, fields_set = "custom",
fields = c("Locality", "AllSpeciesReported"),
username = "sample", info = "nc_example")
## Not run:
# All collections by request id
# Specific collection by request id
my_data <- nc_data_dl(collections = "ABATLAS1",
request_id = 000000, username = "USER",
info = "MY REASON")
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.