Accept a result-file path in NetworkModelResult

Constructing a model result from a file meant importing Network, loading
it, then passing it in. Hand NetworkModelResult the path instead and it
loads the network itself via Network.from_path; the loaded network stays
reachable afterwards.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: jpalm3r

src/modelskill/model/network.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from pathlib import Path
 from typing import TYPE_CHECKING, Sequence
 
 import numpy as np
@@ -90,15 +91,17 @@ def _create_new_instance(self, data: xr.Dataset) -> NodeModelResult:
 class NetworkModelResult:
     """Model result for network data with time and node dimensions.
 
-    Construct a NetworkModelResult from a Network object containing
-    timeseries data for each node. Users must provide exact node IDs
-    (integers obtained via ``Network.find()``) when creating observations —
-    no spatial interpolation is performed.
+    Construct a NetworkModelResult from a result file or from an already-loaded
+    Network containing timeseries data for each node. Users must provide exact
+    node IDs (integers obtained via ``Network.find()``) when creating
+    observations — no spatial interpolation is performed.
 
     Parameters
     ----------
-    data : Network
-        Network-like object with a ``to_dataset()`` method (e.g. :class:`modelskill.network.Network`).
+    data : Network, str or Path
+        Path to a ``.res1d``, ``.res11`` or ``.res`` result file, or a
+        network-like object with a ``to_dataset()`` method (e.g.
+        :class:`modelskill.network.Network`).
     name : str, optional
         The name of the model result,
         by default None (will be set to first data variable name)
@@ -113,23 +116,54 @@ class NetworkModelResult:
     Examples
     --------
     >>> import modelskill as ms
+    >>> mr = ms.NetworkModelResult("model.res1d", item="WaterLevel")
+
+    From a network built by hand, or loaded with arguments of its own:
+
     >>> from modelskill.network import Network
     >>> network = Network(reaches)  # reaches is a list[NetworkReach]
     >>> mr = ms.NetworkModelResult(network, name="MyModel")
-    >>> obs = ms.NodeObservation(data, node=network.find(node="node_A"))
+    >>> obs = ms.NodeObservation(data, at=network.find(node="node_A"))
     >>> extracted = mr.extract(obs)
+
+    Notes
+    -----
+    A path is read by the constructor its extension belongs to: ``.res1d`` and
+    ``.res11`` by :meth:`Network.from_mike
+    <modelskill.network.Network.from_mike>`, ``.res`` by
+    :meth:`Network.from_epanet <modelskill.network.Network.from_epanet>`. An
+    EPANET file also picks up the ``.resx`` and ``.inp`` companions that share
+    its folder and stem, since the ``.inp`` is the only one of the three
+    carrying reach lengths.
+
+    Load the network yourself when you need to name the companions, or to keep
+    memory down on a large file by reading only the nodes, reaches or
+    quantities you will score.
+
+    See Also
+    --------
+    modelskill.network.Network.from_mike : Read a MIKE 1D or MIKE 11 result file.
+    modelskill.network.Network.from_epanet : Read an EPANET result file.
     """
 
     def __init__(
         self,
-        data: Network,
+        data: Network | str | Path,
         *,
         name: str | None = None,
         item: str | int | None = None,
         quantity: Quantity | None = None,
         aux_items: Sequence[int | str] | None = None,
     ):
-        self.network = data.copy()
+        if isinstance(data, (str, Path)):
+            # Imported here, not at module scope, to keep this module importable
+            # without the optional network dependencies (ADR-010).
+            from modelskill.network import _network_from_path
+
+            # Freshly built, so nothing else holds a reference to copy away from.
+            self.network = _network_from_path(data)
+        else:
+            self.network = data.copy()
 
         ds = self.network.to_dataset()
         sel_items = SelectedItems.parse(

tests/test_network.py

@@ -2145,3 +2145,54 @@ def test_a_failure_without_companions_is_left_alone(self, tmp_path, monkeypatch)
         with pytest.raises(ValueError, match="^boom$"):
             _network_from_path(res)
 
+
+@requires_mikeio1d
+class TestNetworkModelResultFromPath:
+    """A path spares the caller a separate Network import and load."""
+
+    _RES1D = "./tests/testdata/network.res1d"
+
+    def test_a_path_gives_the_same_result_as_a_loaded_network(self):
+        from_path = NetworkModelResult(self._RES1D, item="WaterLevel")
+        from_network = NetworkModelResult(
+            Network.from_mike(self._RES1D), item="WaterLevel"
+        )
+
+        assert from_path.name == from_network.name
+        assert from_path.quantity == from_network.quantity
+        assert np.array_equal(from_path.nodes, from_network.nodes)
+        assert from_path.time.equals(from_network.time)
+
+    def test_a_str_and_a_path_are_interchangeable(self):
+        as_str = NetworkModelResult(self._RES1D, item="WaterLevel")
+        as_path = NetworkModelResult(Path(self._RES1D), item="WaterLevel")
+
+        assert np.array_equal(as_str.nodes, as_path.nodes)
+
+    def test_the_network_is_reachable_afterwards(self):
+        mr = NetworkModelResult(self._RES1D, item="WaterLevel")
+
+        assert isinstance(mr.network, Network)
+        assert mr.network.find(node="100") in mr.nodes
+
+    def test_extract_works_from_a_path_loaded_model(self):
+        mr = NetworkModelResult(self._RES1D, item="WaterLevel")
+        node = mr.network.find(node="100")
+        obs_data = pd.DataFrame({"sensor": np.zeros(len(mr.time))}, index=mr.time)
+
+        extracted = mr.extract(NodeObservation(obs_data, at=node))
+
+        assert isinstance(extracted, NodeModelResult)
+        assert extracted.node == node
+
+    def test_an_epanet_path_reads_its_companions(self, tmp_path):
+        res = _copy_epanet(tmp_path, ".resx", ".inp")
+
+        mr = NetworkModelResult(res, item="Head")
+
+        assert "Volume" in mr.network.quantities
+        assert mr.network._reaches["10"].length == pytest.approx(3209.544)
+
+    def test_an_unreadable_format_is_refused(self):
+        with pytest.raises(NotImplementedError, match="Unsupported file extension"):
+            NetworkModelResult("./tests/testdata/obs.dfs0")