MergeByValue()

Summary

Creates districts by merging areas from a geographic file, based on the value of a field.

 

Syntax

MergeByValue(string geofile_name, string new_layer_name, string lyr_set_name, string field, string output_table_type, array field_specs, array options)

 

Argument	Contents
geofile_name	The name of the new standard geographic file for the districts
new_layer_name	The name of the layer in the new geographic file
lyr_set_name	The name of the input layer or selection set
field	The name of the field on which to merge. All areas in lyr_set_name with the same value for this field will be merged into a single area in the new geographic file
output_table_type	The table type to use to store the aggregate data for the districts (one of "DBASE", "FFA", "FFB", or "CSV")
field_specs	An array containing one element for each field in the output table. Each element is an array of three items that indicate the statistic to be calculated, as shown below:

 

Item..	Type	Contents
1	String	Name of a field in the input layer
2	String	Statistic: "SUM", "MIN", "MAX", "DOM" (DOMINANT), "AVG" (AVERAGE), or "STDDEV"
3 (optional)	String	Name of a field in the input view used in computing averages. Necessary only for averages. Must be a numeric field.

 

Option	Type	Contents
Missing as Zero	N/A	No contents necessary. If present, this option causes all missing numeric values in the input view to be treated as zeros in sum, average, min or max calculations.

 

Notes

• The file types include FFA for fixed-format text (ASCII), FFB for fixed-format binary, and CSV for comma-separated text (values).

• MergeByValue() takes the features in a layer or selection set and groups them together based on the value of one of the fields in the view. Then, for each group, it creates an area feature in a new geographic file, and computes the sum, min, max, dominant, standard deviation, or average value for any data field. The results are written to a new table file that is joined to the area definitions in the geographic file.

• By default, when you use the sum, min, max, standard deviation, or average statistic for a numeric field, any missing values in the input view result in a missing value for the statistic.

• For string typed input data fields, only the dominant mode is supported. This currently evaluates to the first value encountered for the chosen field.

• The average statistic calculates weighted averages, and requires a weighting field (the optional third field listed above).

• The output table has one record for each value of the aggregation field.

• The output table has one column containing the group value, plus one column for each statistic that was requested in output_fields.

• The name, width and number of decimals for all output fields are automatically determined. The name is determined as follows:

Statistic	Prefix	Example
Sum	(none)	Income
Min	Low	Low Income
Max	High	High Income
Average	Avg	Avg Income

• If the layer to be merged does not contain any topology then the areas will be merged into districts, but the common borders inside the districts will not be removed.

Example

MergeByValue("districts.dbd", "Districts", "ZIP Codes|","DistrictNumber", "DBASE",      {{"Population","sum", },

     {"Population","min", },

     {"Population","max", },

     {"HH Income","average", "Households"}

     }, null)

 

Error Codes

Error Type	Meaning
Error	The geofile_name was invalid, the lyr_set_name was invalid, the field was invalid, or the output table could not be created
NotFound	There is no layer, selection set, or field with the given name

 

See Also

Function	Summary
AggregateTable()	Groups records in a view and computes summary statistics
ApplyOverlayTable()	Computes attribute values for a view using information from an overlay table
ColumnAggregate()	Performs a geographic overlay between two layers and aggregates tabular data
ComputeIntersectionPercentages()	Intersects two or more area or line layers and computes the intersection percentages
GetMergedArea()	Creates an area by merging a set of features
SelfAggregate()	Groups the records in a view, based on a field, to create an aggregate view