Merge pull request #6 from Julie-Fabre/JOSS_submission

Joss submission

Author: Julie-Fabre

README.md

@@ -12,6 +12,12 @@ Load and plot Allen Connectivity Data ([Oh et al., Nature, 2014](https://doi.org
 
 Available in both **MATLAB** and **Python**. **[Documentation](https://brain-street-view.readthedocs.io)**
 
+<p align="center">
+  <img src="./images/docs/upstream_projectome_scroll.gif" width="80%" alt="Scrolling through coronal slices showing projections into the caudate putamen from several visual areas, each in its own colour">
+</p>
+
+*Scroll through the brain to see projections into a target region from several source areas at once, each in its own colour ([interactive slice viewer](https://brain-street-view.readthedocs.io/en/latest/interactive_viewer.html)).*
+
 ### 🏁 Quick start
 
 **Python**:

bsv/plot_upstream_projectome.py

@@ -12,7 +12,8 @@
 def plot_upstream_projectome(experiment_ids, source_regions, target_region, save_location,
                               allen_atlas_path, atlas_resolution=10, atlas_type='allen',
                               slice_thickness=2, density_percentile=99,
-                              static_ap=None, save_path=None):
+                              static_ap=None, save_path=None,
+                              save_gif=None, gif_ap_step=2, gif_fps=8, gif_width=720):
     """Interactive coronal slice viewer of upstream projections into a target region.
 
     Displays a Jupyter widget with a coronal AP slider showing:
@@ -52,6 +53,16 @@ def plot_upstream_projectome(experiment_ids, source_regions, target_region, save
         documentation figures headlessly.
     save_path : str or None, optional
         When *static_ap* is set, save the rendered figure to this path.
+    save_gif : str or None, optional
+        If given, render an animated GIF scrolling through the AP slices that
+        contain the target region and write it to this path (requires Pillow).
+        Skips the interactive widget.
+    gif_ap_step : int, optional
+        Step between AP slices when building the GIF (default 2).
+    gif_fps : int, optional
+        Frames per second of the GIF (default 8).
+    gif_width : int, optional
+        Width in pixels to downscale GIF frames to (default 720).
     """
     AP, DV, ML = PROJECTION_GRID_SIZE
     # Number of full-res atlas voxels per 100 µm projection grid voxel
@@ -256,6 +267,36 @@ def _draw(ap_idx):
         plt.tight_layout()
         plt.show()
 
+    # ------------------------------------- animated GIF (scroll through AP)
+    if save_gif is not None:
+        try:
+            from PIL import Image
+        except ImportError as exc:
+            raise ImportError("Saving a GIF requires Pillow (pip install pillow).") from exc
+
+        present = np.where(target_mask.any(axis=(1, 2)))[0]
+        ap_lo, ap_hi = (int(present.min()), int(present.max())) if present.size else (0, AP - 1)
+        ap_indices = list(range(ap_lo, ap_hi + 1, max(1, int(gif_ap_step))))
+
+        frames = []
+        for ap in ap_indices:
+            _draw(ap)
+            fig = plt.gcf()
+            fig.canvas.draw()
+            w, h = fig.canvas.get_width_height()
+            rgba = np.frombuffer(fig.canvas.buffer_rgba(), dtype=np.uint8).reshape(h, w, 4)
+            img = Image.fromarray(rgba[:, :, :3].copy())
+            if gif_width and img.width > gif_width:
+                img = img.resize((int(gif_width), round(img.height * gif_width / img.width)))
+            frames.append(img.convert('P', palette=Image.ADAPTIVE, colors=256))
+            plt.close(fig)
+
+        if frames:
+            frames[0].save(save_gif, save_all=True, append_images=frames[1:],
+                           duration=int(1000 / max(gif_fps, 1)), loop=0, optimize=True)
+            print(f'Saved GIF: {save_gif} ({len(frames)} frames)')
+        return
+
     # ------------------------------------- static render (docs / headless use)
     if static_ap is not None:
         _draw(int(static_ap))

docs/generate_images.py

@@ -138,4 +138,11 @@ def save_current(name, facecolor='white'):
     static_ap=55)
 save_current('plot_upstream_projectome_CP.png', facecolor='black')
 
+# ── 9. Animated GIF scrolling through the brain (for README / docs) ──
+print('Generating: upstream projectome scroll GIF...')
+bsv.plot_upstream_projectome(
+    proj_src_ids, proj_src_regions, 'CP', save_location, allen_atlas_path,
+    save_gif=os.path.join(img_dir, 'upstream_projectome_scroll.gif'),
+    gif_ap_step=2, gif_fps=8, gif_width=720)
+
 print('\nDone! All images in:', img_dir)

docs/index.md

@@ -47,7 +47,7 @@ find_and_fetch
 plot_2d
 plot_3d
 plot_injections
-upstream_projectome
+interactive_viewer
 compare_regions
 thresholding
 striatum_analysis

docs/upstream_projectome.md docs/interactive_viewer.mddocs/upstream_projectome.md renamed to docs/interactive_viewer.md

@@ -1,4 +1,4 @@
-# Interactive upstream projectome
+# Interactive slice viewer
 
 Scroll through the brain and see, at every coronal level, the projections that
 *multiple* source regions send into a target region — each source drawn in its own
@@ -12,12 +12,12 @@ slider. At each slice it overlays, on the Allen CCF structure boundaries:
 - injection-site dots (sized by injection volume) at the AP levels where the injections
   actually sit.
 
-```{image} ../images/docs/plot_upstream_projectome_CP.png
+```{image} ../images/docs/upstream_projectome_scroll.gif
 :width: 100%
 ```
-*One AP slice (CCF 5500 µm) of projections into the caudate putamen (CP) from four
-visual areas, each in its own colour. Dragging the slider scrolls through the brain;
-injection-site dots appear at their own (more posterior) AP levels.*
+*Scrolling through coronal slices: projections into the caudate putamen (CP) from four
+visual areas, each in its own colour. In the live widget an anterior-posterior slider
+drives this; injection-site dots appear at their own (more posterior) AP levels.*
 
 **Python:**
 ```python