Add ability to specify index_path to EventBank, update docs accordingly

CHANGELOG.txt

@@ -1,7 +1,9 @@
 master
+  - obsplus.bank
+    * Tweaked the banks to allow for custom index paths. See #258.
   - obsplus.utils.stations
     * Fixed df_to_inventory to use a local copy of the NRL for compatibility
-      with ObsPy and NRLv2 (Note that NRLv1 is no longer accessible)
+      with ObsPy and NRLv2 (Note that NRLv1 is no longer accessible) (#271)
 
 obsplus 0.2.5
   - obsplus

docs/notebooks/interfaces/eventbank.ipynb

@@ -49,7 +49,7 @@
     "bank = obsplus.EventBank(event_path)\n",
     "\n",
     "# ensure index is up-to-date\n",
-    "bank.update_index() "
+    "bank.update_index()"
    ]
   },
   {
@@ -86,6 +86,29 @@
     "print(index.columns)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If you are working from a data directory that doesn't have write access, you can specify a custom location for the index path:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import tempfile\n",
+    "from pathlib import Path\n",
+    "\n",
+    "index_path = Path(tempfile.mkdtemp()) / \"index.db\"\n",
+    "cust_ind_bank = obsplus.EventBank(event_path, index_path=index_path)\n",
+    "cust_ind_bank.update_index()\n",
+    "ind = cust_ind_bank.read_index()\n",
+    "ind  # Note that paths in the index are relative to event_path"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -213,7 +236,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.5"
+   "version": "3.9.18"
   }
  },
  "nbformat": 4,

docs/notebooks/interfaces/wavebank.ipynb

@@ -82,6 +82,29 @@
     "bank.update_index()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Using a custom index path\n",
+    "\n",
+    "If you are working from a data directory that doesn't have write access, you can specify a custom location for the index path:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import tempfile\n",
+    "from pathlib import Path\n",
+    "\n",
+    "index_path = Path(tempfile.mkdtemp()) / \"index.h5\"\n",
+    "cust_ind_bank = obsplus.WaveBank(crandall_path, index_path=index_path)\n",
+    "cust_ind_bank.update_index()"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -344,7 +367,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.5"
+   "version": "3.9.18"
   }
  },
  "nbformat": 4,

src/obsplus/bank/core.py

@@ -320,6 +320,6 @@ def load_example_bank(
     def __repr__(self):
         """Return the class name with bank path."""
         name = type(self).__name__
-        return f"{name}(base_path={self.bank_path})"
+        return f"{name}(base_path={self.bank_path}, index_path={self.index_path})"
 
     __str__ = __repr__

src/obsplus/bank/eventbank.py

@@ -102,6 +102,9 @@ class EventBank(_Bank):
         variables and a slash cannot be used in a file name on most operating
         systems. The default extension (.xml) will be added.
         The default is {time}_{event_id_short}.
+    index_path
+        The path to the index file containing the contents of the directory.
+        By default it will be created in the top-level of the data directory.
     format
         The anticipated format of the event files. Any format supported by the
         obspy.read_events function is permitted.
@@ -160,6 +163,7 @@ def __init__(
         base_path: Union[str, Path, "EventBank"] = ".",
         path_structure: Optional[str] = None,
         name_structure: Optional[str] = None,
+        index_path: Optional[Union[str, Path]] = None,
         format="quakeml",
         ext=".xml",
         executor: Optional[Executor] = None,
@@ -181,6 +185,7 @@ def __init__(
         self.path_structure = ps
         ns = name_structure or self._name_structure or EVENT_NAME_STRUCTURE
         self.name_structure = ns
+        self._index_path = index_path
         self.executor = executor
         # enforce min version and warn on newer
         self._enforce_min_version()

tests/test_bank/test_eventbank.py

@@ -20,7 +20,7 @@
 from obsplus.constants import EVENT_DTYPES
 from obsplus.exceptions import UnsupportedKeyword
 from obsplus.utils.events import get_preferred
-from obsplus.utils.testing import instrument_methods
+from obsplus.utils.testing import check_index_paths, instrument_methods
 from obsplus.utils.misc import suppress_warnings, get_progressbar
 
 
@@ -130,6 +130,24 @@ def ebank_low_version(self, tmpdir, monkeypatch):
         assert obsplus.__last_version__ != self.low_version_str
         return ebank
 
+    @pytest.fixture
+    def cust_ebank_index_path(self, tmpdir_factory):
+        """Path for a custom index location"""
+        return tmpdir_factory.mktemp("custom_index") / ".index.db"
+
+    @pytest.fixture
+    def cust_index_ebank(self, tmpdir_factory, cust_ebank_index_path):
+        """
+        Create a copy of the bingham_test data set. Then return an inited event bank
+        using the temporary bingham_test bank
+        """
+        new = Path(str(tmpdir_factory.mktemp("bingham_test")))
+        copy_dataset("bingham_test", new)
+        path = new / "bingham_test" / "events"
+        ebank = EventBank(path, index_path=cust_ebank_index_path)
+        ebank.update_index()
+        return ebank
+
     @pytest.fixture(scope="class")
     def ebank_with_event_no_time(self, tmp_path_factory):
         """Create an event bank which has one file with no time."""
@@ -177,6 +195,24 @@ def test_read_index(self, bing_ebank, bingham_catalog):
         assert isinstance(df, pd.DataFrame)
         assert len(bingham_catalog) == len(df)
 
+    def test_custom_index_path(
+        self, cust_index_ebank, cust_ebank_index_path, bingham_catalog
+    ):
+        """
+        Read index, ensure its length matches events and id sets are
+        equal.
+        """
+        index_path = cust_index_ebank.index_path
+        # Make sure the new path got passed correctly
+        assert index_path == cust_ebank_index_path
+        assert os.path.exists(index_path)
+        # Make sure paths got written to the index properly
+        check_index_paths(cust_index_ebank)
+        # As an extra check, verify the length of the index matches the data catalog
+        df = cust_index_ebank.read_index()
+        assert isinstance(df, pd.DataFrame)
+        assert len(bingham_catalog) == len(df)
+
     def test_read_timestamp(self, bing_ebank):
         """read the current timestamp (after index has been updated)"""
         bing_ebank.update_index()