sDNA_GH components all have an associated tool (apart from a few special ones, e.g. Config). As one would expect, sDNA components run those sDNA tools of the same name. But components can run any number of tools, and other components' tools (*). These tools are callable class instances, abstractions of ordinary Python functions.
sDNA tools expect to receive a raw input shape file, and output a shapefile, exactly as if they were used on the command line.
To run sDNA with Grasshopper geometry, other tools must be run before and afterwards. For convenience, by default two special options, auto_write_Shp and auto_read_Shp are true. With these settings, sDNA components will accept Grasshopper Geometry and output Grasshopper Geometry, and the two extra support tools Write_Shp and Read_Shp handle the writing and reading of the shapefiles.
To work directly with a shapefile in sDNA_GH, auto_write_Shp should be set to false, so that the sDNA component doesn't first try to write a shapefile for sDNA when a shapefile is already available. Only automatically generated temporary shapefiles are deleted after a tool using it has finished.
Rhino polylines should be imported into Grasshopper with Read_Geom. This is necessary to get the actual UUIDs of the Rhino objects in the object table (not just Grasshopper references).
Text and weights can be stored on Rhino objects as User Text. Using the real references to Rhino polylines from Read_Geom, the Read_Usertext tool can read the Geom and output the Usertext keys and values as a Data Tree in Data. If compute_vals is true, substrings in User Text values such as %<CurveLength( ... )>% are expanded.
As expected, Write_Shp writes polylines to shapefiles. But to allow round tripping of GIS networks, it is now also able to write Degree 1 Nurbs curves to POLYLINEZ shapefiles. To write weights and text to a Shapefile attribute table, e.g. for sDNA, Data must be supplied to a Write_Shp tool, either in its own component or in an sDNA one with auto_write_Shp set to True. Data is automatically in the correct format from Read_Usertext. Read_Usertext will read everything it can find into a Data Tree, but Write_Shp will only write data associated with Usertext keys to a shapefile that match input_key_str. By default this ("{name}") matches everything. But different values can be useful for filtering or using longer Usertext key names than the 10 ascii character maximum length of shapefile field names.
Adding a separate Read_Usertext component can be avoided, by setting auto_read_User_Text to true. The Read_Usertext tool must still be run to achieve this, as that tool is where the code to do this task lives. However that tool (or any other tool) does not have to be run using its component of the same name, if there is an auto rule that will run it for them as part of another component (or if they add that tool to a name_map workflow themselves).
sDNA results, or any POLYLINE shapefile's geometry and associated data, can be read using the Read_Shp tool (either via its own component, or from an sDNA component with auto_read_Shp = true). Shapes can be baked into Rhino straight away by setting bake to true. Otherwise if no Geom was inputted to associate with the shapefile data, Grasshopper Polylines are outputted in Geom.
Rhino has particular rules for what counts as a valid Polyline. Many line-strings from GIS sources, e.g. OSM are invalid by these rules. If attempts to add a polyline from a shapefile of polylines fails, Read_Shp then adds a Degree 1 Nurbs Curve (which Rhino is more lenient towards than Polylines). If the attempt to add a Degree 1 Nurbs Curve fails, an error is raised. If ignore_invalid is set to True, this error is stopped, and data about the curve in the shapefile, including its number in the file, and why it is invalid is outputted in invalid.
Data associated with the (new or old) shapes can be automatically plotted from Read_Shp component by setting auto_plot_data to true. This runs the Recolour_Objects tool, which itself if given raw data will run Parse_Data on it first. To pick custom colours, e.g. a gradient component can be placed between a Parse Data Component and a Recolour Object component. This also allows tinkering with the plotting settings, without having to rerun a large sDNA analysis or reparse the Data Tree for each setting. Parse Data accepts overrides for class boundaries and legend tag names. The Grasshopper Legend component accepts overrides for the tags, rectangular legend frame and even the colours too.
Results and other shapefile data can be saved as Usertext on Rhino objects, using the Write_Usertext tool. Object references from Read_Geom or from Read_Shp with bake = True are required to get references to the actual Rhino objects. Write_Usertext avoids overwriting previous Usertext by time stamping the keys using the template defined in output_key_str (by default 'sDNA output={name} run time={datetime}'). overwrite_UserText can also be set to false to stop this, which will append a suffix to the keys.
(*) By adding a nick name to the name map, it's straightforward to create a custom component to run any sequence of sDNA_GH tools desired. Any standard sDNA_GH component given that name map in its options, that is renamed to that nick name, will run that sequence. This is faster and more efficient overall than using separate components, as the geometry and data trees don't have to be reconverted and reparsed to go from one Iron Python process, to Grasshopper and back to a second Iron Python process, between each component. Every tool in the same component can just use the same data and geometry in RAM. But all the tools in the same component will be rerun each time a solution for it is recomputed.