Merge pull request #50 from broadinstitute/DEGA-98-Write-Celldega-Doc…

…umentation

DEGA-98 write first draft of the Celldega documentation

build.js

@@ -1,10 +1,16 @@
 import esbuild from 'esbuild';
+import fs from 'fs/promises';
+import path from 'path';
 import wasmPlugin from './wasm-plugin.mjs';
 
 const isWatchMode = process.argv.includes('--watch');
 
 async function main() {
   try {
+    // Define paths
+    const srcPath = path.resolve('src/celldega/static/widget.js');
+    const destPath = path.resolve('docs/assets/js/widget.js');
+
     // Create a build context
     const context = await esbuild.context({
       entryPoints: ['js/widget.js'],
@@ -22,22 +28,26 @@ async function main() {
     if (isWatchMode) {
       // Enable watch mode and listen for changes
       await context.watch();
-
       console.log("Watch mode enabled. Listening for changes...");
-
     } else {
       // Perform a single build if not in watch mode
       const result = await context.rebuild();
       console.log('Build succeeded:', result);
 
+      // Copy widget.js to the docs/assets/js directory
+      console.log(`Copying ${srcPath} to ${destPath}...`);
+      await fs.mkdir(path.dirname(destPath), { recursive: true }); // Ensure destination directory exists
+      await fs.copyFile(srcPath, destPath);
+      console.log('File copied successfully.');
+
       // Dispose of the context after a successful build to ensure the process exits
       await context.dispose();
       process.exit(0); // Exit successfully
     }
 
     // Handle clean up for watch mode on process exit
-    process.on('exit', () => {
-      context.dispose();
+    process.on('exit', async () => {
+      await context.dispose();
     });
   } catch (error) {
     console.error('Build failed:', error);

docs/assets/css/custom.css

@@ -0,0 +1,8 @@
+/* .md-header__button{
+    color: red;
+} */
+
+/* Hide the Table of Contents when a Jupyter notebook is present */
+/* .jupyter-wrapper ~ .md-sidebar--secondary {
+    display: none !important;
+} */

docs/assets/js/gallery_mouse_brain.js

@@ -0,0 +1,34 @@
+import celldega from './widget.js';
+document.addEventListener("DOMContentLoaded", async () => {
+
+    const landscape_el = document.getElementById('landscape-mouse-brain');
+
+    if (window.location.pathname.endsWith('gallery_xenium_mouse_brain/')){
+
+        // Use the imported functions
+        const token = '';
+        const ini_x = 21500;
+        const ini_y = 14200;
+        const ini_z = 0;
+        const ini_zoom = -5;
+        const base_url = 'https://raw.githubusercontent.com/broadinstitute/celldega_Xenium_Prime_Mouse_Brain_Coronal_FF_outs/main/Xenium_Prime_Mouse_Brain_Coronal_FF_outs';
+
+        const landscape = await celldega.landscape_ist(
+            landscape_el,
+            {},
+            token,
+            ini_x,
+            ini_y,
+            ini_z,
+            ini_zoom,
+            base_url,
+            '',
+            0.25,
+            '100%',
+            '100%',
+            // ist_callback
+        );
+
+    }
+
+});

docs/assets/js/gallery_skin_cancer.js

@@ -0,0 +1,34 @@
+import celldega from './widget.js';
+document.addEventListener("DOMContentLoaded", async () => {
+
+    const landscape_el = document.getElementById('landscape-skin-cancer');
+
+    if (window.location.pathname.endsWith('gallery_xenium_skin_cancer/')){
+
+        // Use the imported functions
+        const token = '';
+        const ini_x = 21500;
+        const ini_y = 14200;
+        const ini_z = 0;
+        const ini_zoom = -5;
+        const base_url = 'https://raw.githubusercontent.com/broadinstitute/celldega_Xenium_Prime_Human_Skin_FFPE_outs/main/Xenium_Prime_Human_Skin_FFPE_outs';
+
+        const landscape = await celldega.landscape_ist(
+            landscape_el,
+            {},
+            token,
+            ini_x,
+            ini_y,
+            ini_z,
+            ini_zoom,
+            base_url,
+            '',
+            0.25,
+            '100%',
+            '100%',
+            // ist_callback
+        );
+
+    }
+
+});

docs/assets/js/google-analytics.js

@@ -0,0 +1,32 @@
+(function() {
+
+  // Load the GA4 script asynchronously
+  const script = document.createElement('script');
+  script.async = true;
+  script.src = 'https://www.googletagmanager.com/gtag/js?id=G-7NFDYRTDDT';
+  document.head.appendChild(script);
+
+  // Initialize the dataLayer
+  window.dataLayer = window.dataLayer || [];
+  function gtag(){dataLayer.push(arguments);}
+
+  // Set up GA4 with privacy-first configurations
+  gtag('js', new Date());
+
+  // Configure Google Analytics with privacy-first options
+  gtag('config', 'G-7NFDYRTDDT', {
+      'anonymize_ip': true,           // Anonymize IP addresses
+      'allow_google_signals': false, // Disable Google Signals
+      'storage': 'none',             // Disable cookies
+      'cookie_flags': 'SameSite=None;Secure' // Prevent cookies if used inadvertently
+  });
+
+  // Use Consent Mode to limit data collection
+  gtag('consent', 'default', {
+      'ad_storage': 'denied',
+      'analytics_storage': 'denied'
+  });
+
+  // // Optional: Additional configurations for enhanced privacy
+  // console.log('GA4 configured with privacy-first settings');
+})();

docs/assets/js/hide_notebook_sidebar.js

@@ -0,0 +1,33 @@
+document.addEventListener("DOMContentLoaded", async () => {
+    // Increase width of notebook and galley pages
+    if (window.location.pathname.includes('notebook') || window.location.pathname.includes('gallery_')) {
+
+        // hide primary sidebar
+        const sidebar_primary = document.querySelector('.md-sidebar--primary');
+
+        if (sidebar_primary) {
+            sidebar_primary.style.width = '8.1rem';
+        }
+
+        // hide secondary sidebar
+        const sidebar_secondary = document.querySelector('.md-sidebar--secondary');
+
+        if (sidebar_secondary) {
+            sidebar_secondary.style.display = 'none';
+        }
+
+        // remove max width constraint
+        const md_grid = document.querySelector('.md-main__inner');
+
+        if (md_grid) {
+            md_grid.style.marginLeft = 'unset';
+            md_grid.style.marginRight = 'unset';
+            md_grid.style.maxWidth = 'none';
+        }
+
+
+        // You can also add additional logic specific to notebook pages here
+        console.log("Notebook page detected. Sidebar hidden.");
+    }
+
+});

docs/assets/js/index.js

@@ -0,0 +1,42 @@
+import celldega from './widget.js';
+
+document.addEventListener("DOMContentLoaded", async () => {
+
+    // Check if we are on the home page
+    const isHomePage = window.location.pathname === '/' || window.location.pathname.endsWith('/index.html');
+
+    const landscape_el = document.getElementById('landscape');
+
+    if (landscape_el) {
+
+        // Use the imported functions
+        const token = '';
+        const ini_x = 21500;
+        const ini_y = 14200;
+        const ini_z = 0;
+        const ini_zoom = -6;
+        const base_url = 'https://raw.githubusercontent.com/broadinstitute/celldega_Xenium_Prime_Human_Skin_FFPE_outs/main/Xenium_Prime_Human_Skin_FFPE_outs';
+
+        // let el = document.querySelector("#landscape");
+
+        const landscape = await celldega.landscape_ist(
+            landscape_el,
+            {},
+            token,
+            ini_x,
+            ini_y,
+            ini_z,
+            ini_zoom,
+            base_url,
+            '',
+            0.25,
+            '100%',
+            '100%',
+            // ist_callback
+        );
+
+    }
+
+});
+
+

docs/examples/index.md

@@ -0,0 +1,6 @@
+# Jupyter Notebook Examples
+
+## Brief Notebooks
+[Landscape View Xenium](brief_notebooks/Landscape_View_Xenium.ipynb)
+
+[Mouse-Brain_Alpha-Shape-Neighborhood](brief_notebooks/Mouse-Brain_Alpha-Shape-Neighborhood.ipynb)

docs/gallery/gallery_xenium_mouse_brain.md

@@ -0,0 +1,5 @@
+# Xenium Prime Mouse Brain Coronal FF
+
+<div id="landscape-container" style="position: relative; display: flex; width: 100%; height: 800px; overflow: hidden; border: 1px solid #ccc;">
+    <div id="landscape-mouse-brain" style="height; 800px;"></div>
+</div>

docs/gallery/gallery_xenium_skin_cancer.md

@@ -0,0 +1,7 @@
+# Xenium Prime Human Skin FFPE outs
+<!-- <iframe width="100%" height="750" style="border: 1px solid #d3d3d3; overflow: hidden"
+src="https://observablehq.com/embed/7782aa99166a0eef?cells=root"></iframe> -->
+
+<div id="landscape-container" style="position: relative; display: flex; width: 100%; height: 800px; overflow: hidden; border: 1px solid #ccc;">
+    <div id="landscape-skin-cancer" style="height; 800px;"></div>
+</div>

docs/gallery/index.md

@@ -0,0 +1,14 @@
+# Celldega Gallery
+This page includes links to visualizations that are made with the stand-alone [Celldega JavaScript library](../javascript/index.md).
+
+## Imaging Spatial Transcriptomics
+### Xenium
+<div class="grid cards" markdown>
+
+- [Xenium Mouse Brain ![](../assets/img/xenium_mouse_brain.jpg)](gallery_xenium_mouse_brain.md)
+- [Xenium Human Skin Cancer ![](../assets/img/xenium_human_skin_cancer.jpg)](gallery_xenium_skin_cancer.md)
+
+</div>
+
+## Sequencing Spatial Transcriptomics
+### Visium HD

docs/index.md

@@ -1,17 +1,26 @@
 # Welcome to Celldega's Documentation
-<iframe width="100%" height="575" frameborder="0"
-  src="https://observablehq.com/embed/@cornhundred/celldega-xenium-bone-marrow-example?cells=root"></iframe>
 
+<div id="landscape-container" style="position: relative; display: flex; width: 100%; height: 500px; overflow: hidden; border: 1px solid #ccc;">
+    <div id="landscape" style="height; 500px;"></div>
+</div>
 
-This is the official documentation for the Celldega library.
+<div style="text-align: justify; font-size: 0.9em; color: gray; margin-top: 10px;">
+    Celldega Landscape visualization of a human skin cancer Xenium dataset obtained from <a href='https://www.10xgenomics.com/datasets' target='_blank'>10X Genomics</a>.
+</div>
 
-## Overview
+Celldega is a spatial analysis and visualization library that is being developed by the [Spatial Technology Platform](https://www.broadinstitute.org/spatial-technology-platform) at the [Broad Institute of MIT and Harvard](https://www.broadinstitute.org/spatial-technology-platform). This project enables researchers to easily visualize large ST datasets (e.g., datasets with >100M transcripts) alongside single-cell and spatial analysis notebook workflows (e.g., [sverse](https://scverse.org/) tools and novel spatial analysis approaches).
 
-- [Getting Started](getting_started.md)
-- [Installation](installation.md)
-- [Usage](usage.md)
+- [Getting Started](overview/getting_started.md)
+- [Installation](overview/installation.md)
+- [Usage](overview/usage.md)
 
-## Gallery
+## What's New
+The project was recently presented at the Broad Retreat Data Visualization Breakout Session -
 
+<a href="https://broadinstitute.github.io/Celldega-Broad-Retreat-2024/" target="_blank" rel="noopener noreferrer">
+    <img src="assets/img/Celldega_Broad-Retreat-2024.png" alt="Celldega Broad Retreat 2024" style="display:block; margin:0 auto; width:75%; border:1px solid lightgray; border-radius:5px;">
+</a>
 
-## Embedded Jupyter Notebook
+
+## About
+Celldega is named after a bodega, a small shop with all the essentials that is part of the fabric of a neighborhood.