<commit_before>Using the connectome visualisation tool
=======================================

The connectome tool bar in *MRtrix3* has been designed from scratch, with
the intention of providing a simple, data-driven mechanism for visually
assessing individual connectomes as well as the results of network-based
group statistics. The interface may therefore vary considerably from
other connectome visualisation packages, and may be intimidating for new
users who simply want to 'see the connectome'. I hope I can convince you
in this tutorial that the design of this tool allows you, the user, to
dictate exactly *how* you want to visualise the connectome, rather than
being forced to conform to a particular prior expectation of how such
things should be visualised.

Initialising the tool
---------------------

My suspicion is that new users will load the tool, and immediately
think: 'Where do I load my connectome?'. Well, let's take a step
backwards. If you were to give the software a connectome matrix, with no
other data, there would be no way to visualise that connectome in the
space of an MR image: the software has no information about the spatial
locations of the nodes upon which that connectome is based. So the first
step is actually to load an image to provide the tool with this
information, using the "Node image" button at the top of the toolbar.
The desired image is the output of the ``labelconvert`` command, as
detailed in the :ref:`struct_connectome_construction` guide: the
tool uses this image to localise each parcel in 3D space in preparation
for visualisation. Alternatively, you can load the relevant parcellation
image from the command-line when you first run ``mrview``, using the
``-connectome.init`` option.

.. ATTENTION::

  If you still do not see anything in the ``mrview`` main window, this is
  likely because you have not yet opened a primary image in ``mrview``. This
  is currently necessary for ``mrview`` to correctly set up the camera
  positioning. The easiest solution is to open your parcellation image not
  only to initialise the connectome tool, but also as a standard image in
  ``mrview``; then simply *hide* the main image using the 'View' menu.

With the basis parcellation image loaded, the tool will display the
location of each node; note however that all of the nodes are exactly
the same colour, and exactly the same size, and there are no connections
shown between them - it's an entirely dis-connected network. This makes
sense - we haven't actually provided the tool with any information
regarding which connections are present and which are absent. We can
also do the opposite: change the "Edge visualisation" - "Visibility"
from 'None' to 'All', and now the software shows every edge in the
connectome non-discriminantly.

Therefore, we need some mechanism of informing the software of which
edges should be drawn, and which should not. Most logically, this could
be achieved by loading a structural connectome, and perhaps applying
some threshold. So now, for the "Edge visualisation" - "Visibility"
option, select "Matrix file", and load your connectome. The software now
uses the data from this external file to threshold which edges are drawn
and which are not, and also allows you to vary that threshold
interactively. (You can also load a connectome matrix from the command
line using the ``-connectome.load`` option.)

The connectome still however has a binary appearance; every edge in the
connectome is either present or absent, and they all have the same size
and the same colour. We know that our connectome contains weights
distributed over a wide scale, and would like to be able to see this as
part of our visualisation; for instance, we may decide that more dense
connections should have a 'hot' colour appearance, whereas less dense
connections should be darker. We can achieve this by changing the "Edge
visualisation" - "Colour" from 'Fixed' to 'Matrix file', and selecting
an appropriate matrix file (perhaps the same file as was used for the
visibility threshold, perhaps not).

For most users, connectome data will be loaded using the
'open' button in the 'connectome matrices' section, or at the command-line
when ``mrview`` is first run using the ``-connectome.load`` option.

Basis of connectome visualisation customisation
-----------------------------------------------

With the above steps completed, you should obtain a fairly rduimentary
visualisation of the connectome you have loaded. The plethora of
buttons and gadgets in the connectome tool user interface is however
a clue regarding the scope of customisation available for precisely
how the connectome data will be displayed.

As an example, consider the 'Edge visualisation - Colour' entry. These
options control how the colour of each individual edge in the connectome
will be determined, based on the data the tool is provided with. Clicking
on the main combo box shows that there are a few options available:

* *Fixed*: Use the same fixed colour to display all visible edges.

* *By direction*: The XYZ spatial offset between the two nodes connected by an
  edge is used to derive an RGB colour (much like the default streamlines
  colouring).<commit_msg>Docs: Connectome tool: Spelling error<commit_after>Using the connectome visualisation tool
=======================================

The connectome tool bar in *MRtrix3* has been designed from scratch, with
the intention of providing a simple, data-driven mechanism for visually
assessing individual connectomes as well as the results of network-based
group statistics. The interface may therefore vary considerably from
other connectome visualisation packages, and may be intimidating for new
users who simply want to 'see the connectome'. I hope I can convince you
in this tutorial that the design of this tool allows you, the user, to
dictate exactly *how* you want to visualise the connectome, rather than
being forced to conform to a particular prior expectation of how such
things should be visualised.

Initialising the tool
---------------------

My suspicion is that new users will load the tool, and immediately
think: 'Where do I load my connectome?'. Well, let's take a step
backwards. If you were to give the software a connectome matrix, with no
other data, there would be no way to visualise that connectome in the
space of an MR image: the software has no information about the spatial
locations of the nodes upon which that connectome is based. So the first
step is actually to load an image to provide the tool with this
information, using the "Node image" button at the top of the toolbar.
The desired image is the output of the ``labelconvert`` command, as
detailed in the :ref:`struct_connectome_construction` guide: the
tool uses this image to localise each parcel in 3D space in preparation
for visualisation. Alternatively, you can load the relevant parcellation
image from the command-line when you first run ``mrview``, using the
``-connectome.init`` option.

.. ATTENTION::

  If you still do not see anything in the ``mrview`` main window, this is
  likely because you have not yet opened a primary image in ``mrview``. This
  is currently necessary for ``mrview`` to correctly set up the camera
  positioning. The easiest solution is to open your parcellation image not
  only to initialise the connectome tool, but also as a standard image in
  ``mrview``; then simply *hide* the main image using the 'View' menu.

With the basis parcellation image loaded, the tool will display the
location of each node; note however that all of the nodes are exactly
the same colour, and exactly the same size, and there are no connections
shown between them - it's an entirely dis-connected network. This makes
sense - we haven't actually provided the tool with any information
regarding which connections are present and which are absent. We can
also do the opposite: change the "Edge visualisation" - "Visibility"
from 'None' to 'All', and now the software shows every edge in the
connectome non-discriminantly.

Therefore, we need some mechanism of informing the software of which
edges should be drawn, and which should not. Most logically, this could
be achieved by loading a structural connectome, and perhaps applying
some threshold. So now, for the "Edge visualisation" - "Visibility"
option, select "Matrix file", and load your connectome. The software now
uses the data from this external file to threshold which edges are drawn
and which are not, and also allows you to vary that threshold
interactively. (You can also load a connectome matrix from the command
line using the ``-connectome.load`` option.)

The connectome still however has a binary appearance; every edge in the
connectome is either present or absent, and they all have the same size
and the same colour. We know that our connectome contains weights
distributed over a wide scale, and would like to be able to see this as
part of our visualisation; for instance, we may decide that more dense
connections should have a 'hot' colour appearance, whereas less dense
connections should be darker. We can achieve this by changing the "Edge
visualisation" - "Colour" from 'Fixed' to 'Matrix file', and selecting
an appropriate matrix file (perhaps the same file as was used for the
visibility threshold, perhaps not).

For most users, connectome data will be loaded using the
'open' button in the 'connectome matrices' section, or at the command-line
when ``mrview`` is first run using the ``-connectome.load`` option.

Basis of connectome visualisation customisation
-----------------------------------------------

With the above steps completed, you should obtain a fairly rudimentary
visualisation of the connectome you have loaded. The plethora of
buttons and gadgets in the connectome tool user interface is however
a clue regarding the scope of customisation available for precisely
how the connectome data will be displayed.

As an example, consider the 'Edge visualisation - Colour' entry. These
options control how the colour of each individual edge in the connectome
will be determined, based on the data the tool is provided with. Clicking
on the main combo box shows that there are a few options available:

* *Fixed*: Use the same fixed colour to display all visible edges.

* *By direction*: The XYZ spatial offset between the two nodes connected by an
  edge is used to derive an RGB colour (much like the default streamlines
  colouring).
{'fraction_non_alphanumeric': 0.060600267635251386, 'fraction_numerical': 0.0003823360734085261, 'mean_word_length': 4.3960804538421865, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1790564', 'n_tokens_mistral': 2474, 'n_tokens_neox': 2400, 'n_words': 1619}