### Install Julia Packages for Benchmarking

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/test/perf/README.md

Installs the BenchmarkTools and NCDatasets packages within a Julia environment. Ensure you are in a Julia shell before running.

```julia
using Pkg
Pkg.add(["BenchmarkTools","NCDatasets"])
```

--------------------------------

### Install Python Packages for Benchmarking

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/test/perf/README.md

Installs the netCDF4 and numpy Python packages using pip. This command should be run in a system shell.

```bash
pip install netCDF4 numpy
```

--------------------------------

### Install R Packages for Benchmarking

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/test/perf/README.md

Installs the microbenchmark and ncdf4 R packages within an R environment. Execute these commands in an R shell.

```r
install.packages("microbenchmark")
install.packages("ncdf4")
```

--------------------------------

### Demonstrate type promotion with NaN

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/other.md

Examples showing how NaN causes promotion to Float64.

```julia
[1, NaN]
# 2-element Vector{Float64}:
#    1.0
#  NaN
```

```julia
[1f0, NaN]
# 2-element Vector{Float64}:
#   1.0
# NaN
```

--------------------------------

### Install Latest Development Version of NCDatasets.jl

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/index.md

Installs the latest development version of NCDatasets.jl from the main branch.

```julia
using Pkg
Pkg.add(PackageSpec(name="NCDatasets", rev="main"))
```

--------------------------------

### Create NetCDF file with variable data in one call

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/README.md

This example shows a concise way to create a NetCDF file, define dimensions, and set variable data using a single `defVar` call.

```julia
using NCDatasets
ds = NCDataset("/tmp/test2.nc","c")
data = [Float32(i+j) for i = 1:100, j = 1:110]
v = defVar(ds,"temperature",data,("lon","lat"))
close(ds)
```

--------------------------------

### List S3 Bucket Objects using AWS CLI

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/tutorials.md

Lists all keys in a specified S3 bucket using the AWS command-line interface. Requires AWS CLI to be installed and configured with appropriate credentials.

```bash
aws s3 ls s3://podaac-ops-cumulus-protected/MODIS_TERRA_L3_SST_THERMAL_DAILY_4KM_NIGHTTIME_V2019.0/
```

--------------------------------

### Test NASA EarthData Configuration with ncdump

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/tutorials.md

Verifies the correct setup of .netrc and .ncrc files for NASA EarthData access by using the ncdump tool to fetch metadata.

```bash
ncdump -h "https://opendap.earthdata.nasa.gov/providers/POCLOUD/collections/GHRSST%20Level%204%20MUR%20Global%20Foundation%20Sea%20Surface%20Temperature%20Analysis%20(v4.1)/granules/20190101090000-JPL-L4_GHRSST-SSTfnd-MUR-GLOB-v02.0-fv04.1"
```

--------------------------------

### Install NCDatasets.jl Package

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/paper/paper.md

Use the Julia package manager to add NCDatasets and its dependencies. This command ensures that compiled binaries for the Unidata netCDF C library are installed.

```julia
using Pkg
Pkg.add("NCDatasets")
```

--------------------------------

### Example NetCDF File Generation Code

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/index.md

This is an example of the Julia code generated by ncgen, showing how to define dimensions and variables with attributes for a NetCDF file.

```julia
ds = NCDataset("filename.nc","c")
# Dimensions

ds.dim["lat"] = 128;
ds.dim["lon"] = 256;
ds.dim["bnds"] = 2;
ds.dim["plev"] = 17;
ds.dim["time"] = 1;

# Declare variables

ncarea = defVar(ds,"area", Float32, ("lon", "lat"))
ncarea.attrib["long_name"] = "Surface area";
ncarea.attrib["units"] = "meter2";
# ...
```

--------------------------------

### Run Benchmark Script with Dropped Caches and Custom HOME

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/test/perf/README.md

Executes the benchmark script with the --drop-caches option, while temporarily setting the HOME environment variable. This is useful when packages are installed in a user's home directory but the script is run as root.

```bash
HOME=/home/my_user_name ./benchmark.sh --drop-caches
```

--------------------------------

### Access OPeNDAP URLs in Julia

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/issues.md

Use this code to access OPeNDAP URLs. Ensure you have the NCDatasets package installed. This example may fail on Windows with older NetCDF versions.

```julia
using NCDatasets
ds = NCDataset("https://thredds.jpl.nasa.gov/thredds/dodsC/ncml_aggregation/OceanTemperature/modis/terra/11um/4km/aggregate__MODIS_TERRA_L3_SST_THERMAL_DAILY_4KM_DAYTIME_V2019.0.ncml#fillmismatch")
```

--------------------------------

### Getting the Dataset from a Variable

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/variables.md

Obtain the NCDataset object from which a CFVariable was derived.

```julia
NCDataset(var::NCDatasets.CFVariable)
```

--------------------------------

### Load a NetCDF file in read-only mode

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/README.md

Opens a NetCDF file in read-only mode and loads a specific variable. The mode 'r' is default and can be omitted. Includes examples for loading subsets and entire variables, as well as ignoring certain metadata.

```julia
# The mode "r" stands for read-only. The mode "r" is the default mode and the parameter can be omitted.
ds = NCDataset("file.nc","r")
v = ds["temperature"]

# load a subset
subdata = v[10:30,30:5:end]

# load all data
data = v[:,:]

# load all data ignoring attributes like scale_factor, add_offset, _FillValue and time units
data2 = v.var[:,:];


# load an attribute
unit = v.attrib["units"]
close(ds)
```

--------------------------------

### Julia NetCDF LoadError Example

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/issues.md

This error indicates a library version mismatch, often occurring with non-official Julia builds or when environment variables like LD_LIBRARY_PATH are set incorrectly. It's recommended to use official Julia builds and ensure environment variables are clean.

```julia
using NCDatasets
ERROR: LoadError: InitError: could not load library "/root/.julia/artifacts/461703969206dd426cc6b4d99f69f6ffab2a9779/lib/libnetcdf.so"
/usr/lib/julia/libcurl.so: version `CURL_4' not found (required by /root/.julia/artifacts/461703969206dd426cc6b4d99f69f6ffab2a9779/lib/libnetcdf.so)
Stacktrace:
 [1] macro expansion
   @ ~/.julia/packages/JLLWrappers/QpMQW/src/products/library_generators.jl:54 [inlined]
 [2] __init__()
   @ NetCDF_jll ~/.julia/packages/NetCDF_jll/BYHmI/src/wrappers/x86_64-linux-gnu.jl:12
 [3] top-level scope
   @ stdin:1
during initialization of module NetCDF_jll
```

--------------------------------

### Attribute Access and Manipulation

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/attributes.md

Demonstrates how to get, set, list, and delete attributes from a NetCDF dataset or variable using the `NCDatasets.Attributes` type, which behaves like a Julia dictionary.

```APIDOC
## Attribute Operations

### Description

Access and manipulate attributes associated with NetCDF datasets or variables. The `attrib` field provides dictionary-like access to these attributes.

### Methods

- `getindex(a::NCDatasets.Attributes, name::AbstractString)`: Retrieves the value of an attribute by its name.
- `setindex!(a::NCDatasets.Attributes, data, name::AbstractString)`: Sets or updates the value of an attribute.
- `keys(a::NCDatasets.Attributes)`: Returns a list of all attribute names.
- `delete!(a::NCDatasets.Attributes, name::AbstractString)`: Removes an attribute by its name.

### Example Usage

```julia
# Assuming 'ds' is an NCDataset object
attribute_value = ds.attrib["some_attribute"]

ds.attrib["new_attribute"] = "some_value"

all_attribute_names = keys(ds.attrib)

delete!(ds.attrib, "old_attribute")
```
```

--------------------------------

### Edit an existing NetCDF file

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/README.md

Opens an existing NetCDF file in append mode ('a') to modify variables or attributes. This example demonstrates adding a global attribute.

```julia
ds = NCDataset("file.nc","a")
ds.attrib["creator"] = "your name"
close(ds);
```

--------------------------------

### Linux NetCDF LoadError Example

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/issues.md

This error, similar to the Windows OPeNDAP issue, can occur on Linux if incompatible libraries are loaded via LD_LIBRARY_PATH or LD_PRELOAD. Verify these environment variables are unset or that loaded libraries are compatible.

```julia
ERROR: LoadError: InitError: could not load library "/home/user/.julia/artifacts/461703969206dd426cc6b4d99f69f6ffab2a9779/lib/libnetcdf.so"
/usr/lib/x86_64-linux-gnu/libcurl.so: version `CURL_4' not found (required by /home/user/.julia/artifacts/461703969206dd426cc6b4d99f69f6ffab2a9779/lib/libnetcdf.so)
```

--------------------------------

### Initialize MPI Parallel NetCDF I/O

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/other.md

Demonstrates initializing an MPI communicator and creating a NetCDF file with collective access enabled for parallel writing.

```julia
using MPI
using NCDatasets

MPI.Init()

mpi_comm = MPI.COMM_WORLD
mpi_comm_size = MPI.Comm_size(mpi_comm)
mpi_rank = MPI.Comm_rank(mpi_comm)

# The file needs to be the same for all processes
filename = "file.nc"

# index based on MPI rank
i = mpi_rank + 1

# create the netCDF file
ds = NCDataset(mpi_comm,filename,"c")

# define the dimensions
defDim(ds,"lon",10)
defDim(ds,"lat",mpi_comm_size)
ncv = defVar(ds,"temp",Int32,("lon","lat"))

# enable colletive access (:independent is the default)
NCDatasets.paraccess(ncv.var,:collective)

ncv[:,i] .= mpi_rank

ncv.attrib["units"] = "degree Celsius"
ds.attrib["comment"] = "MPI test"
close(ds)
```

--------------------------------

### Configure NASA EarthData Credentials with .netrc and .ncrc

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/tutorials.md

Sets up authentication for NASA EarthData by creating .netrc and .ncrc files in the home directory. This method is recommended to avoid sharing credentials directly.

```bash
machine urs.earthdata.nasa.gov
    login YOUR_USERNAME
    password YOUR_PASSWORD
```

```bash
HTTP.NETRC=/home/abarth/.netrc
```

--------------------------------

### Check LD_PRELOAD and LD_LIBRARY_PATH

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/issues.md

If you encounter 'version `CURL_4' not found' errors, check your environment variables. Ensure LD_LIBRARY_PATH and LD_PRELOAD are empty or that loaded libraries are compatible. Use wrapper scripts or rpath if you must set LD_LIBRARY_PATH.

```bash
echo $LD_PRELOAD
```

```bash
echo $LD_LIBRARY_PATH
```

--------------------------------

### Getting Variable Name

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/variables.md

Retrieve the name of a CFVariable.

```julia
name
```

--------------------------------

### Getting Dimension Size

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/variables.md

Retrieve the size of a specific dimension of a CFVariable.

```julia
dimsize
```

--------------------------------

### Getting Variable Dimensions

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/variables.md

Retrieve the names of the dimensions associated with a CFVariable.

```julia
dimnames
```

--------------------------------

### Create and manipulate Julia array views

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/other.md

Demonstrates creating a view of a standard Julia array and verifying the relationship between the view and its parent.

```julia
A = zeros(4,4)
subset = @view A[2:3,2:4]
# or
# subset = view(A,2:3,2:4)

subset[1,1] = 2
A[2,2]
# output
2.0
```

```julia
parent(subset) == A
# true, as both arrays are the same

parentindices(subset)
# output
(2:3, 2:4)
```

--------------------------------

### Run Benchmark Script

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/test/perf/README.md

Executes the main benchmark script. This command is run in a system shell and will output benchmark statistics in a markdown table.

```bash
./benchmark.sh
```

--------------------------------

### Create NetCDF File with Dimensions and Variables

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/index.md

Create a new NetCDF file, define dimensions, a global attribute, and a variable with its attributes. Ensure the file is closed after writing.

```julia
using NCDatasets
# This creates a new NetCDF file /tmp/test.nc.
# The mode "c" stands for creating a new file (clobber)
ds = NCDataset("/tmp/test.nc","c")

# Define the dimension "lon" and "lat" with the size 100 and 110 resp.
defDim(ds,"lon",100)
defDim(ds,"lat",110)

# Define a global attribute
ds.attrib["title"] = "this is a test file"

# Define the variables temperature
v = defVar(ds,"temperature",Float32, ("lon","lat"))

# Generate some example data
data = [Float32(i+j) for i = 1:100, j = 1:110]

# write a single column
v[:,1] = data[:,1]

# write a the complete data set
v[:,:] = data

# write attributes
v.attrib["units"] = "degree Celsius"
v.attrib["comments"] = "this is a string attribute with Unicode Ω ∈ ∑ ∫ f(x) dx"

close(ds)
```

--------------------------------

### Accessing and Loading Variables

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/variables.md

Demonstrates how to access a variable from a dataset and load its data into memory, either fully or partially. It also shows how to handle scalar variables and retrieve raw data ignoring attributes.

```APIDOC
## Accessing and Loading Variables

Variables are the core data containers within a NetCDF dataset. You can access them using dictionary-like syntax on a `NCDataset` object.

### Example: Accessing a Float32 variable
```julia
using NCDatasets
ds = NCDataset("test.nc")
ncvar_cf = ds["variable"]
```

Once accessed, `ncvar_cf` is a `CFVariable` object. Data is not loaded into memory until explicitly requested. You can query metadata like `size`, `ndims`, and `length` directly.

### Loading Variable Data

To load the entire variable into a Julia array:

```julia
# Load entire variable
data = Array(ncvar_cf)
# or using pipe operator
data = ncvar_cf |> Array
# for 2D variables
data = ncvar_cf[:,:]
```

Note: `ncvar_cf[:]` flattens the array and is only equivalent to the above for 1D variables (vectors).

### Loading Sub-parts of Variables

You can load specific portions of a variable by indexing its dimensions:

```julia
# Load a slice of the variable
subset_data = ncvar_cf[1:5, 10:20]
```

### Loading Scalar Variables

Scalar variables are loaded using empty indexing `[]`:

```julia
# Create a NetCDF with a scalar variable
NCDataset("test_scalar.nc", "c") do ds
    defVar(ds, "scalar", 42, ())
end

# Load the scalar value
ds = NCDataset("test_scalar.nc")
value = ds["scalar"][] # value will be 42
```

### Loading Raw Data (Ignoring Attributes)

To load the variable's data while ignoring attributes like `scale_factor`, `add_offset`, `_FillValue`, and time units, use the `.var` property or the `variable()` function:

```julia
# Example with time data
using Dates
data_time = [DateTime(2000,1,1), DateTime(2000,1,2)]
NCDataset("test_file.nc", "c") do ds
    defVar(ds, "time", data_time, ("time",), attrib = Dict("units" => "days since 2000-01-01"))
end

ds = NCDataset("test_file.nc")

# Get raw variable data
ncvar_raw = ds["time"].var
# or
ncvar_raw = variable(ds, "time")

# Load raw data (e.g., as days since epoch)
raw_data = ncvar_raw[:]
# raw_data will be [0., 1.] in this example
```

The `ncvar_raw` object can be indexed similarly to `ncvar_cf`.
```

--------------------------------

### Get Variable by Attribute Value

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/index.md

Retrieve variables from a dataset based on attribute values. Useful when variable names are not standardized. The first element of the returned list can be directly accessed for data.

```julia
nclon = varbyattrib(ds, standard_name = "longitude");
```

```julia
data = varbyattrib(ds, standard_name = "longitude")[1][:]
```

--------------------------------

### Run Benchmark Script with Cache Dropping

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/test/perf/README.md

Executes the benchmark script with the --drop-caches option enabled. This requires superuser privileges and is specific to Linux systems to ensure disk I/O is included in timing.

```bash
./benchmark.sh --drop-caches
```

--------------------------------

### Create a NetCDF file with dimensions, variables, and attributes

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/README.md

This snippet demonstrates creating a new NetCDF file, defining dimensions, global attributes, and variables with their own attributes. It shows how to write data to a variable, both partially and completely.

```julia
using NCDatasets
using DataStructures: OrderedDict
# This creates a new NetCDF file called file.nc.
# The mode "c" stands for creating a new file (clobber)
ds = NCDataset("file.nc","c")

# Define the dimension "lon" and "lat" with the size 100 and 110 resp.
defDim(ds,"lon",100)
defDim(ds,"lat",110)

# Define a global attribute
ds.attrib["title"] = "this is a test file"

# Define the variables temperature with the attribute units
v = defVar(ds,"temperature",Float32,("lon","lat"), attrib = OrderedDict(
    "units" => "degree Celsius",
    "scale_factor" => 10,
))

# add additional attributes
v.attrib["comments"] = "this is a string attribute with Unicode Ω ∈ ∑ ∫ f(x) dx"

# Generate some example data
data = [Float32(i+j) for i = 1:100, j = 1:110];

# write a single column
v[:,1] = data[:,1];

# write a the complete data set
v[:,:] = data;

close(ds)
```

--------------------------------

### Download GHRSST Data from NASA EarthData

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/tutorials.md

Downloads GHRSST Level 4 MUR Global Foundation Sea Surface Temperature Analysis data via OPeNDAP for a specified bounding box and time. Requires prior configuration of .netrc and .ncrc files.

```julia
using NCDatasets, PyPlot, Dates, Statistics

url = "https://opendap.earthdata.nasa.gov/providers/POCLOUD/collections/GHRSST%20Level%204%20MUR%20Global%20Foundation%20Sea%20Surface%20Temperature%20Analysis%20(v4.1)/granules/20190101090000-JPL-L4_GHRSST-SSTfnd-MUR-GLOB-v02.0-fv04.1"

ds = NCDataset(url)

# range of longitude
lonr = (-6, 37.0)

```

--------------------------------

### Create and Access NetCDF Groups

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/dataset.md

Demonstrates how to create a new group within a NetCDF dataset and define a variable inside that group. Also shows how to access a variable within a specific group.

```julia
ds = NCDataset("results.nc", "c")
ds_forecast = defGroup(ds,"forecast")
defVar(ds_forecast,"temperature",randn(10,11,12),("lon","lat","time"))

forecast_temp = ds.group["forecast"]["temperature"][:,:,:]
close(ds)
```

--------------------------------

### Download and Load NetCDF from S3

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/tutorials.md

Downloads the first object from an S3 list and loads it as a NetCDF dataset from memory. Requires NCDatasets version 0.12.5 or later.

```julia
# download the first object
data = S3.get_object("podaac-ops-cumulus-protected",resp["Contents"][1]["Key"]);

# load the NetCDF dataset
ds = NCDataset("temp-memory","r", memory = data)
```

--------------------------------

### Create NetCDF File with Do Block and OrderedDict

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/index.md

An alternative method to create a NetCDF file using a do block and OrderedDict for attributes, implicitly creating dimensions.

```julia
using NCDatasets
using DataStructures
data = [Float32(i+j) for i = 1:100, j = 1:110]

NCDataset("/tmp/test2.nc","c",attrib = OrderedDict("title" => "this is a test file")) do ds
    # Define the variable temperature. The dimension "lon" and "lat" with the
    # size 100 and 110 resp are implicitly created
    defVar(ds,"temperature",data, ("lon","lat"), attrib = OrderedDict(
           "units" => "degree Celsius",
           "comments" => "this is a string attribute with Unicode Ω ∈ ∑ ∫ f(x) dx"
    ))
end
```

--------------------------------

### Generate Benchmark Data

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/test/perf/README.md

Executes the julia script to prepare the necessary data file 'filename_fv.nc' for benchmarking. This command is run in a system shell.

```bash
julia generate_data.jl
```

--------------------------------

### Type Promotion Issues with Attributes

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/attributes.md

Highlights a potential issue with type promotion when defining attributes using arrays of pairs, specifically concerning `_FillValue`, and provides solutions.

```APIDOC
## Handling Type Promotion in Attributes

### Description

When defining attributes using an array of pairs, Julia's type promotion can lead to mismatches, particularly with `_FillValue`. This section explains the problem and offers solutions.

### Problem Scenario

Defining attributes with an array of pairs can cause `_FillValue` to be promoted to a different type (e.g., `Float64`), which conflicts with the NetCDF data type, resulting in an error.

```julia
# Example of problematic attribute definition
# ncv1 = defVar(ds, "v1", UInt8, ("longitude", "latitude", "time"), attrib = [
#     "add_offset" => -1.0,
#     "scale_factor" => 5.0,
#     "_FillValue" => UInt8(255),
# ])
# This can lead to: "NetCDF: Not a valid data type or _FillValue type mismatch"
```

### Solutions

1.  **Use `Dict`**: Using a Julia `Dict` for attributes avoids the type promotion issue observed with arrays of pairs.
    ```julia
    ncv1 = defVar(ds, "v1", UInt8, ("longitude", "latitude", "time"), attrib = Dict(
        "add_offset" => -1.0,
        "scale_factor" => 5.0,
        "_FillValue" => UInt8(255),
    ))
    ```
    *Note: `Dict` does not preserve attribute order.* For ordered attributes, consider `OrderedDict` from the `DataStructures` package.

2.  **Use `fillvalue` parameter**: Directly use the `fillvalue` parameter in `defVar` for the fill value, and define other attributes separately.
    ```julia
    ncv1 = defVar(ds, "v1", UInt8, ("longitude", "latitude", "time"), fillvalue = UInt8(255), attrib = [
        "add_offset" => -1.0,
        "scale_factor" => 5.0,
    ])
    ```
```

--------------------------------

### Creating a Variable

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/variables.md

Explains how to define and create new variables within a NetCDF dataset using the `defVar` function.

```APIDOC
## Creating a Variable

New variables can be defined and added to a NetCDF dataset using the `defVar` function.

### `defVar`

```@docs
defVar
```
```

--------------------------------

### Iterate Over Dataset Variables

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/dataset.md

Shows how to iterate through all variables in a NetCDF dataset and display their names and sizes.

```julia
for (varname,var) in ds
    # all variables
    @show (varname,size(var))
end
```

--------------------------------

### Configure Custom NetCDF Library Path

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/issues.md

To use a specific NetCDF library, override the default artifact path using the `Preferences` package. Ensure the custom library's dependencies are compatible with Julia's runtime environment.

```julia
# install these packages if necessary
using Preferences, NetCDF_jll

set_preferences!(NetCDF_jll, "libnetcdf_path" => "/path/to/libnetcdf.so.xyz")

```

--------------------------------

### Loading Attributes as a Dictionary

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/attributes.md

Shows how to load all attributes of a NetCDF dataset into a standard Julia `Dict`.

```APIDOC
## Load Attributes as Dictionary

### Description

Convert all attributes of a NetCDF dataset into a Julia `Dict` for easier manipulation or inspection.

### Method

Pass the `attrib` field of an `NCDataset` object to the `Dict` constructor.

### Example Usage

```julia
using NCDatasets

# Download a sample NetCDF file
ncfile = download("https://www.unidata.ucar.edu/software/netcdf/examples/sresa1b_ncar_ccsm3-example.nc");
ds = NCDataset(ncfile);

# Load attributes into a dictionary
attributes_as_dictionary = Dict(ds.attrib)

# Verify the type
typeof(attributes_as_dictionary)
# Expected output: Dict{String, Any}
```
```

--------------------------------

### Load and Inspect NetCDF File

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/index.md

Open a NetCDF file in read-only mode and inspect its structure. This includes checking for variable existence, listing all variable names, iterating over variables, querying variable sizes, and handling global attributes.

```julia
# Open a file as read-only
ds = NCDataset("/tmp/test.nc","r")
```

```julia
# check if a file has a variable with a given name
if haskey(ds,"temperature")
    println("The file has a variable 'temperature'")
end
```

```julia
# get a list of all variable names
@show keys(ds)
```

```julia
# iterate over all variables
for (varname,var) in ds
    @show (varname,size(var))
end
```

```julia
# query size of a variable (without loading it)
v = ds["temperature"]
@show size(v)
```

```julia
# similar for global and variable attributes

if haskey(ds.attrib,"title")
    println("The file has the global attribute 'title'")
end
```

```julia
# get an list of all attribute names
@show keys(ds.attrib)
```

```julia
# iterate over all attributes
for (attname,attval) in ds.attrib
    @show (attname,attval)
end
```

```julia
# get the attribute "units" of the variable v
# but return the default value (here "adimensional")
# if the attribute does not exists

units = get(v,"units","adimensional")
close(ds)
```

--------------------------------

### Windows OPeNDAP workaround

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/issues.md

On Windows, NetCDF 4.7.4 may fail with an 'ocpanic' error when accessing OPeNDAP URLs. Create a `.dodsrc` file in your working directory with the content below, replacing USERNAME with your actual username. The specified directory must exist and be writable.

```text
HTTP.COOKIEJAR=C:\Users\USERNAME\AppData\Local\Temp\
```

--------------------------------

### Check NetCDF Library Dependencies on Linux

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/issues.md

When using a custom NetCDF library, verify its dependencies on Linux using the `ldd` command to ensure compatibility with Julia's libraries.

```bash
ldd /path/to/libnetcdf.so.xyz

```

--------------------------------

### Slice an entire NCDataset

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/other.md

Shows how to create a view of an entire dataset based on dimension ranges.

```julia
ds_subset = view(ds, lon = 2:3, lat = 2:4)
# or
# ds_subset = @view ds[lon = 2:3, lat = 2:4]
ds_subset.dim["lon"]

# output
2
```

--------------------------------

### NCDataset(comm::MPI.Comm, filename::AbstractString, mode::AbstractString)

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/other.md

Creates or opens a NetCDF dataset using an MPI communicator for parallel I/O operations.

```APIDOC
## NCDataset(comm::MPI.Comm, filename::AbstractString, mode::AbstractString)

### Description
Creates or opens a NetCDF dataset with MPI parallel I/O support. All metadata operations must be performed collectively across the MPI communicator.

### Parameters
- **comm** (MPI.Comm) - Required - The MPI communicator to use for parallel access.
- **filename** (AbstractString) - Required - The path to the NetCDF file.
- **mode** (AbstractString) - Required - The file access mode (e.g., "c" for create).
```

--------------------------------

### Save a sliced dataset to a file

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/other.md

Demonstrates writing a sliced dataset view to a new NetCDF file.

```julia
write("slice.nc",ds_subset)
```

--------------------------------

### Open a NetCDF file for exploration

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/README.md

Opens a NetCDF file to explore its contents without loading all data into memory. This is useful for inspecting variables and attributes before full data loading.

```julia
using NCDatasets
ds = NCDataset("file.nc")
```

--------------------------------

### Set AWS Environment Variables and List S3 Objects

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/tutorials.md

Sets AWS environment variables using fetched credentials and lists objects in a specified S3 bucket. This is a prerequisite for downloading data from S3.

```julia
# add your credentials here (or get it programmatically from environment variables or a file)
username = "..."
password = "..."

cred = earthdata_s3credentials(username,password)
@info "Token expires: $(cred.expiration)"


ENV["AWS_ACCESS_KEY_ID"] = cred.accessKeyId;
ENV["AWS_SECRET_ACCESS_KEY"] = cred.secretAccessKey;
ENV["AWS_SESSION_TOKEN"] = cred.sessionToken;

c = AWS.global_aws_config();

resp = S3.list_objects("podaac-ops-cumulus-protected",
     Dict("prefix" => "MODIS_TERRA_L3_SST_MID-IR_DAILY_4KM_NIGHTTIME_V2019.0/",
          "delimiter" => '/'))
```

--------------------------------

### Iterate Over Dataset Groups

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/dataset.md

Illustrates how to iterate through all groups within a NetCDF dataset and display their names and group objects.

```julia
for (groupname,group) in ds.groups
    # all groups
    @show (groupname,group)
end
```

--------------------------------

### In-place Loading with `NCDatasets.load!`

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/performance.md

Utilize the in-place `NCDatasets.load!` function for type-stable code and memory buffer reuse. This function requires prefixing with the module name as it is unexported.

```julia
ds = NCDataset("file.nc")

temp = zeros(Float32,10,20)
NCDatasets.load!(variable(ds,"temp"),temp,:,:)

```

--------------------------------

### Load All Data from NetCDF Variable

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/index.md

Loads all data from a NetCDF variable.

```julia
# load all data
data = v[:,:]
```

--------------------------------

### Download Sea Surface Temperature from Copernicus Marine

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/tutorials.md

Downloads sea surface temperature data from Copernicus Marine Service. Requires username and password, which can be embedded in the URL using URIs.escapeuri for special characters.

```julia
using NCDatasets, PyPlot, Statistics, URIs

username = "your_username"
password = "your_password"

url = "https://nrt.cmems-du.eu/thredds/dodsC/SST_MED_SST_L4_NRT_OBSERVATIONS_010_004_a_V2"

# add username and password to url
# username or password can contain special characters
username_escaped = URIs.escapeuri(username)
password_escaped = URIs.escapeuri(password)
url2 = string(URI(URI(url),userinfo = string(username_escaped,":",password_escaped)))

ds = NCDataset(url2)

ncvar = ds["analysed_sst"];
SST = ncvar[:,:,1]
lon = ds["lon"][:]
lat = ds["lat"][:]
SST_time = ds["time"][1]

clf()
pcolormesh(lon,lat,nomissing(SST,NaN)')
cbar = colorbar(orientation="horizontal")
cbar.set_label(ncvar.attrib["units"])
gca().set_aspect(1/cosd(mean(lat)))

title("$(ncvar.attrib["long_name"]) $SST_time")
```

--------------------------------

### Iterate Over Dataset Attributes

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/dataset.md

Demonstrates iterating over all attributes of a NetCDF dataset and displaying their names and values.

```julia
for (attribname,attrib) in ds.attrib
    # all attributes
    @show (attribname,attrib)
end
```

--------------------------------

### Common Methods

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/dataset.md

Provides methods for iterating over datasets, attributes, dimensions, and groups.

```APIDOC
## Common methods

### Description
Allows iteration over datasets, attributes, dimensions, and groups.

### Iteration
- **Dataset Iteration**: Iterate over `ds` to access variables.
- **Attribute Iteration**: Iterate over `ds.attrib` to access attributes.
- **Group Iteration**: Iterate over `ds.groups` to access sub-groups.
```

--------------------------------

### Load NetCDF File and Variable

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/index.md

Opens a NetCDF file in read-only mode and accesses a specific variable. The mode 'r' is default and can be omitted.

```julia
# The mode "r" stands for read-only. The mode "r" is the default mode and the parameter can be omitted.
ds = NCDataset("/tmp/test.nc","r")
v = ds["temperature"]
```

--------------------------------

### Storage Parameters of a Variable

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/variables.md

Details on how to access and potentially set storage-related parameters for variables, such as chunking and compression.

```APIDOC
## Storage Parameters of a Variable

Information regarding the storage characteristics of a variable can be accessed:

- `chunking(v::NCDatasets.CFVariable)`: Returns the chunking configuration of the variable.
- `deflate(v::NCDatasets.CFVariable)`: Returns the deflation level (compression level) of the variable.
- `checksum(v::NCDatasets.CFVariable)`: Returns the checksum information for the variable.
```

--------------------------------

### Defining Variables with FillValue Parameter

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/attributes.md

Shows the preferred method for defining a variable with a fill value using the dedicated `fillvalue` parameter in `defVar`. This approach is cleaner and avoids potential attribute-related issues.

```julia
ncv1 = defVar(ds,"v1", UInt8, ("longitude", "latitude", "time"), fillvalue = UInt8(255), attrib = [
    "add_offset"                => -1.0,
    "scale_factor"              => 5.0,
])
```

--------------------------------

### Select data using NCDatasets

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/other.md

Use the @select macro for data selection.

```julia
NCDatasets.@select
```

--------------------------------

### Setting Variable Deflate Compression

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/variables.md

Apply deflate compression to a variable to reduce file size, with options for compression level.

```julia
deflate
```

--------------------------------

### Load data using a do block for automatic closing

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/README.md

Ensures a NetCDF file is automatically closed after reading data by using a do block. This is the recommended approach for managing file resources.

```julia
data = NCDataset(filename,"r") do ds
    ds["temperature"][:,:]
end # ds is closed
```

--------------------------------

### Check NCDatasets version

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/README.md

Prints the version information for Julia and the NCDatasets package, useful for debugging and reporting issues.

```julia
versioninfo()
using Pkg
Pkg.installed()["NCDatasets"]
```

--------------------------------

### Check integer precision limits

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/other.md

Verify the smallest integers that cannot be represented as floating point numbers.

```julia
Float32(16_777_217) == 16_777_217 # false
Float64(9_007_199_254_740_993) == 9_007_199_254_740_993 # false
```

--------------------------------

### Iterating Over Dimensions

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/dimensions.md

Demonstrates how to iterate through all dimensions of a NetCDF dataset.

```APIDOC
## Iterating Over Dimensions

### Description
Iterate over all dimensions in a NetCDF dataset.

### Example
```julia
for (dimname, dim) in ds.dim
    # Process each dimension
    @show (dimname, dim)
end
```
```

--------------------------------

### Iterate Over Dataset Dimensions

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/dimensions.md

Demonstrates how to iterate through all dimensions of a NetCDF dataset. This is useful for inspecting or processing each dimension.

```julia
for (dimname,dim) in ds.dim
    # all dimensions
    @show (dimname,dim)
end
```

--------------------------------

### Slice NCDatasets variables as views

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/other.md

Shows how to create a view of an NCDataset variable, modify it, and access its attributes.

```julia
using NCDatasets, DataStructures
ds = NCDataset(tempname(),"c")

nclon = defVar(ds,"lon", 1:10, ("lon",))
nclat = defVar(ds,"lat", 1:11, ("lat",))
ncvar = defVar(ds,"bat", zeros(10,11), ("lon", "lat"), attrib = OrderedDict(
    "standard_name"             => "height",
))

ncvar_subset = @view ncvar[2:4,2:3]
# or
# ncvar_subset = view(ncvar,2:4,2:3)

ncvar_subset[1,1] = 2
# ncvar[2,2] is now 2

ncvar_subset.attrib["standard_name"]

# output
"height"
```

--------------------------------

### Defining Variables with Attributes (Dict)

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/attributes.md

Demonstrates defining a NetCDF variable with attributes using a Julia `Dict`. This avoids the type promotion issues seen with arrays of pairs, but `Dict` does not preserve attribute order.

```julia
ncv1 = defVar(ds,"v1", UInt8, ("longitude", "latitude", "time"), attrib = Dict(
    "add_offset"                => -1.0,
    "scale_factor"              => 5.0,
    "_FillValue"                => UInt8(255),
))
```

--------------------------------

### Defining Variables with Attributes (Array of Pairs)

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/attributes.md

Shows how to define a NetCDF variable with attributes provided as an array of key-value pairs. Be cautious of type promotion issues, especially with `_FillValue`, which must match the variable's data type.

```julia
ncv1 = defVar(ds,"v1", UInt8, ("longitude", "latitude", "time"), attrib = [
    "add_offset"                => -1.0,
    "scale_factor"              => 5.0,
    "_FillValue"                => UInt8(255),
])
```

--------------------------------

### Convenience Functions for Variables

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/variables.md

A list of convenient functions provided by NCDatasets.jl for inspecting and manipulating variables.

```APIDOC
## Convenience Functions for Variables

The following functions offer convenient ways to interact with `CFVariable` objects:

- `Base.size(v::NCDatasets.CFVariable)`: Returns the dimensions of the variable.
- `dimnames(v::NCDatasets.CFVariable)`: Returns the names of the dimensions of the variable.
- `dimsize(v::NCDatasets.CFVariable, dimname::String)`: Returns the size of a specific dimension by its name.
- `name(v::NCDatasets.CFVariable)`: Returns the name of the variable.
- `renameVar(ds::NCDatasets.NCDataset, oldname::String, newname::String)`: Renames a variable in the dataset.
- `NCDataset(var::NCDatasets.CFVariable)`: Returns the `NCDataset` object to which the variable belongs.
- `nomissing(v::NCDatasets.CFVariable)`: Returns a view of the variable with missing values filtered out (if applicable).
- `fillvalue(v::NCDatasets.CFVariable)`: Returns the fill value associated with the variable.
- `loadragged(v::NCDatasets.CFVariable)`: Loads ragged array data associated with the variable.
- `NCDatasets.load!(dest_array::AbstractArray, v::NCDatasets.CFVariable)`: Loads the data from the variable `v` into the pre-allocated `dest_array`.
```

--------------------------------

### Run NCDatasets test suite

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/README.md

Executes the test suite for the NCDatasets package. This is helpful to verify the package's integrity and functionality.

```julia
using Pkg
Pkg.test("NCDatasets")
```

--------------------------------

### Accessing NetCDF Attributes as a Dictionary

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/attributes.md

Demonstrates how to load all attributes of a NetCDF dataset into a Julia `Dict`. This is useful for inspecting or processing all metadata at once.

```julia
using NCDatasets
ncfile = download("https://www.unidata.ucar.edu/software/netcdf/examples/sresa1b_ncar_ccsm3-example.nc");
ds = NCDataset(ncfile);
attributes_as_dictionary = Dict(ds.attrib)
typeof(attributes_as_dictionary)
# returns Dict{String,Any}
```

--------------------------------

### Select and Plot SST Data

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/tutorials.md

Selects a subset of analyzed Sea Surface Temperature (SST) data based on latitude and longitude ranges, then plots it. Requires NCDatasets and plotting libraries.

```julia
latr = (29, 45.875)

ds_subset = NCDatasets.@select(
    ds["analysed_sst"],
    $lonr[1] <= lon <= $lonr[2] && $latr[1] <= lat <= $latr[2])

ncvar = ds_subset["analysed_sst"]
SST = ncvar[:,:,1]
lon = ds_subset["lon"][:]
lat = ds_subset["lat"][:]
time = ds_subset["time"][1]


clf()
pcolormesh(lon,lat,nomissing(SST,NaN)");
gca().set_aspect(1/cosd(mean(lat)))

cbar = colorbar(orientation="horizontal")
cbar.set_label(ncvar.attrib["units"])

plt.title("$(ncvar.attrib["long_name"]) $time")
```

--------------------------------

### Load NetCDF Data Subset

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/index.md

Load a subset of data from a NetCDF file. Ensure files are closed after use to avoid resource limits.

```julia
unit = v.attrib["units"]
close(ds)
```

```julia
subdata = NCDataset("/tmp/test.nc")["temperature"][10:30,30:5:end]
```

--------------------------------

### Use NaN32 to avoid promotion

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/other.md

Use NaN32 to maintain Float32 precision when masking.

```julia
using NCDatasets
data32 = [1f0 2f0 3f0; missing 20f0 30f0]
data64 = [1. 2. 3.; missing 20. 30.]
ds = NCDataset("example_float32_64.nc","c")
defVar(ds,"var32",data32,("lon","lat"),fillvalue = 9999f0)
defVar(ds,"var64",data64,("lon","lat"),fillvalue = 9999.)
close(ds)

ds = NCDataset("example_float32_64.nc","r", maskingvalue = NaN32)
ds["var32"][:,:]
# 2×3 Matrix{Float32}:
#   1.0   2.0   3.0
# NaN    20.0  30.0

ds["var64"][:,:]
# 2×3 Matrix{Float64}:
#   1.0   2.0   3.0
# NaN    20.0  30.0
```

--------------------------------

### Define a NetCDF variable with a fill value

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/other.md

Create a NetCDF file and define a variable with a specific fill value.

```julia
using NCDatasets
data = [1. 2. 3.; missing 20. 30.]
ds = NCDataset("example.nc","c")
defVar(ds,"var",data,("lon","lat"),fillvalue = 9999.)
```

--------------------------------

### NCDatasets.@select

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/other.md

A macro for performing data selection based on values within a NetCDF dataset.

```APIDOC
## NCDatasets.@select

### Description
Macro used for selecting data from a NetCDF dataset based on specific value criteria.

### Usage
`@select(ds, condition)`
```

--------------------------------

### Loading Scalar Variables

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/variables.md

Create and load a scalar variable from a NetCDF file. Scalar variables do not have dimensions.

```julia
using NCDatasets
NCDataset("test_scalar.nc","c") do ds
    # the list of dimension names is simple `()` as a scalar does not have dimensions
    defVar(ds,"scalar",42,())
end

ds = NCDataset("test_scalar.nc")
value = ds["scalar"][] # 42
```

--------------------------------

### Type Promotion Issue with Attributes

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/attributes.md

Illustrates a common pitfall where Julia's type promotion can cause mismatches for attribute values like `_FillValue`, leading to errors. The output shows how `UInt8(255)` is promoted to `Float64` when using an array of pairs.

```julia
[
           "add_offset"                => -1.0,
           "scale_factor"              => 5.0,
           "_FillValue"                => UInt8(255),
]
# returns
# 3-element Array{Pair{String,Float64},1}:
#   "add_offset" => -1.0
# "scale_factor" => 5.0
#   "_FillValue" => 255.0

# Note the type of the second element of the `Pair`.
```

--------------------------------

### Generate Julia Code from NetCDF Metadata with ncgen

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/index.md

Use the ncgen utility function to generate Julia code that replicates the metadata of an existing NetCDF file.

```julia
using Downloads: download
# download an example file
ncfile = download("https://www.unidata.ucar.edu/software/netcdf/examples/sresa1b_ncar_ccsm3-example.nc")
# generate Julia code
ncgen(ncfile)
```

--------------------------------

### Loading Data into an Existing Array

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/variables.md

Efficiently load NetCDF variable data directly into a pre-allocated Julia array.

```julia
NCDatasets.load!
```

--------------------------------

### NCDatasets.paraccess

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/other.md

Configures the parallel access mode for a NetCDF variable.

```APIDOC
## NCDatasets.paraccess(var, mode::Symbol)

### Description
Sets the parallel access mode for a specific NetCDF variable. Supported modes are :independent (default) and :collective.

### Parameters
- **var** (Variable) - Required - The NetCDF variable to configure.
- **mode** (Symbol) - Required - The access mode, either :independent or :collective.
```

--------------------------------

### Coordinate Variables and Cell Boundaries

Source: https://github.com/juliageo/ncdatasets.jl/blob/main/docs/src/variables.md

Describes how to access coordinate variables and associated cell boundary data.

```APIDOC
## Coordinate Variables and Cell Boundaries

NCDatasets.jl provides functions to access coordinate variables and their related cell boundary data:

- `coord(v::NCDatasets.CFVariable)`: Returns the coordinate variable associated with the given variable.
- `bounds(v::NCDatasets.CFVariable)`: Returns the cell boundaries associated with the variable.
```