DesireLines Method

Creates desire lines (spider diagrams) drawn from every customer to associated store location.

Availability: Business Analyst Server.

TaskResultOutput DesireLines ( 
    DesireLinesParameters  Parameters, 
    RenderingParameters    RenderingParameters, 
    TaskOutputType[]       OutputTypes, 
    esriFolderItem         OutputAnalysisItem 
);

Parameter Description

Parameters Configuration options for analysis. Type DesireLinesParameters.

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) and creating a feature layer for subsequent analysis (GetFeatureClass). 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.

Parameter	Description
Parameters	Configuration options for analysis. Type DesireLinesParameters.
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) and creating a feature layer for subsequent analysis (GetFeatureClass). 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.

Returns

Variable of type TaskResultOutput

Remarks

Desire lines, or spider diagrams, are a series of rays drawn from each customer to the associated store location.

There are three ways to generate desire lines:

Euclidean or straight-line distance
Drive time
Drive distance

Desire lines can be used in following cases:

A lawn and garden operation uses desire lines to adjust advertising expenditures by visualizing the greater draw toward expanding suburbs and a more limited reach towards the inner city. New locations are assigned accordingly.
A national home improvement and builder supply operation maps weekday and weekend desire lines to better understand variations in these market segments.
A convenience store and gas chain creates desire lines based on the Affinity card data to examine the impact of new, suburban locations on older, highway-oriented stores. Older, marginal operations are closed when excessive cannibalization can be seen.
A multi-store dry cleaning and laundry operation uses customer addresses and the time of day, going to work versus travelling to home, to visualize customer travel patterns.
Large supermarket chains use desire lines weighted by sales to analyze the effect of distance on expenditures per visit.
A retailer uses desire lines to identify weekday versus weekend shoppers. The resulting analysis can be used to identify consumer behavior and shopping patterns. For example, weekday shoppers travel less distance than weekend shoppers.

Usage Tips

In most cases, the input store and customer layers will be Business Analyst layers.
The store and customer layers must be point layers.
Creating desire lines using drive time and drive distance will take significantly longer than using the straight-line (Euclidean) distance method.
Use the AssignCustomersByClosestStore or AssignCustomersByTradeArea methods if your customers are not assigned to a store location.

Examples

The example below generates desire lines between a list of stores and a list of customers associated with each store. Also, the store layer, the customer layer, and the desire lines analysis result layer are all saved to the repository.

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 RenderingParameters imageOptions; TaskOutputType[] outputOptions; esriFolderItem outputLayer; // ========= STEP 1: Create a record set by store addresses RecordSetByAddress[] storeAddresses = new RecordSetByAddress[2]; storeAddresses[0] = new RecordSetByAddress(); storeAddresses[0].Name = "location1"; storeAddresses[0].Description = "Downtown Location"; storeAddresses[0].StoreID = "1"; storeAddresses[0].Address = "1401 Kettner Blvd."; storeAddresses[0].City = "San Diego"; storeAddresses[0].State = "CA"; storeAddresses[0].ZIP = "92101"; storeAddresses[1] = new RecordSetByAddress(); storeAddresses[1].Name = "location2"; storeAddresses[1].Description = "Clairemont Location"; storeAddresses[1].StoreID = "2"; storeAddresses[1].Address = "5407 Balboa Ave."; storeAddresses[1].City = "San Diego"; storeAddresses[1].State = "CA"; storeAddresses[1].ZIP = "92111"; TaskResultOutput storeRecordSetResult = baServerHelper.CreateRecordSetByAddresses(storeAddresses, esriFolderType.esriFolderStoreLayers); TableData tableData = new TableData(); tableData.RecordSet = storeRecordSetResult.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_DesireLines"; 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: Create a record set by customer addresses RecordSetByAddress[] customerAddresses = new RecordSetByAddress[7]; customerAddresses[0] = new RecordSetByAddress(); customerAddresses[0].Name = "customer1"; customerAddresses[0].Description = "Ocean Beach Customer"; customerAddresses[0].StoreID = "1"; customerAddresses[0].Address = "5080 Newport Ave."; customerAddresses[0].City = "San Diego"; customerAddresses[0].State = "CA"; customerAddresses[0].ZIP = "92107"; customerAddresses[0].CustomerID = "1"; customerAddresses[1] = new RecordSetByAddress(); customerAddresses[1].Name = "customer2"; customerAddresses[1].Description = "La Jolla Customer"; customerAddresses[1].StoreID = "1"; customerAddresses[1].Address = "1250 Prospect St."; customerAddresses[1].City = "La Jolla"; customerAddresses[1].State = "CA"; customerAddresses[1].ZIP = "92037"; customerAddresses[1].CustomerID = "2"; customerAddresses[2] = new RecordSetByAddress(); customerAddresses[2].Name = "customer3"; customerAddresses[2].Description = "Pacific Beach Customer"; customerAddresses[2].StoreID = "1"; customerAddresses[2].Address = "1762 Garnet Ave."; customerAddresses[2].City = "San Diego"; customerAddresses[2].State = "CA"; customerAddresses[2].ZIP = "92109"; customerAddresses[2].CustomerID = "3"; customerAddresses[3] = new RecordSetByAddress(); customerAddresses[3].Name = "customer4"; customerAddresses[3].Description = "Morena Customer"; customerAddresses[3].StoreID = "2"; customerAddresses[3].Address = "1240 W. Morena Blvd."; customerAddresses[3].City = "San Diego"; customerAddresses[3].State = "CA"; customerAddresses[3].ZIP = "92111"; customerAddresses[3].CustomerID = "4"; customerAddresses[4] = new RecordSetByAddress(); customerAddresses[4].Name = "customer5"; customerAddresses[4].Description = "Clairemont Customer"; customerAddresses[4].StoreID = "2"; customerAddresses[4].Address = "6393 Balboa Ave."; customerAddresses[4].City = "San Diego"; customerAddresses[4].State = "CA"; customerAddresses[4].ZIP = "92111"; customerAddresses[4].CustomerID = "5"; customerAddresses[5] = new RecordSetByAddress(); customerAddresses[5].Name = "customer6"; customerAddresses[5].Description = "Bird Rock Customer"; customerAddresses[5].StoreID = "2"; customerAddresses[5].Address = "5735 La Jolla Blvd."; customerAddresses[5].City = "La Jolla"; customerAddresses[5].State = "CA"; customerAddresses[5].ZIP = "92037"; customerAddresses[5].CustomerID = "6"; customerAddresses[6] = new RecordSetByAddress(); customerAddresses[6].Name = "customer7"; customerAddresses[6].Description = "University City Customer"; customerAddresses[6].StoreID = "1"; customerAddresses[6].Address = "3254 Governor Dr."; customerAddresses[6].City = "San Diego"; customerAddresses[6].State = "CA"; customerAddresses[6].ZIP = "92122"; customerAddresses[6].CustomerID = "7"; TaskResultOutput customerRecordSetResult = baServerHelper.CreateRecordSetByAddresses(customerAddresses, esriFolderType.esriFolderCustomerLayers); tableData = new TableData(); tableData.RecordSet = customerRecordSetResult.RecordSet; geocodeData = new GeocodeData(); geocodeData.Table = tableData; // ========= STEP 4: Geocode the record set with customers geocodeParameters = new CustomerStoreSetupByGeocodeTableParameters(); // Set specific analysis parameters geocodeParameters.GeocodeCustomers = true; geocodeParameters.GeocodeData = geocodeData; geocodeParameters.LinkField = "STORE_ID"; geocodeParameters.NameField = "NAME"; // 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.esriFolderCustomerLayers; outputLayer.itemName = "customerLayer_DesireLines"; outputLayer.workspaceName = "Default Workspace"; outputLayer.projectName = "Default Project"; TaskResultOutput customerGeocodeResult = baServerHelper.CustomerStoreSetupByGeocodeTable(geocodeParameters, imageOptions, outputOptions, outputLayer); PointLayer customerLayer = new PointLayer(); customerLayer.RecordSet = customerGeocodeResult.RecordSet; // ========= STEP 5: Execute the analysis DesireLinesParameters parameters = new DesireLinesParameters(); // Set specific analysis parameters parameters.CalculationMethod = esriDistanceCalcType.esriDistanceCalcTypeStraightLine; parameters.CustomerLinkField = "STORE_ID"; parameters.Customers = customerLayer; parameters.DistanceUnits = esriUnits.esriMiles; parameters.StoreIDField = "STORE_ID"; parameters.Stores = storeLayer; // 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.esriFolderAnalyses; outputLayer.itemName = "analysisLayer_DesireLines"; outputLayer.projectName = "Default Project"; outputLayer.workspaceName = "Default Workspace"; TaskResultOutput result = baServerHelper.DesireLines(parameters, imageOptions, outputOptions, outputLayer);

Returns

Remarks

Usage Tips

Examples

See Also