Syntax

   FACTORY_DEF <ReaderKeyword> SamplingFactory
   [FACTORY_NAME <factory name>]
   [INPUT FEATURE_TYPE <feature type>
      [<attribute name> <attribute value>]*
      [<feature function>]*]*
   [GROUP_BY [<attribute name>]+]*
   [FLUSH_WHEN_GROUPS_CHANGE (Yes|No)]
   SAMPLE_RATE <sample rate>
   SAMPLE_ORDER (RANDOM|LAST|ORIGINAL)
   [OUTPUT (SAMPLED|NOT_SAMPLED)
      FEATURE_TYPE <feature type>
      [<attribute name> <attribute value>]*
      [<feature function>]*]*

Overview

   This factory samples the input features at a specified rate and divides them
   into two groups: those which are matched by the sampling rate, and those
   which come between the sampled features. The first input feature and each
   <sample rate> feature thereafter is considered a "sampled" feature.

   However, when the sample rate is negative, then the sampling factory behaves
   differently. For example, if the sample rate is -1, then only the first
   feature will pass as sampled. Similarly, if sample rate is -2, then only the
   first two features will pass as sampled, and so on.

   The input features are partitioned into groups based on attribute values by way
   of the GROUP_BY clause, and each group is sampled independently. If
   FLUSH_WHEN_GROUPS_CHANGE is set to Yes, any remaining sampling of the current
   group will complete whenever a feature of a different group is encountered.
   If the GROUP_BY clause is not specified, then all input features will be
   sampled together.

   The SamplingFactory is useful to test mapping files being developed for large
   data sources as it can greatly reduce the number of features processed by the
   system.

      A sample rate of 1 passes all features through the factory. This can be
      used to apply a feature function to every translated feature.

      A sample rate of 0 tells the SamplingFactory to treat all features as
      unsampled features.

      A sample rate of -1 tells the SamplingFactory to pass only the first
      feature as sampled feature.

     The SAMPLE_ORDER can be used to vary the above behaviour.  If it is
     ORIGINAL, then the rates are interpreted as above.  If it is RANDOM,
     then all features are held until the end of the input, and the
     features are shuffled before being output as per the sampling rate above.
     If the SAMPLE_ORDER is LAST, then the SAMPLE_RATE will contain the
     number of features that will be output and these will be the LAST ones
     in each group to enter the factory.

      Note: Older versions of this factory did not support any output clauses,
      and simply wrote out the sampled features. To maintain backward
      compatibility, an instance of the SamplingFactory which has no OUTPUT
      clause will behave as if a clause of "OUTPUT SAMPLED FEATURE_TYPE *" has
      been specified. This is non-standard FME behavior.

Output Tags

   The SamplingFactory supports the following output tags.

   SAMPLED

      Features that occur at the specified <sample rate> are output with this
      tag.

   NOT_SAMPLED

      Features that come between the sampled features are output with this tag.