ethoscopy 2.1.0__tar.gz → 2.2.0__tar.gz

{ethoscopy-2.1.0 → ethoscopy-2.2.0}/Docker/Dockerfile

@@ -87,9 +87,18 @@ RUN pip3 install \
         seaborn \
         bokeh \
         lifelines \
+        ipywidgets \
+        ipympl \
         opencv-python \
         mysql-connector \
-        ethoscopy
+        scikit-learn \
+        statsmodels \
+        pingouin \
+        openpyxl \
+        pyarrow \
+        tqdm \
+        jupyterlab-git \
+        ethoscopy==2.1.0
        # pycatch22
 
 # Pre-populate tutorial datasets inside the installed package so non-root

{ethoscopy-2.1.0 → ethoscopy-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ethoscopy
-Version: 2.1.0
+Version: 2.2.0
 Summary: "A python based toolkit to download and anlyse data from the Ethoscope hardware system."
 Author-email: Lblackhurst29 <lblackhurst29@gmail.com>
 License-File: LICENSE
@@ -23,6 +23,7 @@ Requires-Dist: plotly<6.0.0,>=5.22.0
 Requires-Dist: pywavelets<2.0.0,>=1.6.0
 Requires-Dist: seaborn<0.14.0,>=0.13.2
 Requires-Dist: tabulate<0.10.0,>=0.9.0
+Requires-Dist: tqdm<5.0,>=4.66
 Provides-Extra: dev
 Requires-Dist: black<25.0.0,>=24.0.0; extra == 'dev'
 Requires-Dist: ipykernel<7.0.0,>=6.29.5; extra == 'dev'

{ethoscopy-2.1.0 → ethoscopy-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ethoscopy"
-version = "2.1.0"
+version = "2.2.0"
 description = "\"A python based toolkit to download and anlyse data from the Ethoscope hardware system.\""
 authors = [{name = "Lblackhurst29",email = "lblackhurst29@gmail.com"}]
 readme = "README.md"
@@ -15,6 +15,7 @@ dependencies = [
     "pywavelets>=1.6.0,<2.0.0",
     "astropy>=7.0,<8.0",
     "nbformat>=5.10.4,<6.0.0",
+    "tqdm>=4.66,<5.0",
 ]
 requires-python = ">=3.12,<4.0"
 classifiers = [

{ethoscopy-2.1.0 → ethoscopy-2.2.0}/src/ethoscopy/behavpy_core.py

@@ -9,6 +9,7 @@ from hmmlearn import hmm
 from scipy.signal import find_peaks
 from scipy.stats import zscore
 from tabulate import tabulate
+from tqdm.auto import tqdm
 
 from ethoscopy.analyse import max_velocity_detector
 from ethoscopy.misc.general_functions import concat, rle
@@ -2330,9 +2331,7 @@ class behavpy_core(pd.DataFrame):
         seq_test = np.concatenate(test, 0)
         seq_test = seq_test.reshape(-1, 1)
 
-        for i in range(iterations):
-            print(f"Iteration {i+1} of {iterations}")
-
+        for i in tqdm(range(iterations), desc="HMM training", unit="iter"):
             init_params = ""
             # h = hmm.MultinomialHMM(n_components = n_states, n_iter = hmm_iterations, tol = tol, params = 'ste', verbose = verbose)
             h = hmm.CategoricalHMM(
@@ -2397,11 +2396,13 @@ class behavpy_core(pd.DataFrame):
             h.fit(seq_train, len_seq_train)
 
             # Boolean output of if the number of runs convererged on set of appropriate probabilites for s, t, an e
-            print(
+            tqdm.write(
                 "True Convergence:"
                 + str(h.monitor_.history[-1] - h.monitor_.history[-2] < h.monitor_.tol)
             )
-            print("Final log liklihood score:" + str(h.score(seq_train, len_seq_train)))
+            tqdm.write(
+                "Final log liklihood score:" + str(h.score(seq_train, len_seq_train))
+            )
 
             # On first iteration save and print the first trained matrix
             if i == 0:
@@ -2410,9 +2411,11 @@ class behavpy_core(pd.DataFrame):
                     if h.score(seq_test, len_seq_test) > h_old.score(
                         seq_test, len_seq_test
                     ):
-                        print("New Matrix:")
+                        tqdm.write("New Matrix:")
                         df_t = pd.DataFrame(h.transmat_, index=states, columns=states)
-                        print(tabulate(df_t, headers="keys", tablefmt="github") + "\n")
+                        tqdm.write(
+                            tabulate(df_t, headers="keys", tablefmt="github") + "\n"
+                        )
 
                         with open(file_name, "wb") as file:
                             pickle.dump(h, file)
@@ -2426,9 +2429,9 @@ class behavpy_core(pd.DataFrame):
                 if h.score(seq_test, len_seq_test) > h_old.score(
                     seq_test, len_seq_test
                 ):
-                    print("New Matrix:")
+                    tqdm.write("New Matrix:")
                     df_t = pd.DataFrame(h.transmat_, index=states, columns=states)
-                    print(tabulate(df_t, headers="keys", tablefmt="github") + "\n")
+                    tqdm.write(tabulate(df_t, headers="keys", tablefmt="github") + "\n")
                     with open(file_name, "wb") as file:
                         pickle.dump(h, file)
 

{ethoscopy-2.1.0 → ethoscopy-2.2.0}/src/ethoscopy/behavpy_plotly.py

@@ -6,6 +6,7 @@ import pandas as pd
 import plotly.graph_objs as go
 from plotly.subplots import make_subplots
 from scipy.stats import zscore
+from tqdm.auto import tqdm
 
 from ethoscopy.behavpy_draw import behavpy_draw
 from ethoscopy.behavpy_seaborn import behavpy_seaborn
@@ -3559,10 +3560,16 @@ class behavpy_plotly(behavpy_draw):
         min_t = []
         max_t = []
 
-        for c, (df, b) in enumerate(zip(decoded, b_list)):
+        for c, (df, b) in enumerate(
+            tqdm(
+                list(zip(decoded, b_list)),
+                desc="Plotting",
+                unit="fly",
+                total=len(decoded),
+            )
+        ):
             df["colour"] = df["previous_state"].map(colours_index)
             id = df.first_valid_index()
-            print(f"Plotting: {id}")
 
             if stim_df is not None:
                 df2 = stim_df.xmv("id", id)

{ethoscopy-2.1.0 → ethoscopy-2.2.0}/src/ethoscopy/behavpy_seaborn.py

@@ -6,6 +6,7 @@ import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
 import seaborn as sns
+from tqdm.auto import tqdm
 
 from ethoscopy.behavpy_draw import behavpy_draw
 from ethoscopy.misc.circadian_bars import circadian_bars
@@ -3000,9 +3001,7 @@ class behavpy_seaborn(behavpy_draw):
         min_t = []
         max_t = []
 
-        for ax, data in enumerate(decoded):
-            print(f"Plotting: {data.index[0]}")
-
+        for ax, data in enumerate(tqdm(decoded, desc="Plotting", unit="fly")):
             data["bin"] = data["bin"] / (60 * 60)
             st = data["state"].to_numpy()
             time = data["bin"].to_numpy()

{ethoscopy-2.1.0 → ethoscopy-2.2.0}/src/ethoscopy/load.py

@@ -15,6 +15,7 @@ from urllib.parse import urlparse
 
 import numpy as np
 import pandas as pd
+from tqdm.auto import tqdm
 
 from ethoscopy.misc.validate_datetime import validate_datetime
 
@@ -74,7 +75,7 @@ def _connect_db(path):
         return sqlite3.connect(path_str)
 
 
-def download_from_remote_dir(meta, remote_dir, local_dir):
+def download_from_remote_dir(meta, remote_dir, local_dir, progress=True):
     """
     Download ethoscope data from a remote FTP server to a local directory.
 
@@ -88,6 +89,8 @@ def download_from_remote_dir(meta, remote_dir, local_dir):
             e.g. 'ftp://YOUR_SERVER//auto_generated_data//ethoscope_results'
         local_dir (str): Path to the local directory for saving .db files. Files will be saved using the FTP server's structure.
             e.g. 'C:\\Users\\YOUR_NAME\\Documents\\ethoscope_databases'
+        progress (bool, optional): If True, show a tqdm progress bar (ipywidgets-based in Jupyter,
+            text in CLI). Default is True.
 
     Returns:
         None
@@ -268,39 +271,27 @@ def download_from_remote_dir(meta, remote_dir, local_dir):
             ftp.quit()
             localfile.close()
 
-    # iterate over paths, downloading each file
-    # provide estimate download time based upon average time of previous downloads in queue
+    # iterate over paths, downloading each file. tqdm provides per-file progress
+    # plus an aggregate ETA, so we no longer need to hand-roll an estimate.
     download = partial(
         download_database,
         remote_dir=parse.netloc,
         folders=parse.path,
         local_dir=local_dir,
     )
-    times = []
 
-    for counter, j in enumerate(paths):
-        print(
-            "Downloading {}... {}/{}".format(
-                j[0].split("/")[1], counter + 1, len(paths)
-            )
-        )
-        if counter == 0:
-            start = time.time()
-            p = PurePosixPath(j[0])
-            download(work_dir=p.parents[0], file_name=p.name, file_size=j[1])
-            stop = time.time()
-            t = stop - start
-            times.append(t)
-
-        else:
-            av_time = round((np.mean(times) / 60) * (len(paths) - (counter + 1)))
-            print(f"Estimated finish time: {av_time} mins")
-            start = time.time()
-            p = PurePosixPath(j[0])
-            download(work_dir=p.parents[0], file_name=p.name, file_size=j[1])
-            stop = time.time()
-            t = stop - start
-            times.append(t)
+    iterator = tqdm(
+        paths,
+        desc="Downloading databases",
+        unit="db",
+        disable=not progress,
+    )
+    for j in iterator:
+        machine_name = j[0].split("/")[1]
+        if progress:
+            iterator.set_postfix_str(machine_name, refresh=False)
+        p = PurePosixPath(j[0])
+        download(work_dir=p.parents[0], file_name=p.name, file_size=j[1])
 
 
 def link_meta_index(metadata, local_dir):
@@ -471,6 +462,7 @@ def load_ethoscope(
     cache=None,
     FUN=None,
     verbose=True,
+    progress=True,
 ):
     """
     Load and process ethoscope data from database files.
@@ -488,7 +480,9 @@ def load_ethoscope(
             Directory structure mirrors ethoscope saved data. Cached files are in pickle format. Default is None.
         FUN (callable, optional): Function to apply individual curation to each ROI, typically using package
             generated functions (e.g., sleep_annotation). If None, data remains as found in the database. Default is None.
-        verbose (bool, optional): If True, prints information about each ROI when loading. Default is True.
+        verbose (bool, optional): If True, emits per-ROI warnings when loading fails. Default is True.
+        progress (bool, optional): If True, show a tqdm progress bar over ROIs (ipywidgets-based in
+            Jupyter, text in CLI). Default is True.
 
     Returns:
         pd.DataFrame: DataFrame containing the database data with unique IDs per fly as the index
@@ -507,101 +501,114 @@ def load_ethoscope(
     # Group ROIs by database file to reuse connections and cache metadata
     grouped_metadata = metadata.groupby("path")
 
+    pbar = tqdm(
+        total=len(metadata),
+        desc="Loading ROIs",
+        unit="roi",
+        disable=not progress,
+    )
+
     # iterate over each database file
-    for db_path, group in grouped_metadata:
-        conn = None
+    try:
+        for db_path, group in grouped_metadata:
+            conn = None
 
-        try:
-            # Open connection once per database file
-            conn = _connect_db(db_path)
-
-            # Cache metadata queries that are the same for all ROIs in this database
-            roi_df = pd.read_sql_query("SELECT * FROM ROI_MAP", conn)
-            var_df = pd.read_sql_query("SELECT * FROM VAR_MAP", conn)
-            date = pd.read_sql_query(
-                'SELECT value FROM METADATA WHERE field = "date_time"', conn
-            )
-            if date.empty:
-                raise ValueError("No date_time found in METADATA table")
-            date_formatted = time.strftime(
-                "%Y-%m-%d %H:%M:%S", time.gmtime(float(date.iloc[0].iloc[0]))
-            )
+            try:
+                # Open connection once per database file
+                conn = _connect_db(db_path)
+
+                # Cache metadata queries that are the same for all ROIs in this database
+                roi_df = pd.read_sql_query("SELECT * FROM ROI_MAP", conn)
+                var_df = pd.read_sql_query("SELECT * FROM VAR_MAP", conn)
+                date = pd.read_sql_query(
+                    'SELECT value FROM METADATA WHERE field = "date_time"', conn
+                )
+                if date.empty:
+                    raise ValueError("No date_time found in METADATA table")
+                date_formatted = time.strftime(
+                    "%Y-%m-%d %H:%M:%S", time.gmtime(float(date.iloc[0].iloc[0]))
+                )
 
-            # Process each ROI in this database
-            for i in group.index:
-                file_info = metadata.iloc[metadata.index.get_loc(i), :]
+                # Process each ROI in this database
+                for i in group.index:
+                    file_info = metadata.iloc[metadata.index.get_loc(i), :]
 
-                try:
-                    if verbose is True:
-                        print(
-                            "Loading ROI_{} from {}".format(
-                                file_info["region_id"], file_info["machine_name"]
+                    try:
+                        if progress:
+                            pbar.set_postfix_str(
+                                f"{file_info['machine_name']} ROI_{file_info['region_id']}",
+                                refresh=False,
                             )
-                        )
 
-                    # Use optimized single ROI reader with cached connection and metadata
-                    roi_1 = read_single_roi_optimized(
-                        file_info,
-                        conn,
-                        roi_df,
-                        var_df,
-                        date_formatted,
-                        min_time,
-                        max_time,
-                        reference_hour,
-                        cache,
-                    )
+                        # Use optimized single ROI reader with cached connection and metadata
+                        roi_1 = read_single_roi_optimized(
+                            file_info,
+                            conn,
+                            roi_df,
+                            var_df,
+                            date_formatted,
+                            min_time,
+                            max_time,
+                            reference_hour,
+                            cache,
+                        )
 
-                    if roi_1 is None:
-                        if verbose is True:
-                            print(
-                                "ROI_{} from {} was unable to load due to an error formatting roi".format(
-                                    file_info["region_id"], file_info["machine_name"]
+                        if roi_1 is None:
+                            if verbose is True:
+                                tqdm.write(
+                                    "ROI_{} from {} was unable to load due to an error formatting roi".format(
+                                        file_info["region_id"],
+                                        file_info["machine_name"],
+                                    )
                                 )
-                            )
-                        continue
+                            continue
+
+                        if FUN is not None:
+                            roi_1 = FUN(roi_1)
+
+                        if roi_1 is None:
+                            if verbose is True:
+                                tqdm.write(
+                                    "ROI_{} from {} was unable to load due to an error in applying the function".format(
+                                        file_info["region_id"],
+                                        file_info["machine_name"],
+                                    )
+                                )
+                            continue
 
-                    if FUN is not None:
-                        roi_1 = FUN(roi_1)
+                        # Check if 'id' column already exists, if not insert it
+                        if "id" not in roi_1.columns:
+                            roi_1.insert(0, "id", file_info["id"])
+                        else:
+                            # Replace existing id with the one from metadata for consistency
+                            roi_1["id"] = file_info["id"]
 
-                    if roi_1 is None:
+                        # Add to list instead of concatenating in loop
+                        roi_data_list.append(roi_1)
+
+                    except Exception as e:
                         if verbose is True:
-                            print(
-                                "ROI_{} from {} was unable to load due to an error in applying the function".format(
-                                    file_info["region_id"], file_info["machine_name"]
+                            tqdm.write(
+                                "ROI_{} from {} was unable to load due to an error loading roi: {}".format(
+                                    file_info["region_id"],
+                                    file_info["machine_name"],
+                                    str(e),
                                 )
                             )
-                        continue
-
-                    # Check if 'id' column already exists, if not insert it
-                    if "id" not in roi_1.columns:
-                        roi_1.insert(0, "id", file_info["id"])
-                    else:
-                        # Replace existing id with the one from metadata for consistency
-                        roi_1["id"] = file_info["id"]
-
-                    # Add to list instead of concatenating in loop
-                    roi_data_list.append(roi_1)
-
-                except Exception as e:
-                    if verbose is True:
-                        print(
-                            "ROI_{} from {} was unable to load due to an error loading roi: {}".format(
-                                file_info["region_id"],
-                                file_info["machine_name"],
-                                str(e),
-                            )
-                        )
-                        import traceback
+                            import traceback
 
-                        print("Full traceback:")
-                        traceback.print_exc()
-                    continue
+                            tqdm.write("Full traceback:")
+                            tqdm.write(traceback.format_exc())
+                        continue
+                    finally:
+                        pbar.update(1)
 
-        finally:
-            # Close connection when done with this database
-            if conn:
-                conn.close()
+            finally:
+                # Close connection when done with this database
+                if conn:
+                    conn.close()
+    finally:
+        pbar.close()
 
     # Concatenate all data at once for much better performance
     if roi_data_list:
@@ -612,7 +619,7 @@ def load_ethoscope(
     return data
 
 
-def load_ethoscope_metadata(metadata):
+def load_ethoscope_metadata(metadata, progress=True):
     """
     Extract metadata from ethoscope database files.
 
@@ -621,6 +628,8 @@ def load_ethoscope_metadata(metadata):
 
     Args:
         metadata (pd.DataFrame): Metadata dataframe as returned from link_meta_index function
+        progress (bool, optional): If True, show a tqdm progress bar (ipywidgets-based in Jupyter,
+            text in CLI). Default is True.
 
     Returns:
         pd.DataFrame: DataFrame containing the metadata from the METADATA table in each ethoscope database,
@@ -724,7 +733,12 @@ def load_ethoscope_metadata(metadata):
     rows = []
 
     # iterate over each ethoscope in the metadata df
-    for i in meta_df["path"]:
+    for i in tqdm(
+        meta_df["path"],
+        desc="Reading metadata",
+        unit="db",
+        disable=not progress,
+    ):
         row = get_meta(i)
         rows.append(row)
 
@@ -966,14 +980,14 @@ def read_single_roi_optimized(
             # Handle "database disk image is malformed" errors
             # This can occur with WAL-mode databases on read-only mounts
             if "malformed" in str(e).lower() or "disk image" in str(e).lower():
-                print(
+                tqdm.write(
                     f"Warning: Database error for ROI {file['region_id']}, attempting retry with fresh connection..."
                 )
 
                 # Get database path from file metadata
                 db_path = file.get("path")
                 if not db_path:
-                    print(
+                    tqdm.write(
                         "Error: Cannot retry - database path not found in file metadata"
                     )
                     raise
@@ -983,9 +997,9 @@ def read_single_roi_optimized(
                 try:
                     retry_conn = _connect_db(db_path)
                     data = pd.read_sql_query(sql_query, retry_conn)
-                    print(f"Success: ROI {file['region_id']} loaded on retry")
+                    tqdm.write(f"Success: ROI {file['region_id']} loaded on retry")
                 except Exception as retry_error:
-                    print(
+                    tqdm.write(
                         f"Error: Retry failed for ROI {file['region_id']}: {retry_error}"
                     )
                     raise
@@ -1032,5 +1046,5 @@ def read_single_roi_optimized(
         return data
 
     except Exception as e:
-        print(f"Error reading ROI {file['region_id']}: {e}")
+        tqdm.write(f"Error reading ROI {file['region_id']}: {e}")
         return None

ethoscopy-2.1.0/.claude/settings.local.json

@@ -1,48 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(wc:*)",
-      "Bash(paplay:*)",
-      "Bash(ETHOSCOPE_DATA_PATH=/mnt/ethoscope_data docker compose:*)",
-      "Bash(docker ps:*)",
-      "Bash(docker logs:*)",
-      "Bash(docker compose:*)",
-      "Bash(curl:*)",
-      "Bash(docker exec:*)",
-      "Bash(mkdir -p /tmp/ethoscopy_wheel_inspect)",
-      "Read(//tmp/**)",
-      "Bash(pip download *)",
-      "Bash(unzip -l ethoscopy-2.0.4-py3-none-any.whl)",
-      "Bash(git check-ignore *)",
-      "Bash(/home/gg/Code/ethoscope_project/ethoscopy/.venv/bin/pip install *)",
-      "Bash(.venv/bin/python -m pytest tests/test_get_tutorials.py -v)",
-      "Bash(.venv/bin/python *)",
-      "Bash(.venv/bin/pip install *)",
-      "Bash(gh auth *)",
-      "Bash(gh repo *)",
-      "Bash(docker info *)",
-      "mcp__bookstack__bookstack_search",
-      "Bash(.venv/bin/ruff check *)",
-      "Bash(.venv/bin/black --check src/ tests/)",
-      "Bash(.venv/bin/black src/ethoscopy/misc/get_tutorials.py tests/test_get_tutorials.py)",
-      "mcp__bookstack__bookstack_pages_read",
-      "mcp__bookstack__bookstack_pages_update",
-      "Bash(gh issue create --repo gilestrolab/ethoscopy --title 'Tutorial data pickles missing from PyPI wheel \\(2.0.0 – 2.0.4\\)' --body ' *)",
-      "Bash(git add *)",
-      "Bash(git commit *)",
-      "Bash(git push *)",
-      "Bash(git tag *)",
-      "Bash(gh release create v2.0.5 --repo gilestrolab/ethoscopy --title 'v2.0.5 — package tutorial data separately' --notes ' *)",
-      "Bash(gh run *)",
-      "Bash(gh issue *)",
-      "Bash(.venv/bin/twine check *)",
-      "Bash(.venv/bin/twine upload *)",
-      "Bash(.venv/bin/pip index *)",
-      "Bash(ETHOSCOPE_LAB_TAG=1.2 docker compose build)",
-      "Bash(gh release *)",
-      "Bash(ETHOSCOPE_LAB_TAG=1.2 docker compose build --no-cache --progress=plain)",
-      "Bash(grep -E --line-buffered '^#[0-9]+ \\(ERROR|CANCELED\\)|^#[0-9]+ DONE [0-9.]+s$|^ERROR|^failed to solve|Execution halted|^Error: Required R packages|non-zero code|^naming to|^ *=> .* done *$')",
-      "Bash(grep -E --line-buffered '^#[0-9]+ \\(ERROR|CANCELED\\)$|^#[0-9]+ DONE [0-9.]+s$|^failed to solve|Execution halted|^Error: Required R packages|Successfully built|naming to docker\\\\.io')"
-    ]
-  }
-}

ethoscopy-2.1.0/Docker/jupyterhub_data/jupyterhub_cookie_secret

@@ -1 +0,0 @@
-28d1b26a4bf0427c5ac0a6b896c90ffedd826af2f5fce289877ae09bf4a26b75

ethoscopy-2.1.0/tasks/todo.md

@@ -1,130 +0,0 @@
-# Ethoscopy — task log
-
-## 2026-04-21 — Fix missing tutorial pickles on PyPI installs
-
-**Problem.** Users installing ethoscopy 2.0.4 from PyPI hit
-`FileNotFoundError: Tutorial data files not found in: …/ethoscopy/misc/tutorial_data`
-when running `get_tutorial('overview')`. Root cause: `.gitignore` line 9
-contains `*.pkl`; Hatchling's default VCS plugin honours `.gitignore` when
-selecting wheel contents, so every tracked pickle was silently dropped from
-the 2.0.4 wheel (confirmed by inspecting the 144 KB artifact on PyPI).
-
-**Decision.** Keep the pickles *out* of the wheel by design
-(`overview_data.pkl` alone is ~31 MB — ~200× the code payload). Instead,
-ship an explicit fetch path and document it clearly everywhere.
-
-### Changes
-
-- [x] `pyproject.toml`: add explicit `[tool.hatch.build.targets.wheel] exclude`
-      for `src/ethoscopy/misc/tutorial_data/*.pkl` so intent is independent of
-      `.gitignore`.
-- [x] `src/ethoscopy/misc/get_tutorials.py`: add `download_tutorial_data()`
-      (stdlib `urllib`, idempotent, overwrite flag) and rewrite the
-      `FileNotFoundError` with a copy-paste recovery snippet + GitHub URL.
-- [x] `src/ethoscopy/misc/get_HMM.py`: update its `FileNotFoundError` to point
-      at the same helper (the 4-state HMM pickles live in the same folder).
-- [x] `src/ethoscopy/__init__.py`: re-export `download_tutorial_data` and
-      `get_tutorial` at the top level so users call
-      `etho.download_tutorial_data()`.
-- [x] `tests/test_get_tutorials.py`: add 5 tests for the new helper (URL
-      coverage, full download, skip-if-present, overwrite, network error).
-      15 tests pass.
-- [x] Six tutorial notebooks (`1_Overview`, `2_HMM`, `3_Circadian`,
-      `5_Ethoscopy_catch22`, `6_Ethoscopy_to_hctsa`, `notebook_paper`): insert
-      one markdown + one code cell before each first `get_tutorial(...)`
-      explaining the one-time fetch.
-- [x] `README.md`: add a "Tutorial data" section with the one-liner plus a
-      fallback manual-download path.
-
-### Follow-up (same session)
-
-After shipping the first cut, a second concern surfaced: the default
-destination (`<site-packages>/ethoscopy/misc/tutorial_data/`) is only
-writable for the user who installed ethoscopy. In system-wide installs,
-conda base envs, or Docker images where the package was installed by
-root, a non-root user calling `etho.download_tutorial_data()` would hit
-`PermissionError`. Fixed by:
-
-- [x] Default `download_tutorial_data(dest_dir=...)` to
-      `~/.cache/ethoscopy/tutorial_data/` (always user-writable).
-- [x] `get_tutorial` / `get_HMM` now consult three locations in order:
-      (1) package dir, (2) `$ETHOSCOPY_TUTORIAL_DATA_DIR`, (3) user cache.
-      `_missing_files_message()` prints the full search list so users
-      know exactly where ethoscopy looked.
-- [x] `PermissionError` on `mkdir` surfaces a wrapped message pointing
-      at `dest_dir=` / the env override.
-- [x] New tests: search-path ordering, env-var override, cache fallback,
-      permission-error wrapping, default-dest-is-user-cache. 22/22 pass.
-- [x] `Docker/Dockerfile` now runs
-      `download_tutorial_data(dest_dir=package_tutorial_data_dir())`
-      during build so JupyterHub users inherit the pickles from the
-      root-owned package dir — no runtime download ever needed.
-- [x] `README.md` "Tutorial data" section documents the lookup order.
-
-### Verification
-
-- [x] `python -m build --wheel` → 146 KB wheel, 24 files, 0 `.pkl`.
-- [x] Live network check of `etho.download_tutorial_data()` against
-      GitHub raw URLs — will be exercised by the Docker build.
-- [x] Build the Docker image with
-      `docker compose build` — in-flight.
-
-### Ship checklist (session of 2026-04-21)
-
-- [x] `pyproject.toml` bumped 2.0.4 → 2.0.5.
-- [x] Ruff + black both clean on `src/` and `tests/`.
-- [x] Bookstack "Getting started" page (book 1 / page 1) updated with
-      new "Tutorial data" section; dependency list refreshed; editor
-      switched from `wysiwyg` → `markdown` as a side effect of using
-      the markdown field.
-- [x] GitHub issue #7 opened and auto-closed by the commit footer.
-- [x] Commit `c858b84` pushed to `main` (13 files, +593 / −37).
-- [x] Tag `v2.0.5` pushed.
-- [x] GitHub release v2.0.5 published.
-- [x] CI `release.yml` failed on both tag-push and release events —
-      **pre-existing** `tests/test_load_optimizations.py` failures
-      (`No date_time found in METADATA table`), same pattern as 2.0.4.
-      Unrelated to this change.
-- [x] Manual `twine upload` to PyPI succeeded: 2.0.5 wheel (147 KB)
-      and sdist (14 MB) live at
-      <https://pypi.org/project/ethoscopy/2.0.5/>.
-- [ ] Docker image `ggilestro/ethoscope-lab:1.2` build + push.
-
-### Side debt spotted during this session
-
-- `tests/test_load_optimizations.py::TestLoadOptimizationPerformance`
-  (`test_load_ethoscope_memory_usage`, `test_connection_caching_benefit`)
-  fails on GitHub Actions for both 2.0.4 and 2.0.5 tag / release runs.
-  Raises `ValueError: No date_time found in METADATA table` from
-  `load.py:524`. The test fixture likely builds a SQLite DB without the
-  METADATA row that `load_ethoscope` now requires after
-  a6a1473 (`harden load_ethoscope_metadata against firmware quirks`).
-  Fix: update the test fixture to seed a `date_time` value in METADATA.
-- `.github/workflows/release.yml` also runs broader-than-unit tests on
-  tag push (`pytest tests/ -v --cov=ethoscopy -m "not slow"`), which is
-  stricter than `ci.yml`. This is why the `test` job blocks automated
-  PyPI publish. Either tighten the selection to `-m unit` or fix the
-  underlying test.
-- `.gitignore`'s blanket `*.pkl` is still present. It's currently
-  harmless because `pyproject.toml` has an explicit wheel exclusion,
-  but a future maintainer unaware of the wheel-build behaviour could
-  be surprised.
-
-### Discovered during work
-
-- `.gitignore` has a blanket `*.pkl` rule that's also generating noise (it
-  affects the behaviour of `git add` for tutorial pickles and the Hatchling
-  wheel). The explicit `exclude` in `pyproject.toml` now removes any ambiguity
-  about packaging, but the `.gitignore` rule could be tightened to a
-  user-output pattern (e.g. `tutorial_dataframe.pkl`) in a future pass.
-- The project-local `.venv` had a stale shebang (pointing to
-  `/home/gg/Data/...`) and had to be rebuilt.
-
-### Review
-
-- Net diff intentionally small: one new helper (~40 lines), one packaging
-  guard, one README section, one notebook preamble (templated, six files).
-- No behaviour change for users who already have the pickles on disk; the
-  error path now self-documents recovery.
-- PyPI release 2.0.5 should carry these changes — the 2.0.4 wheel remains
-  broken for new installers until then.