FRAMES | NO FRAMES
ThresholdRings Method

Creates rings around stores. The radii of the rings are determined by expanding out from the store location until they meet the given criteria.

Availability: Business Analyst Server.

TaskResultOutput ThresholdRings ( 
    ThresholdRingsParams  Parameters, 
    esriReportFormat      ReportFormat, 
    RenderingParameters   RenderingParameters, 
    TaskOutputType[]      OutputTypes, 
    esriFolderItem        OutputAnalysisItem, 
    esriFolderItem[]      OutputReportItems
);

Parameter Description
Parameters Configuration options analysis. Type ThresholdRingsParams.
ReportFormat This parameter should be null. This parameter is deprecated.
RenderingParameters Configuration options for rendering output when GetMapImage option is specified in the OutputTypes parameter. Type RenderingParameters.
OutputTypes Array of task output options. Options for this method include rendering output image (GetMapImage), creating a feature layer for subsequent analysis (GetFeatureClass), and creating a report (GetReport). Type TaskOutputType[].
OutputAnalysisItem (Optional parameter — can be null).
Configuration options for storing the output feature layer in the repository. This will enable viewing and working with the output result in subsequent tasks. Type esriFolderItem.
OutputReportItems (Optional parameter - can be null).
Array of configuration options for storing the output reports in the repository. This will enable viewing and working with the output result in subsequent tasks. Type esriFolderItem[]. Available with Business Analyst Server 10.0.

Returns

Variable of type TaskResultOutput

Remarks

The ThresholdRings method creates ring-based trade areas that expand out from the store locations until they meet a specified criteria. You define the criteria, or size of each ring, manually.

The following is an example of how this method can be used to examine the optimal location for a new community center in a given market. Assume you have several proposed community center locations in San Diego, California. To create threshold rings for each location, you would set the community center point layer as the store layer. You would then set the threshold data to a standard geographic layer. You can set the field to aggregate to total households and create the ring-based trade areas based on the values you set in the radii parameter.

Each ring created will have the same number of households but will be of different sizes. This method provides an excellent visual indicator of how far each community center will have to draw the same number of households. A city may want to optimize the location of a new community center by finding the location that will minimize how far people will have to travel to a facility. This same logic can be applied to a retail business scenario.

Because the radii is the same for each store, this method is good for comparing the trade areas of similar stores.

This method is typically used to create radius trade areas for competitors so a store owner can see if a store is being cannibalized by the competition. It can also be used to look for gaps in the market area.

NOTE: Since Business Analyst Server 10.0, the OutputReportItem parameter is replaced with the OutputReportItems parameter which is an array of folder items. The number of items in this array should be equal to the number of items in the ReportOptions array.

Usage Tips

Examples

The example below demonstrates creation of a threshold rings-based trade areas and an associated report from an address record set. The derived store layer, threshold rings-based trade area layer, and a summary report generated from the trade area are all saved to the repository.

NOTE: The signature of the BAServerHelper.ThresholdRings method is made compatible with the previous version of this method—the OutputReportItems parameter is specified with the params keyword allowing users to pass output report items in the variable-length list of parameters.

C#
// Instantiate the BAServerHelper class to access analysis methods
BAServerHelper baServerHelper = new BAServerHelper();
baServerHelper.ActiveDatasetID = "USA_ESRI"; // Optional parameter
baServerHelper.IsFullErrorMessage = true;    // Default is false
 
// You can specify below a domain of your local Business Analyst Server.
//baServerHelper.BAServerDomain = "esri.com";
 
// If a domain name is specified, a local server name in output URLs is replaced with the
// fully-addressable server name so people and machines outside the domain of your local
// Business Analyst Server instance can access these URLs.
 
RenderingParameters imageOptions;
TaskOutputType[] outputOptions;
esriFolderItem outputLayer;
esriFolderItem outputReport;
 
// ========= STEP 1: Create a record set by store addresses
 
RecordSetByAddress[] storeAddresses = new RecordSetByAddress[2];
 
storeAddresses[0] = new RecordSetByAddress();
storeAddresses[0].Name = "pizza1";
storeAddresses[0].Description = "Rush Street Store";
storeAddresses[0].StoreID = "1";
storeAddresses[0].Address = "730 N. Rush St.";
storeAddresses[0].City = "Chicago";
storeAddresses[0].State = "IL";
storeAddresses[0].ZIP = "60611";
 
storeAddresses[1] = new RecordSetByAddress();
storeAddresses[1].Name = "pizza2";
storeAddresses[1].Description = "Clark Street Store";
storeAddresses[1].StoreID = "2";
storeAddresses[1].Address = "2121 N. Clark St.";
storeAddresses[1].City = "Chicago";
storeAddresses[1].State = "IL";
storeAddresses[1].ZIP = "60614";
 
TaskResultOutput recordSetByAddressResult =
    baServerHelper.CreateRecordSetByAddresses(storeAddresses, esriFolderType.esriFolderStoreLayers);
 
TableData tableData = new TableData();
tableData.RecordSet = recordSetByAddressResult.RecordSet;
GeocodeData geocodeData = new GeocodeData();
geocodeData.Table = tableData;
 
// ========= STEP 2: Geocode the record set with stores
 
CustomerStoreSetupByGeocodeTableParameters geocodeParameters = new CustomerStoreSetupByGeocodeTableParameters();
 
// Set specific analysis parameters
geocodeParameters.GeocodeCustomers = false;
geocodeParameters.GeocodeData = geocodeData;
geocodeParameters.NameField = "NAME";
geocodeParameters.StoreIDField = "STORE_ID";
 
// Set other parameters
imageOptions = null;
outputOptions = new TaskOutputType[] { TaskOutputType.GetFeatureClass };
 
// In general, a non-null esriFolderItem is specified to save a newly-created
// item to the server-side repository or to reference an existing item in it.
outputLayer = new esriFolderItem();
outputLayer.folderType = esriFolderType.esriFolderStoreLayers;
outputLayer.itemName = "storeLayer_ThresholdRings";
outputLayer.workspaceName = "Default Workspace";
outputLayer.projectName = "Default Project";
 
TaskResultOutput storeGeocodeResult =
    baServerHelper.CustomerStoreSetupByGeocodeTable(geocodeParameters, imageOptions, outputOptions, outputLayer);
 
PointLayer storeLayer = new PointLayer();
storeLayer.RecordSet = storeGeocodeResult.RecordSet;
 
// ========= STEP 3: Execute the analysis
 
StdLayer stdLayer = new StdLayer();
stdLayer.ID = "US.BlockGroups";
DataLayer thresholdLayer = new DataLayer();
thresholdLayer.StdLayer = stdLayer;
 
ThresholdRingsParams parameters = new ThresholdRingsParams();
 
// Set specific analysis parameters
parameters.Radii = new double[] { 1000, 3000, 5000 };
parameters.StoreIDField = "STORE_ID";
parameters.Stores = storeLayer;
parameters.SummarizationField = "TOTHH_CY";
parameters.ThresholdData = thresholdLayer;
 
// Set summary report parameters
ReportOptions demoReport = new ReportOptions();
demoReport.ReportFormat = "PDF";
demoReport.TemplateName = "Demographic and Income Report";
parameters.ReportOptions = new ReportOptions[] { demoReport };
 
// Set other parameters
outputOptions = new TaskOutputType[] { TaskOutputType.GetFeatureClass, TaskOutputType.GetReport };
 
// In general, a non-null esriFolderItem is specified to save a newly-created
// item to the server-side repository or to reference an existing item in it.
outputLayer = new esriFolderItem();
outputLayer.folderType = esriFolderType.esriFolderTradeAreas;
outputLayer.itemName = "tradeArea_ThresholdRings";
outputLayer.projectName = "Default Project";
outputLayer.workspaceName = "Default Workspace";
 
// In general, a non-null esriFolderItem is specified to save a newly-created
// item to the server-side repository or to reference an existing item in it.
outputReport = new esriFolderItem();
outputReport.folderType = esriFolderType.esriFolderReports;
outputReport.itemName = "report_ThresholdRings";
outputReport.projectName = "Default Project";
outputReport.workspaceName = "Default Workspace";
 
TaskResultOutput result =
    baServerHelper.ThresholdRings(parameters, imageOptions, outputOptions, outputLayer, outputReport);
 
string reportURL = result.Reports[0].ReportURL;

See Also