Add table from Laura paper

docs/algorithm/subhalo_merger_trees.md

@@ -12,21 +12,36 @@ We provide an example of how this works in practice [in the following page](../e
 
 If one is interested in the evolution of all of the subhaloes that contributed to the build-up of a given subhalo, then its **secondary evolutionary branches** also need to be considered. Identifying secondary evolutionary branches requires connecting disjoint main evolutionary branches, identified by their `TrackId`, at the time when their associated subhaloes first became orphans. HBT-HERONS identifies the descendants of subhaloes that have just become orphans in two different ways, depending on whether [sinking](./subhalo_sinking.md) or [disruption](./unbinding.md) lead to its conversion to an orphan subhalo.
 
+The table below summarises the three scenarios through which a subhalo becomes linked to a descendant, based on the values of `DescendantTrackId`, `SinkTrackId`, `SnapshotOfDeath` and `SnapshotOfSink`. In the conditions column, properties of the subhalo becoming an orphan (the **secondary**) are shown in <span class="merger-orange">orange</span>, and the `TrackId` of the central subhalo it merges into (the **primary**, denoted `TrackId_p`) is shown in <span class="merger-blue">blue</span>. This primary/secondary colour coding matches the figure further below, and each scenario is described in more detail in the sections that follow.
+
+| Merger scenario | Description | Conditions |
+| :--------------- | :----------- | :---------- |
+| **Subhalo disruption** | The subhalo is no longer self-bound; its descendant subhalo contains the majority of its tracer particles. | `DescendantTrackId`{: .merger-orange} == `TrackId_p`{: .merger-blue} &&<br> `SinkTrackId`{: .merger-orange} == -1 &&<br> `SnapshotOfDeath`{: .merger-orange} != -1 &&<br> `SnapshotOfSink`{: .merger-orange} == -1 |
+| **Subhalo sinking** | Two self-bound subhalo cores become indistinguishable in phase-space. | `DescendantTrackId`{: .merger-orange} == `SinkTrackId`{: .merger-orange} == `TrackId_p`{: .merger-blue} &&<br> `SnapshotOfDeath`{: .merger-orange} == `SnapshotOfSink`{: .merger-orange} != -1 |
+| **Unresolved sinking** | An already-disrupted subhalo remnant is later identified as having sunk into another subhalo. | `DescendantTrackId`{: .merger-orange} == `SinkTrackId`{: .merger-orange} == `TrackId_p`{: .merger-blue} &&<br> -1 != `SnapshotOfDeath`{: .merger-orange} < `SnapshotOfSink`{: .merger-orange} != -1 |
+
+The figure below walks through each scenario as a worked example, following a secondary subhalo (`TrackId_s`, orange) as it merges into a primary subhalo (`TrackId_p`, blue) between snapshot 114 ($z=0.2$) and snapshot 127 ($z=0.0$). The snapshot at which the secondary becomes an orphan (`SnapshotOfDeath`) is outlined in red, and the snapshot at which it sinks (`SnapshotOfSink`) is outlined in teal; for subhalo sinking these coincide, since disruption and sinking happen simultaneously.
+
+<figure markdown="span">
+![image_title](../images/algorithm/merger_scenarios.png){ width="1000" }
+<figcaption>Figure credit: Laura Serrano Rodriguez.</figcaption>
+</figure>
+
 We provide an example of how to use the information that HBT-HERONS outputs to find secondary evolutionary branches [in the following page](../examples/merger_trees.md#secondary-progenitors).
 
 ### Disruption descendants
 
 At the beginning of the analysis of each simulation output, HBT-HERONS stores for each resolved subhalo the particle IDs of the `NumTracersForDescendants` most bound tracer particles from the last analysed output. If a subhalo becomes an orphan, HBT-HERONS finds which self-bound subhaloes this set of particles is now bound to.
 
-The descendant subhalo, stored in `DescendantTrackId`, is identified as the `TrackId` that contains the largest share of the tagged tracer particles of the now-orphan subhalo. Note that this may result in `DescendantTrackId = -1` if the largest share of particles are unbound.
+The descendant subhalo, stored in `DescendantTrackId`, is identified as the `TrackId` that contains the largest share of the tagged tracer particles of the now-orphan subhalo. Note that this may result in `DescendantTrackId == -1` if the largest share of particles are unbound.
 
 The subhaloes where this descendant entry should be used can be identified by `SnapshotOfDeath != SnapshotOfSink == -1`, as well as `SnapshotOfSink > SnapshotOfDeath != -1` (see [unresolved sinking](#unresolved-sinking)).
 
 ### Sinking descendants
 
 Subhaloes that are found to overlap in phase-space with the core of another resolved subhalo of `TrackId` store this value as `SinkTrackId`. Contrary to `DescendantTrackId`, the value of `SinkTrackId` can never be `-1`, because sinking needs another existing subhalo to serve as a reference for the phase-space overlap. This means that subhaloes that have sunk can be selected via `SinkTrackId != -1` or `SnapshotOfSink != -1`.
 
-The subhaloes where this descendant entry should be used can be identified by `SnapshotOfDeath = SnapshotOfSink != -1`. Note that HBT-HERONS also computes a `DescendantTrackId` at this time because the subhalo becomes an orphan. The `DescendantTrackId` is the same as `SinkTrackId` in $\approx 99.9\%$ of sinking events, with the discrepant values explained in [unusual descendants](#unusual-descendants).
+The subhaloes where this descendant entry should be used can be identified by `SnapshotOfDeath == SnapshotOfSink != -1`. Note that HBT-HERONS also computes a `DescendantTrackId` at this time because the subhalo becomes an orphan. The `DescendantTrackId` is the same as `SinkTrackId` in $\approx 99.9\%$ of sinking events, with the discrepant values explained in [unusual descendants](#unusual-descendants).
 
 ## Important considerations
 
@@ -42,20 +57,20 @@ For these instances, we recommend using as the subhalo descendant the value prov
 
 ### Unusual descendants
 
-HBT-HERONS tries to assign `DescendantTrackId` when a subhalo first becomes an orphan, including when the orphan is created because of sinking. There are certain cases where no descendant is found (`DescendantTrackId = -1`) or when the descendant is not the same as the `SinkTrackId`.
+HBT-HERONS tries to assign `DescendantTrackId` when a subhalo first becomes an orphan, including when the orphan is created because of sinking. There are certain cases where no descendant is found (`DescendantTrackId == -1`) or when the descendant is not the same as the `SinkTrackId`.
 
 Although we make specific recommendations of which entry to use depending on how the orphan was created (`DescendantTrackId` for disruption and unresolved sinking, and `SinkTrackId` for sinking), we provide a table that gives a rough order of magnitude of how common some of these cases are. Note that the subhalo population used to populate the table is entirely made up of orphans, i.e. `SnapshotOfDeath != -1`.
 
 | <div style="width:75px">Description</div> | <div style="width:70">Mask</div> |<div style="width:100px">Statistics</div> |
 | :-------------------------------------- | :---- | :-------------------------------------------------------------------------------------------------------------- |
-| The subhalo **disrupts** but the majority of its core is not bound to any subhalo. | `DescendantTrackId = -1 &` <br>`SinkTrackId = -1`                                                      | $20\%$ of all orphan subhaloes. |
-| The subhalo **sinks** but the majority of its core is bound to a different subhalo from the one it sunk to. | `DescendantTrackId != SinkTrackId &` <br> `DescendantTrackId != -1 & SinkTrackId != -1`                                                      | $0.01\%$ of all orphan subhaloes. |
-| The subhalo **sinks** but the majority of its core is not bound to any subhalo. | `DescendantTrackId = -1 &`  <br>  `SinkTrackId != -1`                                                      |$0.0001\%$ of all orphan subhaloes.  |
+| The subhalo **disrupts** but the majority of its core is not bound to any subhalo. | `DescendantTrackId == -1 &&` <br>`SinkTrackId == -1`                                                      | $20\%$ of all orphan subhaloes. |
+| The subhalo **sinks** but the majority of its core is bound to a different subhalo from the one it sunk to. | `DescendantTrackId != SinkTrackId &&` <br> `DescendantTrackId != -1 && SinkTrackId != -1`                                                      | $0.01\%$ of all orphan subhaloes. |
+| The subhalo **sinks** but the majority of its core is not bound to any subhalo. | `DescendantTrackId == -1 &&`  <br>  `SinkTrackId != -1`                                                      |$0.0001\%$ of all orphan subhaloes.  |
 
 ### Re-resolving orphans
 
 Orphan subhaloes can re-appear as resolved subhaloes in HBT-HERONS. This happens if the only subhalo in a FoF group is an orphan subhalo, because it is designated as the central subhalo of the halo. All particles in the FoF are consequently added to the source of the orphan subhalo, and if they are found to be self-bound, the orphan is re-classified as a resolved subhalo.
 
 This means that some subhaloes, typically those close to the resolution limit of the simulation, may re-appear (and disrupt) several times throughout the simulation. When a orphan subhalo becomes a resolved subhalo again, the entries associated to the disappearance of the subhalo (e.g. `SnapshotOfDeath`, `SnapshotOfSink`) are reset to a value of `-1`.
 
-The choice of allowing orphan subhaloes to re-appear under these conditions is a preferable approach to the alternative of spawning a completely new subhalo in the halo. Doing so would lead to the creation of many short-lived subhaloes with disjoint evolutionary branches, even if the underlying overdense region is the same.
+The choice of allowing orphan subhaloes to re-appear under these conditions is a preferable approach to the alternative of spawning a completely new subhalo in the halo. Doing so would lead to the creation of many short-lived subhaloes with disjoint evolutionary branches, even if the underlying overdense region is the same.

docs/stylesheets/extra.css

@@ -0,0 +1,15 @@
+[data-md-color-scheme="default"] .merger-orange {
+  color: #b35900;
+}
+
+[data-md-color-scheme="default"] .merger-blue {
+  color: #1a5fb4;
+}
+
+[data-md-color-scheme="slate"] .merger-orange {
+  color: #f2a65a;
+}
+
+[data-md-color-scheme="slate"] .merger-blue {
+  color: #7aa2f7;
+}

mkdocs.yml

@@ -45,6 +45,9 @@ markdown_extensions:
   - md_in_html
   - pymdownx.blocks.caption
 
+extra_css:
+  - stylesheets/extra.css
+
 # For Latex equations
 extra_javascript:
   - javascripts/config.js