Skip to contents

Compare category counts, cutpoints, and observed within-category spread across several schemes applied to the same numeric column.

Usage

bin_compare(data, variable, bins = 4L,
  methods = c("quantile", "equal_width"),
  custom_breaks = NULL, separate_zero = FALSE,
  min_count = 20L, min_prop = 0.01)

Arguments

data

A data frame.

variable

One quoted column name identifying a plain numeric or integer vector.

bins

Unique whole numbers from 2 to 1000. Each requested count is paired with each automatic method. Ignored for custom schemes.

methods

Unique choices from c("quantile", "equal_width"). Use character(0) to compare only custom schemes.

custom_breaks

An optional named list of numeric boundary vectors. Each vector must be finite, strictly increasing, and cover the values to be binned, including endpoints. Names must be unique, nonempty, and different from automatic names such as "quantile_4".

separate_zero

Use a separate exact-zero category in every scheme. Requires nonnegative data. Requested interval counts exclude this category.

min_count, min_prop

Sparse-bin screens shared by every scheme. A category is flagged if its count is less than min_count or its proportion of all finite rows is less than min_prop. Defaults are 20 and 0.01.

Details

Each scheme uses bin_diagnose. Missing and infinite values are excluded consistently. Ties remain together, duplicate automatic boundaries collapse, and empty bins are retained. Intervals include their upper boundary; the first includes its lower boundary. If requested, zeros are assigned first.

The comparison records requested and retained interval counts separately from the additional zero category. Size summaries include empty bins and the zero category. Percentages use all finite rows. The widest observed within-bin range is the largest difference between observed extrema in a nonempty category, not the width between its nominal cutpoints. It is measured in the original variable's units. Empty bins are excluded from this range calculation. Ties for widest range select the first category. An extreme range difference can overflow to Inf even though both observed endpoints are finite.

Small tail groups may be intentional. Observed ranges describe retained within-category variation; they are not information-loss scores or tests. No best scheme is automatically selected. Per-scheme diagnostic notes are stored without emitting warnings; invalid inputs stop the whole comparison with an error naming the scheme. No partially evaluated comparison is returned. The original data are not modified. Schemes and assignments are kept in memory, so large data and many requested schemes can require substantial memory.

Value

A bin_comparison list.

comparison

One row per scheme. Columns include scheme, method, requested intervals, retained intervals, zero_bins, total_bins, occupied, empty, sparse, smallest_n, largest_n, smallest_pct, largest_pct, widest_bin, observed_min, observed_max, and widest_range. The last four describe the widest observed within-bin range.

bins

All per-bin tables with an added scheme column, including exact cutpoints, observed summaries, counts, proportions, and sparse flags.

diagnoses

Named list of full bin_diagnosis objects. Use these for per-scheme assessments, notes, and assignments aligned to the original rows.

assessment

Plain-language comparison as a character vector.

call, variable, separate_zero, min_count, min_prop

Call and shared settings.

Examples

d <- data.frame(x = c(rep(0, 40), seq(.01, 1, length.out = 60)))
comparison <- bin_compare(d, "x", bins = c(3, 5), separate_zero = TRUE,
  custom_breaks = list(thresholds = c(0, .1, .5, 1)))
comparison
#> binwise comparison of x
#> 
#> * All 5 schemes use the same 100 finite observations; 0 missing and 0 infinite values are excluded.
#> * Every scheme keeps exact zeros separate. Requested intervals exclude this additional category; size and sparse-bin summaries include it.
#> * quantile_3 produces 3 intervals plus 1 zero category, with 0 empty and 0 flagged categories. Its largest category contains 40.00% of the sample; its widest observed within-bin range runs from 0.68119 to 1.
#> * quantile_5 produces 5 intervals plus 1 zero category, with 0 empty and 5 flagged categories. Its largest category contains 40.00% of the sample; its widest observed within-bin range runs from 0.41271 to 0.59729.
#> * equal_width_3 produces 3 intervals plus 1 zero category, with 0 empty and 0 flagged categories. Its largest category contains 40.00% of the sample; its widest observed within-bin range runs from 0.68119 to 1.
#> * equal_width_5 produces 5 intervals plus 1 zero category, with 0 empty and 5 flagged categories. Its largest category contains 40.00% of the sample; its widest observed within-bin range runs from 0.41271 to 0.59729.
#> * thresholds produces 3 intervals plus 1 zero category, with 0 empty and 1 flagged categories. Its largest category contains 40.00% of the sample; its widest observed within-bin range runs from 0.51339 to 1.
#> * Use category sizes to assess balance and within-bin ranges to assess which values are grouped together. A small tail category can be intentional. These summaries do not select a best scheme. 
#> 
#> Category counts and sizes
#>         scheme requested intervals zero_bins empty sparse smallest_n largest_n
#>     quantile_3         3         3         1     0      0         20        40
#>     quantile_5         5         5         1     0      5         12        40
#>  equal_width_3         3         3         1     0      0         20        40
#>  equal_width_5         5         5         1     0      5         12        40
#>     thresholds         3         3         1     0      1          6        40
#> 
#> Observed spread within categories, in the variable's original units
#>         scheme smallest_pct largest_pct widest_bin observed_min observed_max
#>     quantile_3           20          40         B3       0.6812       1.0000
#>     quantile_5           12          40         B3       0.4127       0.5973
#>  equal_width_3           20          40         B3       0.6812       1.0000
#>  equal_width_5           12          40         B3       0.4127       0.5973
#>     thresholds            6          40         B3       0.5134       1.0000
#>  widest_range
#>        0.3188
#>        0.1846
#>        0.3188
#>        0.1846
#>        0.4866
#> 
#> Requested and intervals exclude any separate zero category.
#> Smallest/largest sizes include empty bins and any zero category; percentages use all finite rows.
#> Sparse means n < 20 or proportion < 0.01.
#> Inspect $bins for every boundary and count, or $diagnoses for each full assessment.
comparison$bins
#>           scheme  bin lower upper left_closed right_closed singleton  n
#> 1     quantile_3 Zero 0.000 0.000        TRUE         TRUE      TRUE 40
#> 2     quantile_3   B1 0.010 0.340        TRUE         TRUE     FALSE 20
#> 3     quantile_3   B2 0.340 0.670       FALSE         TRUE     FALSE 20
#> 4     quantile_3   B3 0.670 1.000       FALSE         TRUE     FALSE 20
#> 5     quantile_5 Zero 0.000 0.000        TRUE         TRUE      TRUE 40
#> 6     quantile_5   B1 0.010 0.208        TRUE         TRUE     FALSE 12
#> 7     quantile_5   B2 0.208 0.406       FALSE         TRUE     FALSE 12
#> 8     quantile_5   B3 0.406 0.604       FALSE         TRUE     FALSE 12
#> 9     quantile_5   B4 0.604 0.802       FALSE         TRUE     FALSE 12
#> 10    quantile_5   B5 0.802 1.000       FALSE         TRUE     FALSE 12
#> 11 equal_width_3 Zero 0.000 0.000        TRUE         TRUE      TRUE 40
#> 12 equal_width_3   B1 0.010 0.340        TRUE         TRUE     FALSE 20
#> 13 equal_width_3   B2 0.340 0.670       FALSE         TRUE     FALSE 20
#> 14 equal_width_3   B3 0.670 1.000       FALSE         TRUE     FALSE 20
#> 15 equal_width_5 Zero 0.000 0.000        TRUE         TRUE      TRUE 40
#> 16 equal_width_5   B1 0.010 0.208        TRUE         TRUE     FALSE 12
#> 17 equal_width_5   B2 0.208 0.406       FALSE         TRUE     FALSE 12
#> 18 equal_width_5   B3 0.406 0.604       FALSE         TRUE     FALSE 12
#> 19 equal_width_5   B4 0.604 0.802       FALSE         TRUE     FALSE 12
#> 20 equal_width_5   B5 0.802 1.000       FALSE         TRUE     FALSE 12
#> 21    thresholds Zero 0.000 0.000        TRUE         TRUE      TRUE 40
#> 22    thresholds   B1 0.000 0.100        TRUE         TRUE     FALSE  6
#> 23    thresholds   B2 0.100 0.500       FALSE         TRUE     FALSE 24
#> 24    thresholds   B3 0.500 1.000       FALSE         TRUE     FALSE 30
#>    proportion sparse         sd       mean observed_max observed_min
#> 1        0.40  FALSE 0.00000000 0.00000000   0.00000000    0.0000000
#> 2        0.20  FALSE 0.09926981 0.16940678   0.32881356    0.0100000
#> 3        0.20  FALSE 0.09926981 0.50500000   0.66440678    0.3455932
#> 4        0.20  FALSE 0.09926981 0.84059322   1.00000000    0.6811864
#> 5        0.40  FALSE 0.00000000 0.00000000   0.00000000    0.0000000
#> 6        0.12   TRUE 0.06049993 0.10228814   0.19457627    0.0100000
#> 7        0.12   TRUE 0.06049993 0.30364407   0.39593220    0.2113559
#> 8        0.12   TRUE 0.06049993 0.50500000   0.59728814    0.4127119
#> 9        0.12   TRUE 0.06049993 0.70635593   0.79864407    0.6140678
#> 10       0.12   TRUE 0.06049993 0.90771186   1.00000000    0.8154237
#> 11       0.40  FALSE 0.00000000 0.00000000   0.00000000    0.0000000
#> 12       0.20  FALSE 0.09926981 0.16940678   0.32881356    0.0100000
#> 13       0.20  FALSE 0.09926981 0.50500000   0.66440678    0.3455932
#> 14       0.20  FALSE 0.09926981 0.84059322   1.00000000    0.6811864
#> 15       0.40  FALSE 0.00000000 0.00000000   0.00000000    0.0000000
#> 16       0.12   TRUE 0.06049993 0.10228814   0.19457627    0.0100000
#> 17       0.12   TRUE 0.06049993 0.30364407   0.39593220    0.2113559
#> 18       0.12   TRUE 0.06049993 0.50500000   0.59728814    0.4127119
#> 19       0.12   TRUE 0.06049993 0.70635593   0.79864407    0.6140678
#> 20       0.12   TRUE 0.06049993 0.90771186   1.00000000    0.8154237
#> 21       0.40  FALSE 0.00000000 0.00000000   0.00000000    0.0000000
#> 22       0.06   TRUE 0.03139187 0.05194915   0.09389831    0.0100000
#> 23       0.24  FALSE 0.11865012 0.30364407   0.49661017    0.1106780
#> 24       0.30  FALSE 0.14771821 0.75669492   1.00000000    0.5133898
comparison$diagnoses$quantile_3$assessment
#> [1] "Exact zeros account for 40.00% of finite observations. They are kept in a separate category; interval bins describe positive values."                                                           
#> [2] "The largest interval, B1, contains 20 observations (33.33% of observations assigned to intervals). Compare this balance with your intended use of the categories."                              
#> [3] "The widest observed within-bin range is in B3, from 0.68119 to 1 (31.88% of the full observed range). If distinctions within that range matter, consider additional or custom boundaries there."
plot(comparison, schemes = c("quantile_3", "equal_width_3"))

plot(comparison, type = "boundaries", schemes = c("quantile_3", "thresholds"))