feat(graphs): add LimitedAreaMask for stretched hidden nodes (#671)

## Description
<!-- What issue or task does this change relate to? -->

This PR add a new node attribute builder, `LimitedAreaMask`.

- Schemas updated
- Documentation updated
- fix: plot_interactive_nodes_2d. Update the argument `titlefont_size`
to a newer version of plotly.

<img width="1905" height="966" alt="Screenshot 2025-11-13 at 12 37 36"
src="https://github.com/user-attachments/assets/0a2e6810-751d-4966-a6bd-f54f9456a63e"
/>


[hidden_nodes.html](https://github.com/user-attachments/files/23524994/hidden_nodes.html)


***As a contributor to the Anemoi framework, please ensure that your
changes include unit tests, updates to any affected dependencies and
documentation, and have been tested in a parallel setting (i.e., with
multiple GPUs). As a reviewer, you are also responsible for verifying
these aspects and requesting changes if they are not adequately
addressed. For guidelines about those please refer to
https://anemoi.readthedocs.io/en/latest/***

By opening this pull request, I affirm that all authors agree to the
[Contributor License
Agreement.](https://github.com/ecmwf/codex/blob/main/Legal/contributor_license_agreement.md)


<!-- readthedocs-preview anemoi-training start -->
----
📚 Documentation preview 📚:
https://anemoi-training--671.org.readthedocs.build/en/671/

<!-- readthedocs-preview anemoi-training end -->

<!-- readthedocs-preview anemoi-graphs start -->
----
📚 Documentation preview 📚:
https://anemoi-graphs--671.org.readthedocs.build/en/671/

<!-- readthedocs-preview anemoi-graphs end -->

<!-- readthedocs-preview anemoi-models start -->
----
📚 Documentation preview 📚:
https://anemoi-models--671.org.readthedocs.build/en/671/

<!-- readthedocs-preview anemoi-models end -->

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Ana Prieto Nemesio <[email protected]>

Author: 3 people

graphs/docs/graphs/node_attributes.rst

@@ -21,6 +21,7 @@ connections only between subsets of nodes.
 
    node_attributes/weights
    node_attributes/anemoi_dataset_attribute
+   node_attributes/area_masks
 
 Additionally, different boolean operations have been implemented to
 support more complex use cases:

graphs/docs/graphs/node_attributes/area_masks.rst

@@ -0,0 +1,18 @@
+###########
+ Area mask
+###########
+
+The `LimitedAreaMask` node attribute builder creates a mask over the
+nodes covering the limited area.
+
+The configuration for these masks, is specified in the YAML file:
+
+.. literalinclude:: ../yaml/attributes_lam_mask.yaml
+   :language: yaml
+
+.. note::
+
+   This node attribute builder is only supported for nodes created using
+   subclasses of ``StretchedIcosahedronNodes``. Currently, it is
+   available exclusively for nodes built with the ``StretchedTriNodes``
+   subclass.

graphs/docs/graphs/yaml/attributes_lam_mask.yaml

@@ -0,0 +1,9 @@
+nodes:
+  data: ...
+  hidden:
+    node_builder:
+      _target_: anemoi.graphs.nodes.StretchedTriNodes
+      # ...
+    attributes:
+      cutout_mask:
+        _target_: anemoi.graphs.nodes.attributes.LimitedAreaMask

graphs/src/anemoi/graphs/nodes/attributes/__init__.py

@@ -18,6 +18,7 @@
 from .boolean_op import BooleanOrMask
 from .masks import CutOutMask
 from .masks import GridsMask
+from .masks import LimitedAreaMask
 from .masks import NonmissingAnemoiDatasetVariable
 from .masks import NonzeroAnemoiDatasetVariable
 
@@ -27,6 +28,7 @@
     "PlanarAreaWeights",
     "UniformWeights",
     "CutOutMask",
+    "LimitedAreaMask",
     "MaskedPlanarAreaWeights",
     "NonmissingAnemoiDatasetVariable",
     "NonzeroAnemoiDatasetVariable",

graphs/src/anemoi/graphs/nodes/attributes/masks.py

@@ -162,3 +162,23 @@ class GridsMask(BaseCombineAnemoiDatasetsMask):
     def __init__(self, grids: int | list[int] = 0) -> None:
         self.grids = [grids] if isinstance(grids, int) else grids
         super().__init__()
+
+
+class LimitedAreaMask(BooleanBaseNodeAttribute):
+    """Limited area mask.
+
+    It adds a mask based on an area of interest. This mask is only defined
+    for nodes built with a subclass of `StretchedIcosahedronNodes`.
+
+    Methods
+    -------
+    compute(self, graph, nodes_name)
+        Compute the attribute for each node.
+    """
+
+    def get_raw_values(self, nodes: NodeStorage, **kwargs) -> torch.Tensor:
+        assert nodes["node_type"] in [
+            "StretchedTriNodes"
+        ], f"{self.__class__.__name__} can only be used with StretchedIcosahedronNodes."
+        lam_mask = nodes["_area_mask_builder"].get_mask(nodes.x)
+        return torch.from_numpy(lam_mask)

graphs/src/anemoi/graphs/nodes/builders/from_refined_icosahedron.py

@@ -47,7 +47,6 @@ def __init__(
             "resolutions",
             "nx_graph",
             "node_ordering",
-            "area_mask_builder",
         }
         if not hasattr(self, "multi_scale_edge_cls"):
             raise AttributeError("Classes inheriting from IcosahedralNodes must set 'multi_scale_edge_cls' attribute.")
@@ -86,6 +85,7 @@ def __init__(
     ) -> None:
 
         super().__init__(resolution, name)
+        self.hidden_attributes = self.hidden_attributes | {"area_mask_builder"}
 
         self.area_mask_builder = KNNAreaMaskBuilder(reference_node_name, margin_radius_km, mask_attr_name)
 
@@ -160,7 +160,7 @@ def create_nodes(self) -> tuple[nx.Graph, np.ndarray, list[int]]:
         return create_hex_nodes(resolution=max(self.resolutions), area_mask_builder=self.area_mask_builder)
 
 
-class StretchedIcosahedronNodes(IcosahedralNodes, ABC):
+class StretchedIcosahedronNodes(LimitedAreaIcosahedralNodes, ABC):
     """Nodes based on iterative refinements of an icosahedron with 2
     different resolutions.
 
@@ -176,19 +176,18 @@ def __init__(
         lam_resolution: int,
         name: str,
         reference_node_name: str,
-        mask_attr_name: str,
+        mask_attr_name: str | None = None,
         margin_radius_km: float = 100.0,
     ) -> None:
-
-        super().__init__(lam_resolution, name)
+        super().__init__(
+            resolution=lam_resolution,
+            reference_node_name=reference_node_name,
+            mask_attr_name=mask_attr_name,
+            margin_radius_km=margin_radius_km,
+            name=name,
+        )
         self.global_resolution = global_resolution
 
-        self.area_mask_builder = KNNAreaMaskBuilder(reference_node_name, margin_radius_km, mask_attr_name)
-
-    def register_nodes(self, graph: HeteroData) -> None:
-        self.area_mask_builder.fit(graph)
-        return super().register_nodes(graph)
-
 
 class StretchedTriNodes(StretchedIcosahedronNodes):
     """Nodes based on iterative refinements of an icosahedron with 2

graphs/src/anemoi/graphs/plotting/interactive_2d_html.py

@@ -237,7 +237,7 @@ def plot_interactive_nodes_2d(graph: HeteroData, nodes_name: str, out_file: Opti
             sliders=[
                 dict(active=0, currentvalue={"visible": False}, len=0.4, x=0.5, xanchor="center", steps=slider_steps)
             ],
-            titlefont_size=16,
+            title_font_size=16,
             showlegend=False,
             hovermode="closest",
             margin={"b": 20, "l": 5, "r": 5, "t": 40},

graphs/src/anemoi/graphs/schemas/node_attributes_schemas.py

@@ -49,8 +49,10 @@ class SphericalAreaWeightSchema(BaseModel):
 
 
 class CutOutMaskSchema(BaseModel):
-    target_: Literal["anemoi.graphs.nodes.attributes.CutOutMask"] = Field(..., alias="_target_")
-    "Implementation of the cutout mask from anemoi.graphs.nodes.attributes."
+    target_: Literal["anemoi.graphs.nodes.attributes.CutOutMask", "anemoi.graphs.nodes.attributes.LimitedAreaMask"] = (
+        Field(..., alias="_target_")
+    )
+    "Implementation of the area masks from anemoi.graphs.nodes.attributes."
 
 
 class GridsMaskSchema(BaseModel):