Type: | Package |
Title: | Design-Based Estimators for NILS |
Version: | 0.1.1 |
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/. |
License: | AGPL-3 |
Encoding: | UTF-8 |
Language: | en-GB |
Depends: | R (≥ 4.2) |
Imports: | Rcpp (≥ 1.0.14) |
LinkingTo: | Rcpp |
URL: | https://github.com/envisim/nilsier/ |
NeedsCompilation: | yes |
LazyData: | true |
RoxygenNote: | 7.3.2 |
Packaged: | 2025-09-30 07:39:33 UTC; wpmg |
Author: | Wilmer Prentius |
Maintainer: | Wilmer Prentius <wilmer.prentius@slu.se> |
Repository: | CRAN |
Date/Publication: | 2025-10-06 08:10:07 UTC |
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 wilmer.prentius@slu.se.
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:
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):
|
tract_data |
A matrix with information about all sampled tracts, including those where no relevant categories were found. Must contain (in order):
|
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):
|
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 |
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:
PSU IDs, ordered from largest to smallest (by PSU size).
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
:
Tract ID (integer).
Category ID (integer).
Design weight (double).
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
);
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)
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 |
... |
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 |
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 |
... |
Additional arguments (currently unused). |
Value
the covariance matrix of the NilsEstimate object.
Examples
obj = NilsEstimate(plots, tracts, psus, category_psu_map);
vcov(obj);