Package 'nilsier'

nilsier: Design-Based Estimators for NILS

Description

Estimators and variance estimators tailored to the NILS hierarchical design (Adler et al. 2020, https://res.slu.se/id/publ/105630; Grafström et al. 2023, https://res.slu.se/id/publ/128235). The National Inventories of Landscapes in Sweden (NILS) is a long-term national monitoring program that collects, analyses and presents data on Swedish nature, covering both common and rare habitats https://www.slu.se/om-slu/organisation/institutioner/skoglig-resurshushallning/miljoanalys/nils/.

Details

Estimates are produced per category and tract, and subsequently combined. Variance estimation takes into account some of the dependencies that exists between categories.

If the PSU collections were drawn using some spatially balanced design, the variance estimator assuming OSU sampling of PSUs will overestimate the variance. An alternative variance, such as the local mean variance estimator, can be used in order to reduce this overestimation somewhat (Grafström & Schelin, 2014).

Conceptual overview of NILS hierarchical design

The primary sampling unit is a tract, and in the first step, a large number of tracts are selected (PSU1). From the collection PSU1, a smaller sample of tracts is drawn to form PSU2, and this process continues to subsequent levels.

Each tract consists of a grid of 14 x 14 circular plots, each with a 10 m radius.

Amongst PSU1, some categories (strata) are identified. The plots in the tracts are assigned to one of these categories or marked as unclassified (considered uninteresting at that stage). Within each tract, a sample of plots is then drawn from each category.

At lower PSU levels, additional categories are introduced, and previously unclassified plots are assigned to one of these new categories.

For further details on the design (in Swedish), see e.g. Adler et al. (2020) and Grafström et al. (2023).

Author(s)

Wilmer Prentius [email protected].

References

Adler, S., Christensen, P., Gardfjell, H., Grafström, A., Hagner, Å., Hedenås, H., & Ranlund, Å. (2020). Ny design för riktade naturtypsinventeringar inom NILS och THUF. Arbetsrapport 513. Institutionen för skoglig resurshushållning, Sveriges lantbruksuniversitet, SLU.

Grafström, A., Randlund, Å., & Adler, S. (2023). Skattningar baserade på hierarkiska urval. Arbetsrapport 558. Institutionen för skoglig resurshushållning, Sveriges lantbruksuniversitet, SLU.

Grafström, A., & Schelin, L. (2014). How to select representative samples. Scandinavian Journal of Statistics, 41(2), 277-290.

See Also

Useful links:

• https://github.com/envisim/nilsier/

---

Estimates of a NILS estimate

Description

Accesses the estimate and variance estimate of a NilsEstimate object.

Usage

## S3 method for class 'NilsEstimate'
coef(object, ...)

Arguments

object	A NilsEstimate object.
...	Additional arguments (currently unused).

Value

A named vector with the following elements:

estimate

Estimated total of the target variable.

variance

Estimated variance of the total estimator.

Examples

obj = NilsEstimate(plots, tracts, psus, category_psu_map);
coef(obj);

---

Filter NILS estimates

Description

Filters a NilsEstimate object by PSU level or category.

Usage

efilter(obj, ...)

## S3 method for class 'NilsEstimate'
efilter(obj, psus = NULL, categories = NULL, ...)

Arguments

obj	A NilsEstimate object.
...	Additional arguments (currently unused)
psus	An optional vector of PSU IDs to keep.
categories	An optional vector of the category IDs to keep.

Value

a filtered NilsEstimate object.

Examples

obj = NilsEstimate(plots, tracts, psus, category_psu_map);

# Keep only category with ID 1
efilter(obj, categories = 1)

# Keep PSU 5
efilter(obj, psus = 5)

---

Estimate totals using the NILS hierarchical design

Description

Estimates the total of some variable surveyed under the NILS hierarchical sampling framework.

Usage

NilsEstimate(
  plot_data,
  tract_data,
  psus,
  category_psu_map,
  area = 46519242.1175867,
  tract_area = 196 * 100 * pi
)

NilsEstimateBalanced(
  plot_data,
  tract_data,
  auxiliaries,
  psus,
  category_psu_map,
  area = 46519242.1175867,
  tract_area = 196 * 100 * pi,
  size_of_neighbourhood = NULL
)

Arguments

plot_data	A data frame with information about observations at the plot level. Must contain (in order): The tract ID (integer) of the parent tract. The category ID (integer) recorded for the plot. The design weight (double) for the plot, conditional on the tract. The observed value of the target variable (double).
tract_data	A matrix with information about all sampled tracts, including those where no relevant categories were found. Must contain (in order): The tract ID (integer) of each sampled tract. The PSU collection ID (integer) of the smallest PSU that contains the tract.
psus	An ordered vector of PSU levels, from largest to smallest.
category_psu_map	A matrix describing the categories used in the design. Must contain (in order): The category ID (integer), as used in plot_data. The PSU collection ID (integer) of the smallest PSU in which the category is sampled.
area	The size of the area frame. Typically larger than the actual area of interest.
tract_area	The area of a tract, expressed in the same units as the target variable.
auxiliaries	A numeric matrix of auxiliary variables used for balancing. Must have the same dimensions and order as tract_data.
size_of_neighbourhood	An optional numeric vector specifying the neighbourhood size for each PSU level.

Details

The function combines plot-level observations (plot_data), tract-level information (tract_data), PSU hierarchy (psus), and category assignments (category_psu_map) to estimate totals under the NILS sampling design.

Variance estimation for spatially balanced sampling: NilsEstimateBalanced

In the balanced variant, variance is estimated using a local neighbourhood deviance measure. The neighbourhood size defaults to 4 for the smallest PSU level and increases linearly with PSU level size.

Covariance between categories belonging to different PSU levels are measured over their intersection, i.e. on the smaller PSU collections. Consequently, the smaller PSU collection also determines the local neighbourhood size.

It is possible to provide a matrix as psus instead of a vector. This matrix should contain:

1. PSU IDs, ordered from largest to smallest (by PSU size).

2. The neighbourhood size for each PSU.

If psus is provided as a vector, the neighbourhood size of PSU $k$ defaults to

$4 \frac{n_{k}}{n_{(0)}} ,$

where $n_{k}$ is the size of PSU collection $k$, and $n_{(0)}$ is the size of the smallest PSU collection.

Value

A NilsEstimate object, essentially a data frame with one row per category and the following columns:

Cat. ID

The category ID number.

Est. total

The estimated total of the target variable within the category.

Est. variance

The estimated variance of the total estimator within the category.

Positive tracts

The number of tracts with at least one positive value of the target variable in the category.

Examples

obj = NilsEstimate(plots, tracts, psus, category_psu_map);

obj = NilsEstimateBalanced(
  plots,
  tracts,
  tract_auxiliaries,
  psus,
  category_psu_map
);

---

Prepare plot-level data

Description

Reorders and extracts columns from a data frame to create a valid plot_data object. Column names are supplied as formulas for convenience.

Usage

PreparePlotData(data, tid, cat, dw, y)

Arguments

data	A data.frame containing plot-level information.
tid	A formula specifying the column containing tract IDs.
cat	A formula specifying the column containing category IDs.
dw	A formula specifying the column containing design weights.
y	A formula specifying the column containing the variable of interest.

Value

A data frame with the required column order for use as plot_data:

1. Tract ID (integer).

2. Category ID (integer).

3. Design weight (double).

4. Value of the variable of interest (double).

Examples

wide_df = data.frame(
  variable_y = runif(16),
  variable_x = runif(16),
  variable_z = runif(16),
  grassland_cover = plots[, 4],
  design_weight = plots[, 3],
  category = plots[, 2],
  tract_id = plots[, 1]
);

plot_data = PreparePlotData(
  wide_df,
  ~tract_id,
  ~category,
  ~design_weight,
  ~grassland_cover
);

---

Print a NILS estimate

Description

Prints a summary of a NilsEstimate object.

Usage

## S3 method for class 'NilsEstimate'
print(x, complete = TRUE, ...)

Arguments

x	A NilsEstimate object.
complete	Logical. If FALSE (default), excludes apparent zero-tracts from the printed output.
...	Additional arguments (currently unused)

Value

Invisibly returns the input NilsEstimate object.

---

Summarize a NILS estimate

Description

Produces summary statistics for a NilsEstimate object.

Usage

## S3 method for class 'NilsEstimate'
summary(object, ...)

## S3 method for class 'summary.NilsEstimate'
print(x, ...)

Arguments

object	A NilsEstimate object.
...	Additional arguments (currently unused).
x	A summary.NilsEstimate.

Value

The returned list has the following components:

estimate

Estimated total of the target variable.

variance

Estimated variance of the total estimator.

rel_se

Estimated relative standard error of the total estimator.

nonnil_tracts

Number of non-nil tracts. Not shown if filtering has been applied.

Examples

obj = NilsEstimate(plots, tracts, psus, category_psu_map);
summary(obj);

---

Sample data on cover of lawns from the NILS, 2024.

Description

The dataset includes information collected in the southern boreal region of Sweden (i.e. the boreal region South of the Dal River).

Usage

tracts

tract_auxiliaries

plots

psus

category_psu_map

Format

tracts

A matrix with 300 rows (tracts)

tid

the tract id number

psu

the id number of the collection of primary sampling units (PSU) of the tract

tract_auxiliaries

A matrix with 300 rows (auxiliary information about the tracts)

x

longitude of the tract centre

y

latitude of the tract centre

elev_max

the tract's maximum elevation

elev_range

the tract's elevation range

nmd_artificial

the area of the tract covered by buildings

nmd_open_land

the area of the tract covered by open land

nmd_forest

the area of the tract covered by forest

nmd_mountain_forest

the area of the tract covered by low-growth mountain forest

wetness_mean

the tract's mean wetness

decidiuous_sum

the area of the tract covered by deciduous forest

arable

the area of the tract covered by arable land

pasture

the area of the tract covered by pasture

plots

A matrix with 16 rows (plots)

tid

the tract id number of the tract containing this plot

cat

the category (stratum) of the plot

dw

the conditional design weight of the plot (inverse inclusion probability)

y

the variable of interest – the area of the (r=10) plot covered by grassland

psus

A length 2 ordered vector of PSU collection id numbers, ranging from the largest PSU level to the smallest PSU level

category_psu_map

A matrix with 2 rows (categories), containing the mapping of the largest PSU that the category map to.

category

the category (stratum) id number

psu

the id number of the largest PSU that the category can be observed in

Details

This sample is a reduced version of the original data, containing only the two sparsest subsamples and the two strata (selection classes/categories) sampled within them.

Source

https://www.slu.se/om-slu/organisation/institutioner/skoglig-resurshushallning/miljoanalys/nils/

---

Covariance matrix for NILS category estimates

Description

Accesses the covariance matrix of a NilsEstimate object.

Usage

## S3 method for class 'NilsEstimate'
vcov(object, complete = TRUE, ...)

Arguments

object	A NilsEstimate object.
complete	Logical. If FALSE, excludes apparent zero-tracts.
...	Additional arguments (currently unused).

Value

the covariance matrix of the NilsEstimate object.

Examples

obj = NilsEstimate(plots, tracts, psus, category_psu_map);
vcov(obj);

---