-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathREADME.Rmd
More file actions
94 lines (62 loc) · 4.64 KB
/
README.Rmd
File metadata and controls
94 lines (62 loc) · 4.64 KB
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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# ncdfCF
<!-- badges: start -->
[](https://lifecycle.r-lib.org/articles/stages.html) [](https://cran.r-project.org/package=ncdfCF) [](https://cran.r-project.org/package=ncdfCF) [](https://mit-license.org) [](https://github.com/R-CF/ncdfCF/commits/main)
[](https://github.com/R-CF/ncdfCF/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
The `ncdfCF` package provides an easy to use interface to netCDF resources in R, either in local files or remotely on a THREDDS server. It is built on the `RNetCDF` package which, like package `ncdf4`, provides a basic interface to the `netcdf` library, but which lacks an intuitive user interface. Package `ncdfCF` provides a high-level interface using functions and methods that are familiar to the R user. It reads the structural metadata and also the attributes upon opening the resource. In the process, the `ncdfCF` package also applies CF Metadata Conventions to interpret the data.
## Basic usage
Opening and inspecting the contents of a netCDF resource is very straightforward:
```{r basic_example}
library(ncdfCF)
# Get any netCDF file
fn <- system.file("extdata", "ERA5land_Rwanda_20160101.nc", package = "ncdfCF")
# Open the file, all metadata is read
(ds <- open_ncdf(fn))
```
You can convert a suitable R object into a `CFVariable` instance quite easily. R objects that are supported include arrays, matrices and vectors of type logical, integer, numeric or logical.
If the R object has `dimnames` set, these will be used to create more informed axes. More interestingly, if your array represents some spatial data you can give your `dimnames` appropriate names ("lat", "lon", "latitude", "longitude", case-insensitive) and the corresponding axis will be created (if the coordinate values in the `dimnames` are within the domain of the axis type). For "time" coordinates, these are automatically detected irrespective of the name.
```{r create_dimnames}
# Note the use of named dimnames: these will become the names of the axes
arr <- array(rnorm(120), dim = c(6, 5, 4))
dimnames(arr) <- list(lat = c(45, 44, 43, 42, 41, 40), lon = c(0, 1, 2, 3, 4),
time = c("2025-07-01", "2025-07-02", "2025-07-03", "2025-07-04"))
(obj <- as_CF("a_new_CF_object", arr))
# Axes are of a specific type and have basic attributes set
obj$axes[["lat"]]
obj$axes[["time"]]
```
You can further modify the resulting `CFVariable` by setting other properties, such as attributes or a coordinate reference system. Once the object is complete, you can export or save it.
More detailed operations and options are given on the [package web site](https://r-cf.github.io/ncdfCF/).
## Development plan
Package `ncdfCF` is still being developed. It supports reading of all data objects from netCDF resources in "classic" and "netcdf4" formats; and can write data variables back to a netCDF file. From the CF Metadata Conventions it supports identification of axes, interpretation of the "time" axis, name resolution when using groups, cell boundary information, auxiliary coordinate variables, labels, cell measures, attributes and grid mapping information, among others.
Development plans for the near future focus on supporting the below features:
##### netCDF
* Writing data to an unlimited dimension of a data variable.
##### CF Metadata Conventions
* Cell methods.
* Aggregation.
* Support for discrete sampling geometries.
* Compliance with CMIP5 / CMIP6 requirements.
## Installation
Package `ncdfCF` is still being developed. While extensively tested on multiple well-structured data sets, errors may still occur, particularly in data sets that do not adhere to the CF Metadata Conventions. The API may still change and although care is taken not to make breaking changes, sometimes this is unavoidable.
Installation from CRAN of the latest release:
```
install.packages("ncdfCF")
```
You can install the development version of `ncdfCF` from [GitHub](https://github.com/) with:
```
# install.packages("devtools")
devtools::install_github("R-CF/ncdfCF")
```