7. Guide to individual tools

7.1. Options common to multiple tools

Several tools share the following parameters:

• Input, Output

  Shape layers for input and output

• Start grade separation, End grade separation

  Select fields for grade separation. If given, links will only be deemed connected if

  1. they share the same endpoints (x,y,z)
  2. they share the same grade separation value at those endpoints

  Grade separation can also be used to emulate multilayer/multimode networks. For example, use values of 0,1,2... for grade separation on roads, 10,11,12... for railways, etc.

• Analysis Metric

  Select metric for analysis: Euclidean, angular, custom, hybrid, other (see Distance Metric for details).

  Custom metrics require selection of a custom metric data field.

  If using hybrid metrics, the formula must be provided in advanced_config using the lineformula and juncformula keywords.

  Other metrics (such as cycle, pedestrian, vehicle) are preset forms of hybrid metric. You can inspect the message output of sDNA to discover exactly what formula they use. Some presets include variables, e.g. for the tendency of cyclists to avoid vehicle traffic. These can be set to different values in advanced config; see preset metric variables.

  Hybrid and preset metrics require sDNA+.

• Weighting, Origin weight, Destination weight

  Select Weighting (link, length or polyline) and the data to use. Standard sDNA will allow the same data to be set for origin and destination weights; using different weights for origin and destination requires sDNA+.

• Radii

  Enter one or more radii to use as radius of analysis (see Radius for details). These are expressed in the spatial units of the data, which should usually be metres if your data is projected correctly. If entering several, separate them by commas. Radius ‘n’ can be used to specify global analysis, limited only by the size of the network (but computationally intensive). Example: 100, 200, 400, 800, 1600, n

• Continuous space

  Select whether Continuous space_ analysis is used.

• Disable lines

  Allows discarding of certain polylines from the analysis. This is useful for testing multiple design options, or for switching on and off parts of the network such as cycle paths.

  This parameter takes an expression_ which, if it evaluates to a nonzero result for a given polyline, will disable that polyline. In the simplest case, this can be a field name such as walk_net (which would disable all lines for which the walk_net field is nonzero) or a combination such as walk_net||cycle_net (which would disable both the walking and cycling network - useful for a vehicle analysis).

• Advanced config

  Allows setting of parameters not shown in the interface. These are described in advanced_config.

7.2. Individual tool details

Preparation

Prepare network

Prepares spatial networks for analysis by checking and optionally repairing various kinds of error:

• endpoint near misses (XY and Z tolerance specify how close a near miss)
• duplicate lines
• traffic islands (requires traffic island field set to 0 for no island and 1 for island). Traffic island lines are straightened; if doing so creates duplicate lines then these are removed.
• split links. Note that fixing split links is no longer necessary as of sDNA 3.0 so this is not done by default
• isolated systems

See Options common to multiple tools.

Optionally, numeric data can be preserved through a prepare operation by providing the desired field names, separated by commas, to the parameters Absolute data to preserve and Unit length data to preserve. (Requires sDNA+).

Individual Line Measures

Outputs connectivity, bearing, euclidean, angular and hybrid metrics for individual polylines.

This tool can be useful for checking and debugging spatial networks. In particular, connectivity output can reveal geometry errors.

See Options common to multiple tools.

Analysis

Integral Analysis

sDNA Integral is the core analysis tool of sDNA. It computes several flow, accessibility, severance and efficiency measures on networks. Full details of the analysis are given in Analysis: what the results mean and Analysis: full specification.

Integral allows output of various groups of measures to be switched on and off.

See Options common to multiple tools.

Accessibility Map

Outputs accessibility maps for specific origins. (Requires sDNA+).

See Options common to multiple tools.

The accessibility map tool also allows a list of origin polyline IDs to be supplied (separated by commas). Leave this parameter blank to output maps for all origins.

If outputting “maps” for multiple origins, these will be output in the same feature class as overlapping polylines. It may be necessary to split the result by origin link ID in order to display results correctly.

Geometries

The geometry tools output individual geometries used in an integral analysis. These may be useful either for visualization, or for exporting to external analysis tools. For example, you could join geodesics to a pollution dataset to estimate exposure to pollution along everyday travel routes.

Convex Hulls

Outputs the convex hulls of network radii used in Integral Analysis. (Requires sDNA+).

See Options common to multiple tools.

The convex hulls tool also allows a list of origin polyline IDs to be supplied (separated by commas). Leave this parameter blank to output hulls for all origins.

Geodesics

Outputs the geodesics (shortest paths) used by Integral Analysis. (Requires sDNA+).

See Options common to multiple tools.

The geodesics tool also allows a list of origin and destination polyline IDs to be supplied (separated by commas). Leave the origin or destination parameter blank to output geodesics for all origins or destinations. (Caution: this can produce a very large amount of data).

Network Radii

Outputs the network radii used in Integral Analysis. (Requires sDNA+).

See Options common to multiple tools.

The network radii tool also allows a list of origin polyline IDs to be supplied (separated by commas). Leave this parameter blank to output radii for all origins.

Calibration

sDNA Learn and Predict provide a way to calibrate sDNA outputs against measured variables (flows, house prices, etc). Currently they offer bivariate regression with Box-Cox transformation. Multiple predictor variables (the outputs of sDNA) can be tested to see which gives the best cross-validated correlation with the target variable.

Learn

sDNA Learn selects (and optionally saves) the best model for predicting a target variable.

Candidate predictor variables can either be entered as field names separated by commas, or alternatively as a regular expression. The latter follows Python regex syntax. A wildcard is expressed as .*, thus, Bt.* would test all Betweenness variables (which in abbreviated form begin with Bt) for correlation with the target.

Box-Cox transformations can be disabled, and the parameters for cross-validation can be changed.

If an output model file is set, the best model is saved and can be applied to fresh data using sDNA Predict.

Predict

Predict takes an output model file from sDNA Learn, and applies it to fresh data. For example, suppose we wish to calibrate a traffic model, using measured traffic flows at a small number of points on the network.

• First run a Betweenness analysis at a number of radii using Integral Analysis.
• Use a GIS spatial join to join Betweenness variables (the output of Integral) to the measured traffic flows.
• Run Learn on the joined data to select the best variable for predicting flows (where measured).
• Run Predict on the output of Integral to estimate traffic flow for all unmeasured polylines.

7.3. Advanced configuration and command line options

sDNA supports a wide variety of options for customizing the analysis beyond what is shown in the user interface. All of these are accessed through the advanced config system.

Advanced config options are specified in a long string with options separated by semicolons (;) like this:

nohull;probroutethreshold=1.2;skipzeroweightorigins

This is an example of an advanced config for sDNA Integral, which means

• Don’t compute convex hull
• Problem route threshold = 1.2
• Skip zero weight origins

When calling sDNA Integral Analysis and Prepare Network from the command line (Using sDNA from the command line), the entire configuration is specified as an advanced config. Therefore, the advanced config options include some which are usually set via the graphical interface. If these options are given as advanced config in the sDNA graphical interface, an error (“Keyword specified multiple times”) will result.

Advanced config options for sDNA Prepare

Option	Description	sDNA	sDNA+
startelev=	Name of field to read start elevation from	Yes	Yes
endelev=	Name of field to read end elevation from	Yes	Yes
island=	Name of field to read traffic island information from. Anything other than zero will be treated as traffic island	Yes	Yes
islandfieldstozero=	Specifies additional data fields to set to zero when fixing traffic islands (used for e.g. origin or destination weights)	No	Yes
data_unitlength=	Specifies numeric data to be preserved by sDNA prepare (preserves values per unit length, averages when merging links)	No	Yes
data_absolute=	Specifies numeric data to be preserved by sDNA prepare (preserves absolute values, sums when merging links)	No	Yes
xytol=	Manual override xy tolerance for fixing endpoint connectivity	Yes	Yes
ztol=	Manual override z tolerance for fixing endpoint connectivity	No	Yes

xytol and ztol are manual overrides for tolerance. sDNA, running on geodatabases from command line or ArcGIS, will read tolerance values from each feature class as appropriate. sDNA running in QGIS or on shapefiles will use a default tolerance of 0, as shapefiles do not store tolerance information:- manual override is necessary to fix tolerance on shapefiles.

Advanced config options for sDNA Integral and geometry tools

sDNA Convex Hulls, Network Radii, Geodesics and Accessibility Map are all different interfaces applied to sDNA Integral, so will in some cases accept these options as well.

Option	Default	Description	sDNA	sDNA+
startelev=		Name of field to read start elevation from	Yes	Yes
endelev=		Name of field to read end elevation from	Yes	Yes
metric=	angular	Metric – angular, euclidean, custom or hybrid (see next section)	Yes	Yes
radius=	n	List of radii separated by commas	Yes	Yes
startelev=		Name of field to read start elevation from	Yes	Yes
endelev=		Name of field to read end elevation from	Yes	Yes
weight=		Name of field to read weight from. Applies weight field to both origins and destinations.	Yes	Yes
lenwt		Specifies that weight field is per unit length	Yes	Yes
custommetric=		Specified field name to read custom metric from	Yes	Yes
xytol=		Manual override xy tolerance for fixing endpoint connectivity.	Yes	Yes
ztol=		Manual override z tolerance for fixing endpoint connectivity.	No	Yes
outputgeodesics		Output geometry of all pairwise geodesics in analysis (careful – this can create a lot of data)	No	Yes
outputdestinations		Output geometry of all pairwise destinations in analysis (careful – this can create a lot of data). Useful in combination with origins for creating a map of distance/metric from a given origin.	No	Yes
outputhulls		Output geometry of all convex hulls in analysis	No	Yes
outputnetradii		Output geometry of all network radii in analysis	No	Yes
origins=		Only compute selected origins (provide feature IDs as comma separated list). Useful in conjunction with outputgeodesicsm, outputdestinations, outputhulls, outputnetradii.	No	Yes
destinations=		Only compute selected destinations (ditto)	No	Yes
nonetdata		Don’t output any network data (used in conjunction with geometry outputs)	No	Yes
pre=		Prefix text of your choice to output column names	Yes	Yes
post=		Postfix text of your choice to output column names	Yes	Yes
nobetweenness		Don’t calculate betweenness (saves a lot of time)	Yes	Yes
nojunctions		Don’t calculate junction measures (saves time)	Yes	Yes
nohull		Don’t calculate convex hull measures (saves time)	Yes	Yes
linkonly		Only calculate individual link measures.	Yes	Yes
outputsums		Output sum measures SAD, SCF etc as well as means MAD, MCF etc.	Yes	Yes
probroutes		Output measures of problem routes – routes which exceed the length of the radius	No	Yes
forcecontorigin		Force origin link to be handled in continuous space, even in a discrete analysis. Prevents odd results on very long links.	Yes	Yes
nqpdn=	1	Custom numerator power for NQPD equation	No	Yes
nqpdd=	1	Custom denominator power for NQPD equation	No	Yes
skipzeroweightorigins		Skips calculation of any output measures for origins with zero weight. Saves a lot of time if many such origins exist.	No	Yes
skipzeroweightdestinations	1	Zero weight destinations are skipped by default. Note this will exclude them from geometry outputs; if this is not desired behaviour then set skipzeroweightdestinations=0	No	Yes
skiporiginifzero=		Specified field name. If this field is zero, the origin will be skipped. Allows full customization of skipping origins.	No	Yes
skipfraction=	1	Set to value n, skips calculation for (n-1)/n origins. Effectively the increment value when looping over origins.	No	Yes
skipmod=	0	Chooses which origins are calculated if skipfraction?1. Effectively the initial value when looping over origins: every skipfractionth origin is computed starting with the skipmodth one.	No	Yes
nostrictnetworkcut		Don’t constrain geodesics to stay within radius. This will create a lot more ‘problem routes’. Only alters behaviour of betweenness measures (not closeness).	No	Yes
probrouteaction=	ignore	Take special action for problem routes that exceed the radius by a factor greater than probroutethreshold. Can be set to ignore, discard or reroute. Reroute changes geodesic to shortest Euclidean path. Only alters betweenness output, not closeness.	No	Yes
probroutethreshold=	1.2	Threshold over which probrouteaction is taken. Note this does not affect computation of probroutes measures, which report on all routes which exceed the radius length regardless of this setting.	No	Yes
outputdecomposableonly		output only measures which are decomposable i.e. can be summed over different origins (useful for parallelization)	No	Yes
linkcentretype=	Angular for angular analysis, Euclidean otherwise	Override link centre types – angular or Euclidean	No	Yes
linkformula=		Formula for link metric in hybrid analysis (see below)	No	Yes
juncformula=	0	Formula for junction turn cost in hybrid analysis (see below)	No	Yes
ignorenonlinear		Force sDNA to proceed even if linkformula is nonlinear (see below)	No	Yes
bidir		Output betweenness for each direction separately	No	Yes
oneway=		Specified field name to read one way data from (see note 1 below)	No	Yes
vertoneway=		Specified field name to read vertical one way data from (see note 1 below)	No	Yes
oversample=	1	Number of times to run the analysis; results given are the mean of all runs. Useful for sampling hybrid metrics with random components.	No	Yes

Preset metric variables

A number of preset metrics are provided for different urban forms of transport (currently cycle, pedestrian and vehicle). These are special cases of hybrid metrics, sometimes with a fairly complex formula. To inspect the formula for a given metric, run Individual Line Measures with the metric selected, and inspect the message output where the full formula will be shown.

Certain variables within the preset metric formulae can be changed by assigning to them in advanced config. To date, the list is:

Metric	Variable	Default	Meaning
Vehicle	jp	0	Tendency of drivers to avoid junctions
Vehicle	a	1	Tendency of drivers to avoid angular change
Pedestrian	a	0.5	Blend of angular and Euclidean metric: 0 for full Euclidean, 1 for full Angular
Cycle	aadtfield	aadt	Name of data field containing annual average daily vehicle traffic estimate
Cycle	t	0.04	Tendency of cyclists to avoid vehicle traffic
Cycle	a	0.3	Tendency of cyclists to avoid angular change
Cycle	s	0.5	Tendency of cyclists to avoid slope

Interpretation of one way data

One way data is interpreted as follows:

• 0 – traversal allowed in both directions (so long as vertoneway allows this too)
• positive number – forward traversal only
• negative number – backward traversal only

Forwards/backwards are taken with respect to the direction in which the link is drawn in the network (ordering of points in the data).

Vertical one way data is interpreted as follows:

• 0 – traversal allowed in both directions (so long as oneway allows this too)
• positive number – upward traversal only
• negative number – downward traversal only

Upward/downward are deduced by measuring the endpoints of the link only. In the event that these have the same elevation/height and this leads to ambiguity, sDNA will print an error message and exit.

If conflicting oneway and vertoneway data are provided, sDNA will print an error message and exit. Note that if either field is zero, the other is permitted to override it without conflict.

Hybrid analysis

Tutorial

In hybrid analysis, custom formulae can be given in advanced config for the evaluation metric of (partial) links and junctions. Here are some examples of advanced configs that specify hybrid analysis.

To simulate Euclidean analysis, assign links a metric equal to their Euclidean length. Junctions receive metric of 0 by default:

lineformula=euc

To simulate angular analysis, both links and junctions have a metric equal to their angular change:

lineformula=ang; juncformula=ang

A mixture of the two. Links have a metric of their Euclidean distance plus twice their angular change; junctions get 3 times the angular change:

lineformula=euc+2*ang; juncformula=3*ang

Topological analysis – counting only the number of junctions and ignoring length and angularity:

lineformula=0; juncformula=1

The formulae used by lineformula and junctionformula are much like those in any spreadsheet or programming language (see Reference). Crucially you have access to the following variables:

Variable	Meaning	Available for links	Available for junctions
ang	Angular change	Yes	Yes
euc	Euclidean distance	Yes	No
hg	Height gain	Yes	No
hl	Height loss	Yes	No
FULLang	Angular change for entire line	Yes	No
FULLeuc	Euclidean distance for entire line	Yes	No
FULLhg	Height gain for entire line	Yes	No
FULLhl	Height loss for entire line	Yes	No
fwd	True if you are traversing this line forwards, false if backwards	Yes	No

(Forwards/Backwards have no physical meaning but are defined by the orientation of the polyline in your network data.)

You also have access to any custom numeric data attached to your input network. So for example if you had a field on your input data called travel_time, then you might write:

lineformula=travel_time (WRONG!)

But while possible, this is not a good formula to use: sDNA would return an error saying the formula is not linear!

The reason for this is that sDNA’s continuous space algorithm does not necessarily evaluate the formula for a whole polyline at once, so at any time, the formula might be applied to a partial line. So, let’s say the travel_time for a given line is 1 minute. If the above formula were to be evaluated once, the metric for that line would be 1 minute, which is correct. But if sDNA breaks the link into two parts and evaluates each part separately, the metric will be 2 minutes – which is clearly wrong. So here is one solution to the problem:

lineformula=euc/FULLeuc*travel_time

The above formula assumes travel time is distributed evenly along the link length, calculates the proportion the link we are currently processing (euc/FULLeuc) and multiplies that by travel_time so that no matter how the link is divided inside sDNA, the metric for the full link will always be the same.

Formally, the requirement for lineformula as a function is that it is linear with respect to breaking down any given link L into arbitrary parts of links x and y

\[F(x) + F(y) = F(x + y)\]

Inspired by this, you might like to try distributing your custom travel time along the angular changes in a link instead of its length:

lineformula=ang/FULLang*travel_time (WRONG!)

This time sDNA fails during computation. The reason would be that some links are totally straight lines, and these have no angular cost. Thus ang and FULLang are both zero, and zero divided by zero is not a number. We need another way to handle the case of straight links. How about distributing travel time down the link’s angular change normally, but if there is no angular change, then distributing down its length?:

lineformula=(FULLang!=0)?ang/FULLang*travel_time:euc/FULLeuc*travel_time

Notice that last formula introduced () brackets, != inequality, and :? the if-then-else ternary operator.

The same formula can be simplified a little by using a temporary variable:

lineformula= _p=(FULLang!=0)?ang/FULLang:euc/FULLeuc , _p*travel_time

Any variable beginning with an underscore _, is assumed to be temporary (not present on the input data). So in the above example we first set _p to represent the proportion of the link we were processing, then we output a value of _p times travel_time. These two operations were separated by a comma ,. This may seem like a minor improvement, but as formulae get more complicated, it helps.

Reference

Operator (in reverse order of precedence)	Name	Example	Meaning
,	Statement separator	a,b,c	Do a, then b, then output c
=	Assignment	_a=b	Set _a equal to b
?:	If-then-else	p?x:y	If p then x else y
&&	Logical and	a&&b	a and b
||	Logical or	a||b	a or b
<=	Less than or equal	a<=b	a is less than or equal to b
>=	Greater than or equal	a>=b	a is greater than or equal to b
!=	Not equal	a!=b	a is not equal to b
==	Equal	a==b	a is equal to b
>	Greater than	a>b	a is greater than b
<	Less than	a<b	a is less than b
+	Addition	a+b	a plus b
-	Subtraction	a-b	a minus b
*	Multiplication	a*b	a times b
/	Division	a/b	a divided by b
^	Exponentiation	a^b	a to the power of b
()	Parentheses	2*(x+1)	add one to x then multiply by 2

Builtin functions
sin(x), cos(x), tan(x) asin(x), acos(x), atan(x) sinh(x), cosh(x), tanh(x) asinh(x), acosh(x), atanh(x)	Trigonometric functions of x (in radians).
log2(x)	Logarithm of x base 2
log10(x), log(x)	Logarithm of x base 10
ln(x)	Logarithm of x base e
exp(x)	e to the power of x
sqrt(x)	Square root of x
sign(x)	-1 if x is negative, else 1
rint(x)	x rounded to nearest integer
abs(x)	Absolute value of x
min(a,b,c,…) max(a,b,c,…) sum(a,b,c,…) avg(a,b,c,…)	Minimum, maximum, sum and average of all arguments
trunc(x,l,u)	Truncate x to the range [l,u] (including endpoints)
randnorm(m,s)	Random number drawn from normal distribution with mean m and standard deviation s
randuni(l,u)	Random number drawn from uniform distribution on range [l,u]

Random numbers are generated from Mersenne Twister mt19937 algorithm. “Mersenne Twister: A 623-dimensionally equidistributed uniform pseudo-random number generator”, Makoto Matsumoto and Takuji Nishimura, ACM Transactions on Modeling and Computer Simulation: Special Issue on Uniform Random Number Generation, Vol. 8, No. 1, January 1998, pp. 3-30.

Constants
inf	infinity
pi	pi

Variables
ang	Angular change
euc	Euclidean distance
hg	Height gain
hl	Height loss
FULLang	Angular change for entire link
FULLeuc	Euclidean distance for entire link
FULLhg	Height gain for entire link
FULLhl	Height loss for entire link
fwd	True if you are traversing this link forwards, false if backwards
_x	(where x is any name): Temporary variable (initialized to 0)
x	(where x is any name not used as function or other value): field data on network link

Any variable can be assigned to with =, but the new value will only affect the current formula being evaluated (assigning to ``ang`` will not change the shape of the network, for example!). It is recommended to use only temporary variables of the form ``_x`` as targets for assignment.