update docs on halo catalogs

docs/halocatalogs.md

@@ -14,6 +14,7 @@ ds = load("TNG50-4_snapshot") # (1)!
 
 The dataset itself passed to load does not possess information about the FoF/Subfind outputs as they are commonly saved in a separate folder or hdf5 file. For typical folder structures of GADGET/AREPO style simulations, an attempt is made to automatically discover and add such information. The path to the catalog can otherwise explicitly be passed to *load()* via the *catalog=...* keyword.
 
+## Accessing halo/galaxy catalog information
 
 Groups and subhalo information is added into the dataset with the data containers *Group* and *Subhalo*. For example, we can obtain the masses of each group as:
 
@@ -22,16 +23,39 @@ Groups and subhalo information is added into the dataset with the data container
 group_mass = ds.data["Group"]["GroupMass"]
 ```
 
+## Accessing particle-level halo/galaxy information
+
 In addition to these two data containers, new information is added to all other containers about their belonging to a given group and subhalo.
 
 ``` py
-groupid = ds.data["PartType0"]["GroupID"]
+groupid = ds.data["PartType0"]["GroupID"] #(1)!
 subhaloid = ds.data["PartType0"]["SubhaloID"]
+localsubhaloid = ds.data["PartType0"]["LocalSubhaloID"]
 ```
 
-In above example, we fetch the virtual dask arrays holding the group and subhalo belonging of each *PartType0* particle. The *groupid* field returns the integer position into the group catalog that given particle belongs to. For the *subhaloid* the subhalo id within a given *groupid* is given, *where subhaloid==0* marks the belonging to the central subhalo in a halo.
+1. This information is also available for the other particle types.
+
+In above example, we fetch the virtual dask arrays holding information about the halo and subhalo association for each particle.
+
+`GroupID`
+
+:   The group ID of the group the particle belongs to. This is the index into the group catalog.
+
+`SubhaloID`
+
+:   The subhalo ID of the subhalo the particle belongs to. This is the index into the subhalo catalog.
+
+`LocalSubhaloID`
+
+:  This is the Subhalo ID relative to the central subhalo of a given group. For the central subhalo, this is 0.
+   Satellites accordingly start at index 1.
+
+Particles that are not associated with a group or subhalo that are queried for such ID
+will return `ds.misc['unboundID']'`. This is currently set to 9223372036854775807, but might change to -1 in the future.
+
 
-This operation allows us to efficiently query the belonging of given particles. So, for example, we can compute the group IDs of the particles 1000-1099 by running
+This operation allows us to efficiently query the belonging of given particles.
+So, for example, we can compute the group IDs of the gas particles 1000-1099 by running
 
 ``` py
 groupid[1000:1100].compute()

mkdocs.yml

@@ -26,6 +26,9 @@ nav:
     - 'Derived fields': derived_fields.md
     - 'Data series': series.md
     - 'Large datasets': largedatasets.md
+  - 'Advanced Topics':
+    - 'Arepo Simulations':
+      - 'Halo Catalogs': halocatalogs.md
   # - 'Cookbook':
   #   - 'Units': notebooks/cookbook/units.ipynb
   - 'FAQ': faq.md