From c03d404b5badeb42a4275b5d777237f987802fd4 Mon Sep 17 00:00:00 2001 From: Milan Bouchet-Valat Date: Tue, 18 Jan 2022 22:35:54 +0100 Subject: [PATCH 1/3] Improve weigths docstrings `AnalyticWeights` have a precise definition, on which we rely in several functions. Also make docstrings more consistent across types. --- src/weights.jl | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/weights.jl b/src/weights.jl index 712951509..dbabdda6d 100644 --- a/src/weights.jl +++ b/src/weights.jl @@ -96,8 +96,8 @@ end Construct an `AnalyticWeights` vector with weight values `vs`. A precomputed sum may be provided as `wsum`. -Analytic weights describe a non-random relative importance (usually between 0 and 1) -for each observation. These weights may also be referred to as reliability weights, +Analytic weights represent the inverse of the variance for each case. +These weights may also be referred to as reliability weights, precision weights or inverse variance weights. These are typically used when the observations being weighted are aggregate values (e.g., averages) with differing variances. """ AnalyticWeights @@ -136,7 +136,7 @@ end Construct a `FrequencyWeights` vector with weight values `vs`. A precomputed sum may be provided as `wsum`. -Frequency weights describe the number of times (or frequency) each observation +Frequency weights represent the number of times (or frequency) each case was observed. These weights may also be referred to as case weights or repeat weights. """ FrequencyWeights @@ -173,9 +173,9 @@ end Construct a `ProbabilityWeights` vector with weight values `vs`. A precomputed sum may be provided as `wsum`. -Probability weights represent the inverse of the sampling probability for each observation, +Probability weights represent the inverse of the sampling probability for each case, providing a correction mechanism for under- or over-sampling certain population groups. -These weights may also be referred to as sampling weights. +These weights may also be referred to as sampling weights or survey weights. """ ProbabilityWeights """ From 538399f5f55996475ab6827213b86ea91f9cf2d4 Mon Sep 17 00:00:00 2001 From: Milan Bouchet-Valat Date: Thu, 20 Jan 2022 09:55:05 +0100 Subject: [PATCH 2/3] Add mentions about scale-invariance --- src/weights.jl | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/weights.jl b/src/weights.jl index dbabdda6d..ba653006f 100644 --- a/src/weights.jl +++ b/src/weights.jl @@ -138,6 +138,9 @@ A precomputed sum may be provided as `wsum`. Frequency weights represent the number of times (or frequency) each case was observed. These weights may also be referred to as case weights or repeat weights. + +The scale of frequency weights is significant: for some functions, +multiplying all weights by a constant changes the result. """ FrequencyWeights """ @@ -176,6 +179,11 @@ A precomputed sum may be provided as `wsum`. Probability weights represent the inverse of the sampling probability for each case, providing a correction mechanism for under- or over-sampling certain population groups. These weights may also be referred to as sampling weights or survey weights. + +The scale of probability weights is not significant: multiplying all weights +by a constant does not change the result of any weighted functions +(except when explicitly computing the sum of weights). This is because +the sample size is taken to be the number of cases with a non-zero weight. """ ProbabilityWeights """ From 0350e4e36a1e8129e24d4c1d118c0ebfbfc97537 Mon Sep 17 00:00:00 2001 From: Milan Bouchet-Valat Date: Sun, 23 Jan 2022 22:45:20 +0100 Subject: [PATCH 3/3] Update weights.jl --- src/weights.jl | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/weights.jl b/src/weights.jl index ba653006f..1ec7c8e6c 100644 --- a/src/weights.jl +++ b/src/weights.jl @@ -96,10 +96,11 @@ end Construct an `AnalyticWeights` vector with weight values `vs`. A precomputed sum may be provided as `wsum`. -Analytic weights represent the inverse of the variance for each case. -These weights may also be referred to as reliability weights, -precision weights or inverse variance weights. These are typically used when the observations -being weighted are aggregate values (e.g., averages) with differing variances. +Analytic weights are proportional to the inverse of the variance for each case. +These weights may also be referred to as reliability weights or precision weights. + +The scale of analytic weights is significant: for some functions, +multiplying all weights by a constant changes the result. """ AnalyticWeights """