SAMPLE command

Used to select records or monetary unit samples from a population in a data file.

Syntax

SAMPLE {[record_syntax]|[mus_syntax]}
<IF test> <WHILE test> <FIRST|NEXT range> <HEADER header_text>
<FOOTER footer_text> TO table_name {<ORDER> FIELDS field_name <...n>|RECORD}
<APPEND> <OPEN> <LOCAL>

 

[record_syntax] ::=
<ON> RECORD {INTERVAL value FIXED value|CELL INTERVAL value RANDOM value
|RANDOM value NUMBER value}

 

[mus_syntax] ::=
<ON> mus_numeric_field {INTERVAL value FIXED value CUTOFF value|CELL
INTERVAL value CUTOFF value RANDOM value|RANDOM value NUMBER value
POPULATION value} <SUBSAMPLE><REPLACEMENT|NOREPLACEMENT>

Parameters

ON RECORD

Specifies record sampling as the sample type. The ON parameter can be omitted.

FIXED

Specifies that the first record or monetary unit chosen is a Fixed Interval sample.

CELL

Specifies that random interval sampling should be used. The data set is broken into groups that equal the size of the specified interval. One random item is chosen from each group, based on a seed value that you specify.

INTERVAL

Specifies the interval value for sampling.

RANDOM value

Specifies the seed value for the random number generator for Cell and Random samples.

NUMBER value

Specifies the size of the population to sample.

ON mus_numeric_field

Specifies the field or expression for monetary unit sampling (MUS). The ON parameter can be omitted.

SUBSAMPLE

Optional. If specified, an extra field is generated in the output table which contains a random number between zero and the field value of the selected item. This is useful when subsampling is required, for example, when a selected sample item is actually made up of a number of “smaller” items. Top stratum items have a subsample amount of zero, facilitating alternative analyses on this population.

REPLACEMENT | NOREPLACEMENT

Optional. If REPLACEMENT is selected, the same MUS item will not be selected more than once. Because ACL does not replace any selections omitted, fewer records or values may be displayed than expected. If this parameter is omitted the default value of NOREPLACEMENT is used.

CUTOFF stratum

Specifies an vale for Fixed Interval and Cell sampling at which an item is considered top stratum. Top stratum items are automatically selected and included in the sample. The default cutoff is the Interval size.

POPULATION

Specifies the total number of units in the population, either in terms of records or the absolute value of the field being sampled on. A population value is only available for Random sampling.

To ensure that each record or field value in the sampling population has the correct opportunity of selection, use either the total number of records in the file (record sampling), or the absolute value of the sampled field (monetary unit sampling), as the population size.

If you choose some other population size, ACL informs you that the supplied population total differs from the actual total.

ORDER

Specifies that an additional field called ORDER should be included in the output results. This field contains the order number that the particular item was selected in.

FIELDS field name

Specifies the field(s) or expressions to be included with the sampled output record. Any field or expression may be used. If you specify multiple fields, they must be separated by spaces.

IF test

Optional. Specifies a condition that must be met. The command is only executed on records that pass the test.

WHILE test

Optional. Specifies that the command should only be executed while a condition is true. The command processing terminates as soon as the specified test evaluates as false, or the end of the table is reached.

FIRST | NEXT range

Optional. Specify FIRST to start processing at the first record or NEXT to start processing at the currently selected record. Use the range value to specify the number of records to process.

HEADER header_text

Optional. Specifies the text to insert at the top of each page of a report. The header_text value must be specified as a quoted string. The value overrides any value set for the ACL HEADER system variable.

FOOTER footer_text

Optional. Specifies the text to insert at the bottom of each page of a report. The footer_text value must be specified as a quoted string. The value overrides any value set for the ACL FOOTER system variable.

TO table_name

Specify TO table_name to write the results to an ACL table. You must specify the table_name value as a quoted string with a .FIL file extension to create an ACL table.

For example: TO "Output.FIL"

You can also specify an absolute or relative file path to an existing folder to write the .FIL file to.

For example: TO "C:\Output.FIL" or TO "Results\Output.FIL"

APPEND

Optional. Specifies that command output should be appended to the end of an existing file instead of overwriting the existing file. You must ensure that the structure of the two files is identical when using this parameter, if maintaining a consistent file structure is important (e.g., when you are appending data to an existing ACL table), because ACL appends output to an existing file regardless of its structure.

OPEN

Optional. Specifies that the table created by the command should be opened after the command executes. This parameter is only valid if the command creates an output table.

LOCAL

Optional. Specifies that the output file should be saved in the same location as the ACL project. This parameter only applies when the command is run on an ACL Server table and the output file is an ACL table.

Remarks

The default for MUS sampling is the absolute value of the field if the PROFILE or STATISTICS command has been previously issued. Otherwise, there is no default.

The default for record sampling is the record count for the file.



(C) 2013 ACL Services Ltd. All Rights Reserved. | Send feedback