refactor(modpathfile): toward unified particle tracking api (#2127)

* introduce base particle track file module and class
* rename _ModpathSeries -> ModpathFile
* deduplicate shared logic in ModpathFile
* deprecate write_shapefile() params
* prep to add support for MF6 PRT
* clarify canonical (minimal) fields
* add dtypes as class attributes
* misc cleanup in plotutil.py

autotest/test_mp5.py

@@ -1,10 +1,8 @@
 import os
 
 import numpy as np
-import pandas as pd
 from autotest.test_mp6 import eval_timeseries
 from matplotlib import pyplot as plt
-from modflow_devtools.markers import requires_pkg
 
 from flopy.modflow import Modflow
 from flopy.plot import PlotMapView
@@ -50,14 +48,8 @@ def test_mp5_load(function_tmpdir, example_data_path):
     for n in pthobj.nid:
         p = pthobj.get_data(partid=n)
         e = endobj.get_data(partid=n)
-        try:
-            mm.plot_pathline(p, colors=colors[n], layer="all")
-        except:
-            assert False, f'could not plot pathline {n + 1} with layer="all"'
-        try:
-            mm.plot_endpoint(e)
-        except:
-            assert False, f'could not plot endpoint {n + 1} with layer="all"'
+        mm.plot_pathline(p, colors=colors[n], layer="all")
+        mm.plot_endpoint(e)
 
     # plot the grid and ibound array
     mm.plot_grid(lw=0.5)

autotest/test_plot_particle_tracks.py

@@ -4,12 +4,12 @@
 import pandas as pd
 import pytest
 from matplotlib.collections import LineCollection, PathCollection
-from modflow_devtools.markers import requires_exe, requires_pkg
+from modflow_devtools.markers import requires_exe
 
 from flopy.modflow import Modflow
 from flopy.modpath import Modpath6, Modpath6Bas
 from flopy.plot import PlotCrossSection, PlotMapView
-from flopy.utils import CellBudgetFile, EndpointFile, HeadFile, PathlineFile
+from flopy.utils import EndpointFile, PathlineFile
 
 
 @pytest.fixture
@@ -58,7 +58,6 @@ def test_plot(pl):
         mx.plot_grid()
         mx.plot_bc("WEL", kper=2, color="blue")
         pth = mx.plot_pathline(pl, colors="red")
-        # plt.show()
         assert isinstance(pth, LineCollection)
         assert len(pth._paths) == 114
 

autotest/test_plotutil.py

@@ -194,7 +194,7 @@
             "PRP000000001",  # name
         ],
     ],
-    columns=PRT_PATHLINE_DTYPE.fields.keys(),
+    columns=PRT_PATHLINE_DTYPE.names,
 )
 MP7_TEST_PATHLINES = pd.DataFrame.from_records(
     [
@@ -233,7 +233,7 @@
             1,  # timestep
         ],
     ],
-    columns=MP7_PATHLINE_DTYPE.fields.keys(),
+    columns=MP7_PATHLINE_DTYPE.names,
 )
 MP7_TEST_ENDPOINTS = pd.DataFrame.from_records(
     [
@@ -322,7 +322,7 @@
             2,  # cellface
         ],
     ],
-    columns=MP7_ENDPOINT_DTYPE.fields.keys(),
+    columns=MP7_ENDPOINT_DTYPE.names,
 )
 
 
@@ -342,13 +342,13 @@ def test_to_mp7_pathlines(dataframe):
     assert len(mp7_pls) == 10
     assert set(
         dict(mp7_pls.dtypes).keys() if dataframe else mp7_pls.dtype.names
-    ) == set(MP7_PATHLINE_DTYPE.fields.keys())
+    ) == set(MP7_PATHLINE_DTYPE.names)
 
 
 @pytest.mark.parametrize("dataframe", [True, False])
 def test_to_mp7_pathlines_empty(dataframe):
     mp7_pls = to_mp7_pathlines(
-        pd.DataFrame.from_records([], columns=PRT_PATHLINE_DTYPE.fields.keys())
+        pd.DataFrame.from_records([], columns=PRT_PATHLINE_DTYPE.names)
         if dataframe
         else np.recarray((0,), dtype=PRT_PATHLINE_DTYPE)
     )
@@ -374,7 +374,7 @@ def test_to_mp7_pathlines_noop(dataframe):
     assert len(mp7_pls) == 2
     assert set(
         dict(mp7_pls.dtypes).keys() if dataframe else mp7_pls.dtype.names
-    ) == set(MP7_PATHLINE_DTYPE.fields.keys())
+    ) == set(MP7_PATHLINE_DTYPE.names)
     assert np.array_equal(
         mp7_pls if dataframe else pd.DataFrame(mp7_pls), MP7_TEST_PATHLINES
     )
@@ -391,13 +391,13 @@ def test_to_mp7_endpoints(dataframe):
     assert np.isclose(mp7_eps.time[0], PRT_TEST_PATHLINES.t.max())
     assert set(
         dict(mp7_eps.dtypes).keys() if dataframe else mp7_eps.dtype.names
-    ) == set(MP7_ENDPOINT_DTYPE.fields.keys())
+    ) == set(MP7_ENDPOINT_DTYPE.names)
 
 
 @pytest.mark.parametrize("dataframe", [True, False])
 def test_to_mp7_endpoints_empty(dataframe):
     mp7_eps = to_mp7_endpoints(
-        pd.DataFrame.from_records([], columns=PRT_PATHLINE_DTYPE.fields.keys())
+        pd.DataFrame.from_records([], columns=PRT_PATHLINE_DTYPE.names)
         if dataframe
         else np.recarray((0,), dtype=PRT_PATHLINE_DTYPE)
     )
@@ -445,7 +445,7 @@ def test_to_prt_pathlines_roundtrip(dataframe):
 @pytest.mark.parametrize("dataframe", [True, False])
 def test_to_prt_pathlines_roundtrip_empty(dataframe):
     mp7_pls = to_mp7_pathlines(
-        pd.DataFrame.from_records([], columns=PRT_PATHLINE_DTYPE.fields.keys())
+        pd.DataFrame.from_records([], columns=PRT_PATHLINE_DTYPE.names)
         if dataframe
         else np.recarray((0,), dtype=PRT_PATHLINE_DTYPE)
     )
@@ -454,4 +454,4 @@ def test_to_prt_pathlines_roundtrip_empty(dataframe):
     assert prt_pls.empty if dataframe else mp7_pls.size == 0
     assert set(
         dict(mp7_pls.dtypes).keys() if dataframe else mp7_pls.dtype.names
-    ) == set(MP7_PATHLINE_DTYPE.fields.keys())
+    ) == set(MP7_PATHLINE_DTYPE.names)

flopy/plot/plotutil.py

@@ -2679,7 +2679,6 @@ def parse_modpath_selection_options(
         ("cellface", np.int32),
     ]
 )
-MP_MIN_PLOT_FIELDS = ["x", "y", "z", "time", "k", "particleid"]
 
 
 def to_mp7_pathlines(
@@ -2698,6 +2697,8 @@ def to_mp7_pathlines(
     np.recarray or pd.DataFrame (consistent with input type)
     """
 
+    from flopy.utils.particletrackfile import MIN_PARTICLE_TRACK_DTYPE
+
     # determine return type
     ret_type = type(data)
 
@@ -2708,13 +2709,13 @@ def to_mp7_pathlines(
     # check format
     dt = data.dtypes
     if not (
-        all(n in dt for n in MP_MIN_PLOT_FIELDS)
-        or all(n in dt for n in PRT_PATHLINE_DTYPE.fields.keys())
+        all(n in dt for n in MIN_PARTICLE_TRACK_DTYPE.names)
+        or all(n in dt for n in PRT_PATHLINE_DTYPE.names)
     ):
         raise ValueError(
             "Pathline data must contain the following fields: "
-            f"{MP_MIN_PLOT_FIELDS} for MODPATH 7, or "
-            f"{PRT_PATHLINE_DTYPE.fields.keys()} for MODFLOW 6 PRT"
+            f"{MIN_PARTICLE_TRACK_DTYPE.names} for MODPATH 7, or "
+            f"{PRT_PATHLINE_DTYPE.names} for MODFLOW 6 PRT"
         )
 
     # return early if already in MP7 format
@@ -2780,6 +2781,8 @@ def to_mp7_endpoints(
     np.recarray or pd.DataFrame (consistent with input type)
     """
 
+    from flopy.utils.particletrackfile import MIN_PARTICLE_TRACK_DTYPE
+
     # determine return type
     ret_type = type(data)
 
@@ -2789,18 +2792,18 @@ def to_mp7_endpoints(
 
     # check format
     dt = data.dtypes
-    if all(n in dt for n in MP7_ENDPOINT_DTYPE.fields.keys()):
+    if all(n in dt for n in MP7_ENDPOINT_DTYPE.names):
         return (
             data if ret_type == pd.DataFrame else data.to_records(index=False)
         )
     if not (
-        all(n in dt for n in MP_MIN_PLOT_FIELDS)
-        or all(n in dt for n in PRT_PATHLINE_DTYPE.fields.keys())
+        all(n in dt for n in MIN_PARTICLE_TRACK_DTYPE.names)
+        or all(n in dt for n in PRT_PATHLINE_DTYPE.names)
     ):
         raise ValueError(
             "Pathline data must contain the following fields: "
-            f"{MP_MIN_PLOT_FIELDS} for MODPATH 7, or "
-            f"{PRT_PATHLINE_DTYPE.fields.keys()} for MODFLOW 6 PRT"
+            f"{MIN_PARTICLE_TRACK_DTYPE.names} for MODPATH 7, or "
+            f"{PRT_PATHLINE_DTYPE.names} for MODFLOW 6 PRT"
         )
 
     # return early if empty
@@ -2909,13 +2912,13 @@ def to_prt_pathlines(
     # check format
     dt = data.dtypes
     if not (
-        all(n in dt for n in MP7_PATHLINE_DTYPE.fields.keys())
-        or all(n in dt for n in PRT_PATHLINE_DTYPE.fields.keys())
+        all(n in dt for n in MP7_PATHLINE_DTYPE.names)
+        or all(n in dt for n in PRT_PATHLINE_DTYPE.names)
     ):
         raise ValueError(
             "Pathline data must contain the following fields: "
-            f"{MP7_PATHLINE_DTYPE.fields.keys()} for MODPATH 7, or "
-            f"{PRT_PATHLINE_DTYPE.fields.keys()} for MODFLOW 6 PRT"
+            f"{MP7_PATHLINE_DTYPE.names} for MODPATH 7, or "
+            f"{PRT_PATHLINE_DTYPE.names} for MODFLOW 6 PRT"
         )
 
     # return early if already in PRT format

flopy/utils/flopy_io.py

@@ -352,7 +352,6 @@ def loadtxt(
     ra : np.recarray
         Numpy record array of file contents.
     """
-    from ..utils import import_optional_dependency
 
     if use_pandas:
         if delimiter.isspace():