ListSampler.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  17. package org.apache.commons.rng.sampling;

  18. import java.util.List;
  19. import java.util.ListIterator;
  20. import java.util.RandomAccess;
  21. import java.util.ArrayList;

  22. import org.apache.commons.rng.UniformRandomProvider;

  23. /**
  24.  * Sampling from a {@link List}.
  25.  *
  26.  * <p>This class also contains utilities for shuffling a {@link List} in-place.</p>
  27.  *
  28.  * @since 1.0
  29.  */
  30. public final class ListSampler {
  31.     /**
  32.      * The size threshold for using the random access algorithm
  33.      * when the list does not implement java.util.RandomAccess.
  34.      */
  35.     private static final int RANDOM_ACCESS_SIZE_THRESHOLD = 4;

  36.     /**
  37.      * Class contains only static methods.
  38.      */
  39.     private ListSampler() {}

  40.     /**
  41.      * Generates a list of size {@code k} whose entries are selected
  42.      * randomly, without repetition, from the items in the given
  43.      * {@code collection}.
  44.      *
  45.      * <p>
  46.      * Sampling is without replacement; but if the source collection
  47.      * contains identical objects, the sample may include repeats.
  48.      * </p>
  49.      *
  50.      * <p>
  51.      * Sampling uses {@link UniformRandomProvider#nextInt(int)}.
  52.      * </p>
  53.      *
  54.      * @param <T> Type of the list items.
  55.      * @param rng Generator of uniformly distributed random numbers.
  56.      * @param collection List to be sampled from.
  57.      * @param k Size of the returned sample.
  58.      * @throws IllegalArgumentException if {@code k <= 0} or
  59.      * {@code k > collection.size()}.
  60.      * @return a shuffled sample from the source collection.
  61.      */
  62.     public static <T> List<T> sample(UniformRandomProvider rng,
  63.                                      List<T> collection,
  64.                                      int k) {
  65.         final int n = collection.size();
  66.         final PermutationSampler p = new PermutationSampler(rng, n, k);
  67.         final List<T> result = new ArrayList<>(k);
  68.         final int[] index = p.sample();

  69.         for (int i = 0; i < k; i++) {
  70.             result.add(collection.get(index[i]));
  71.         }

  72.         return result;
  73.     }

  74.     /**
  75.      * Shuffles the entries of the given array, using the
  76.      * <a href="http://en.wikipedia.org/wiki/Fisher-Yates_shuffle#The_modern_algorithm">
  77.      * Fisher-Yates</a> algorithm.
  78.      *
  79.      * <p>
  80.      * Sampling uses {@link UniformRandomProvider#nextInt(int)}.
  81.      * </p>
  82.      *
  83.      * @param <T> Type of the list items.
  84.      * @param rng Random number generator.
  85.      * @param list List whose entries will be shuffled (in-place).
  86.      */
  87.     @SuppressWarnings({"rawtypes", "unchecked"})
  88.     public static <T> void shuffle(UniformRandomProvider rng,
  89.                                    List<T> list) {
  90.         if (list instanceof RandomAccess || list.size() < RANDOM_ACCESS_SIZE_THRESHOLD) {
  91.             // Shuffle list in-place
  92.             for (int i = list.size(); i > 1; i--) {
  93.                 swap(list, i - 1, rng.nextInt(i));
  94.             }
  95.         } else {
  96.             // Shuffle as an array
  97.             final Object[] array = list.toArray();
  98.             for (int i = array.length; i > 1; i--) {
  99.                 swap(array, i - 1, rng.nextInt(i));
  100.             }

  101.             // Copy back. Use raw types.
  102.             final ListIterator it = list.listIterator();
  103.             for (final Object item : array) {
  104.                 it.next();
  105.                 it.set(item);
  106.             }
  107.         }
  108.     }

  109.     /**
  110.      * Shuffles the entries of the given array, using the
  111.      * <a href="http://en.wikipedia.org/wiki/Fisher-Yates_shuffle#The_modern_algorithm">
  112.      * Fisher-Yates</a> algorithm.
  113.      *
  114.      * <p>
  115.      * The {@code start} and {@code pos} parameters select which part
  116.      * of the array is randomized and which is left untouched.
  117.      * </p>
  118.      *
  119.      * <p>
  120.      * Sampling uses {@link UniformRandomProvider#nextInt(int)}.
  121.      * </p>
  122.      *
  123.      * @param <T> Type of the list items.
  124.      * @param rng Random number generator.
  125.      * @param list List whose entries will be shuffled (in-place).
  126.      * @param start Index at which shuffling begins.
  127.      * @param towardHead Shuffling is performed for index positions between
  128.      * {@code start} and either the end (if {@code false}) or the beginning
  129.      * (if {@code true}) of the array.
  130.      */
  131.     public static <T> void shuffle(UniformRandomProvider rng,
  132.                                    List<T> list,
  133.                                    int start,
  134.                                    boolean towardHead) {
  135.         // Shuffle in-place as a sub-list.
  136.         if (towardHead) {
  137.             shuffle(rng, list.subList(0, start + 1));
  138.         } else {
  139.             shuffle(rng, list.subList(start, list.size()));
  140.         }
  141.     }

  142.     /**
  143.      * Swaps the two specified elements in the list.
  144.      *
  145.      * @param <T> Type of the list items.
  146.      * @param list List.
  147.      * @param i First index.
  148.      * @param j Second index.
  149.      */
  150.     private static <T> void swap(List<T> list, int i, int j) {
  151.         final T tmp = list.get(i);
  152.         list.set(i, list.get(j));
  153.         list.set(j, tmp);
  154.     }

  155.     /**
  156.      * Swaps the two specified elements in the array.
  157.      *
  158.      * @param array Array.
  159.      * @param i First index.
  160.      * @param j Second index.
  161.      */
  162.     private static void swap(Object[] array, int i, int j) {
  163.         final Object tmp = array[i];
  164.         array[i] = array[j];
  165.         array[j] = tmp;
  166.     }
  167. }