Updating "Getting Started" information by guittari · Pull Request #61 · aplbrain/BBQS-EMBER-web

guittari · 2025-09-10T21:26:51Z

New Documentation Subpages
- Added a dedicated Standards page under the documentation section
  - Covers: Overview, Data Standards (NWB/BIDS), Metadata Standards, Workflow Guidance, Validation Tools, and EMBER-specific Conventions
  - Replaced old upload/download content with standards-focused expansion items
- Added a dedicated Workflow Guidance page
  - Provides step-by-step instructions for ingest, validation, ancillary files, and submission
  - Structured as expandable sections for clarity

netlify · 2025-09-10T21:26:56Z

✅ Deploy Preview for emberarchive ready!

Name	Link
🔨 Latest commit	`c7eba0a`
🔍 Latest deploy log	https://app.netlify.com/projects/emberarchive/deploys/68fa51e7cb40b100097550a8
😎 Deploy Preview	https://deploy-preview-61--emberarchive.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

erikjohnson24

Some suggested changes for added links/details!

erikjohnson24 · 2025-09-11T13:46:21Z

frontend/src/constants/mainLayout.ts

+      children: [
+        { name: 'Documentation', route: '/documentation', external: false },
+        { name: 'Standards Overview', route: '/standards', external: false },
+        { name: 'Workflow Guidance', route: '/guidance', external: false },


Is "Data Ingest Guidnace" or "Data Upload Guidance" more accessible to users? I wonder if that will be easier for the non-expert user to quickly understand.

+1 to adding extra words to describe which type of workflow this documentation is about (sometimes people have a lot of 'workflows' floating around for all kinds of things)

erikjohnson24 · 2025-09-11T13:50:13Z

frontend/src/pages/OverviewStandardsPage.vue

+        <q-card-section>
+          <div class="text-h4 q-mb-md">Overview</div>
+          <p>
+            EMBER adopts community standards to enable interoperability and reproducibility across multimodal neuroscience datasets.


EMBER has adopted?

erikjohnson24 · 2025-09-11T13:51:14Z

frontend/src/pages/OverviewStandardsPage.vue

+        <div class="q-pa-md">
+          <p>EMBER integrates widely used community standards for data organization:</p>
+          <ul>
+            <li><strong>NWB:</strong> for neurophysiology (ephys, behavior, optophysiology)</li>


do we want to hightlight suggested extensions? NDX-pose and NDX-wearables would make sense to start?

erikjohnson24 · 2025-09-11T13:59:02Z

frontend/src/pages/OverviewStandardsPage.vue

+        </div>
+      </q-expansion-item>
+
+      <q-expansion-item label="Workflow Guidance" icon="directions" class="q-mt-sm">


update name per above? think about it!

erikjohnson24 · 2025-09-11T14:05:24Z

frontend/src/pages/WorkflowGuidancePage.vue

@@ -0,0 +1,77 @@
+<template>
+  <q-page class="column items-center">
+    <PageTitle title="Workflow Guidance" subtitle="Steps for ingest, validation, and data submission" />


again, consider renaiming?

erikjohnson24 · 2025-09-11T14:06:41Z

frontend/src/pages/WorkflowGuidancePage.vue

+          <p>Convert or organize raw data into recognized community formats where possible:</p>
+          <ul>
+            <li>Use NWB for neurophysiology and behavioral time series</li>
+            <li>Use BIDS for imaging, EEG/MEG/iEEG, and derivatives</li>


Add link to examples/how to from BIDS?

Some useful links

Converters: https://bids.neuroimaging.io/tools/converters.html
Tutorials: https://bids.neuroimaging.io/getting_started/tutorials/index.html

erikjohnson24 · 2025-09-11T14:07:00Z

frontend/src/pages/WorkflowGuidancePage.vue

+          <ul>
+            <li>Use NWB for neurophysiology and behavioral time series</li>
+            <li>Use BIDS for imaging, EEG/MEG/iEEG, and derivatives</li>
+            <li>Maintain consistent folder structures and naming conventions</li>


do we have specific recommendations here?

I would just defer/copy & paste from Oliver's document to try to avoid duplication or writing something potentially inconsistent

erikjohnson24 · 2025-09-11T14:15:14Z

frontend/src/pages/WorkflowGuidancePage.vue

+        </div>
+      </q-expansion-item>
+
+      <q-expansion-item label="Step 3: Validate Data" icon="verified" class="q-mt-sm">


provide example commands or links, and expected output for each vaildator? can probably link to or copy paste from relevant documentation?

erikjohnson24 · 2025-09-11T14:15:46Z

frontend/src/pages/WorkflowGuidancePage.vue

+        </div>
+      </q-expansion-item>
+
+      <q-expansion-item label="Step 4: Prepare Ancillary Files" icon="description" class="q-mt-sm">


do we have good examples to point to? maybe one of the existing project we've formatted, or from Dandi?

erikjohnson24 · 2025-09-11T14:16:02Z

frontend/src/pages/WorkflowGuidancePage.vue

+        <div class="q-pa-md">
+          <ol>
+            <li>Ensure you have registered for EMBER-DANDI with your GitHub account</li>
+            <li>Use the DANDI CLI or UI to upload validated datasets</li>


link to dandi cli code or add examples!

NEStock · 2025-09-11T16:40:34Z

frontend/src/pages/OverviewStandardsPage.vue

+        </q-card-section>
+      </q-card>
+
+      <q-expansion-item label="Data Standards (NWB, BIDS)" icon="schema" class="q-mt-md">


I really like the expandable format & the icons! Very clean and easy to read!

Minor UI nitpick: It wasn't immediately obvious to me that these were dropdowns (partially I think b/c I have a large screen and the dropdown icon is all the way on the right, away from the words)
I'm not sure what the best solution is here, but here are some ideas:

adding a border about the expansion items?

making the expansion componenent smaller (i.e. not the full width)

feel free to play around and see what looks best to you!

frontend/src/pages/WorkflowGuidancePage.vue

yarikoptic · 2025-10-16T16:23:54Z

frontend/src/pages/WorkflowGuidancePage.vue

+                  <ul class="q-ml-lg q-mt-sm">
+                    <li>Use NWB for neurophysiology and behavioral time series</li>
+                    <li>Use BIDS for imaging, EEG/MEG/iEEG, and derivatives</li>
+                    <li>Maintain consistent folder structures and naming conventions</li>


I think we might want to improve into

Suggested change

<li>Maintain consistent folder structures and naming conventions</li>

<li>Organize files and metadata following BIDS standard. In rare cases, "DANDI layout" organization of nwb and video files could suffice.</li>

Co-authored-by: Yaroslav Halchenko <debian@onerussian.com>

CodyCBakerPhD · 2025-10-22T15:42:27Z

frontend/src/pages/OverviewStandardsPage.vue

+            <a href="https://bids.neuroimaging.io/index.html" target="_blank" rel="noopener" class="link">BIDS</a> 
+            and 
+            <a href="https://nwb.org/about-nwb/" target="_blank" rel="noopener" class="link">NWB</a> 
+            formats, along with hybrid layouts that combine both where appropriate, and anticipate accepting new standards. 


Suggested change

formats, along with hybrid layouts that combine both where appropriate, and anticipate accepting new standards.

formats, along with hybrid layouts that combine both where appropriate.

I'd suggest not planting abstract seeds of 'expectations' since 'who knows what will happen' in the future

Can (and should) always come back and modify the line if something changes later down the road

CodyCBakerPhD · 2025-10-22T15:46:43Z

frontend/src/pages/OverviewStandardsPage.vue

+              <q-item-section>
+                <q-item-label overline>Scope</q-item-label>
+                <q-item-label>
+                  Neurophysiology including ephys, behavior, optical physiology, and multimodal time series.


Suggested change

Neurophysiology including ephys, behavior, optical physiology, and multimodal time series.

Neurophysiology data, such as extracellular or intracellular electrophysiology (including EEG/iEEG), optical physiology, together with behavior, other multimodal time series, metadata tables, and annotated events.

CodyCBakerPhD · 2025-10-22T15:48:11Z

frontend/src/pages/OverviewStandardsPage.vue

+              <q-item-section>
+                <q-item-label overline>Scope</q-item-label>
+                <q-item-label>
+                  MRI, EEG/MEG/iEEG, diffusion, functional, microscopy, behavioral logs, and derivatives.


Suggested change

MRI, EEG/MEG/iEEG, diffusion, functional, microscopy, behavioral logs, and derivatives.

MRI/fMRI, EEG/MEG/iEEG, diffusion, microscopy, behavioral logs, and derivatives.

Is this clearer?

Also is 'diffusion' clear enough on its own?

CodyCBakerPhD · 2025-10-22T15:55:30Z

frontend/src/pages/OverviewStandardsPage.vue

+              <q-item-section>
+                <q-item-label overline>NWB Validation</q-item-label>
+                <q-item-label>
+                  Validate with <code>pynwb validate</code> or NWBInspector for schema compliance and metadata completeness.


Suggested change

Validate with <code>pynwb validate</code> or NWBInspector for schema compliance and metadata completeness.

Validate with <a href="https://nwbinspector.readthedocs.io/en/dev/index.html" target="_blank" rel="noopener" class="link">NWB Inspector</a> for schema compliance and metadata completeness.

To have one fewer thing to 'need to know'

FYI the NWB Inspector also runs and reports pynwb validate

CodyCBakerPhD · 2025-10-22T15:57:54Z

frontend/src/pages/WorkflowGuidancePage.vue

+                </q-item-label>
+                <q-item-label>
+                  <ul class="q-ml-lg q-mt-sm">
+                    <li>Use NWB for neurophysiology and behavioral time series</li>


Suggested change

<li>Use NWB for neurophysiology and behavioral time series</li>

<li>Convert data files to NWB format for neurophysiology and behavioral time series</li>

CodyCBakerPhD · 2025-10-22T16:00:17Z

frontend/src/pages/WorkflowGuidancePage.vue

+                <q-item-label>
+                  <ul class="q-ml-lg q-mt-sm">
+                    <li>Use NWB for neurophysiology and behavioral time series</li>
+                    <li>Use file formats defined in BIDS for imaging, EEG/MEG/iEEG, and derivatives</li>


Suggested change

<li>Use file formats defined in BIDS for imaging, EEG/MEG/iEEG, and derivatives</li>

<li>Use file formats defined in BIDS for imaging, EEG/MEG/iEEG (including NWB where applicable), and derivatives</li>

CodyCBakerPhD · 2025-10-22T16:06:00Z

frontend/src/pages/WorkflowGuidancePage.vue

+      <!-- Step 2: Populate Metadata -->
+      <q-card flat class="q-mt-lg">
+        <q-card-section>
+          <div class="text-h2 scrollable">Step 2: Populate Metadata</div>


This is a great section to have, but for people to really walk away with something useful they will need practical examples

(which should be added in a separate PR IMO, so we can hash out or perfect items there)

Example: NCBI taxonomy format for species, UBERON codes for an anotomy or disorder, etc.

CodyCBakerPhD · 2025-10-22T16:34:03Z

frontend/src/pages/WorkflowGuidancePage.vue

+                  <ul class="q-ml-lg q-mt-sm">
+                    <li>README files describing dataset contents and organization</li>
+                    <li>Methodological notes or data processing scripts</li>
+                    <li>Supplementary documentation (e.g., experimental protocols)</li>


More of a policy decision to bring up to DCAIC perhaps; should we recommend/require use of protocols.io?

BICAN/BICCN used this to great effect: https://www.protocols.io/workspaces/biccn/publications

Though such things are much more common in the wet labs of pathology/histology

CodyCBakerPhD · 2025-10-22T16:36:34Z

frontend/src/pages/WorkflowGuidancePage.vue

+      <!-- Step 4: Prepare Ancillary Files -->
+      <q-card flat class="q-mt-lg">
+        <q-card-section>
+          <div class="text-h2 scrollable">Step 4: Prepare Ancillary Files</div>


This section is interesting. While I appreciate it is there (and appreciate anyone who actually does it) one question is how are data submitters expected to include these ancillary files?

Without guidance (e.g., 'submit these files to a GitHub repository or Zenodo dataset and link that repository/dataset to this EMBER-Dandiset'), this section could be confusing

CodyCBakerPhD · 2025-10-22T16:38:07Z

frontend/src/pages/WorkflowGuidancePage.vue

+                <q-item-label overline>Submission</q-item-label>
+                <q-item-label>
+                  <ol class="q-ml-lg q-mt-sm">
+                    <li>Ensure you have registered for EMBER-DANDI with your GitHub account</li>


Does this authentication happen automatically or does it (like DANDI) require admin approval for new registrants? If the latter, perhaps this should be moved to the top as a pre-step (since there might be a temporal delay) as well as a mention to that extent (e.g., 'it may take up to X days for the account to be approved' or so)

CodyCBakerPhD · 2025-10-22T16:38:25Z

Overall looks great - left my comments and impressions!

guittari added 4 commits September 10, 2025 17:21

Updating to include data model information

67150bc

Adding outlines for each new page

4562aff

Update DocumentationPage.vue

e0297fe

Update DocumentationPage.vue

da210af

guittari linked an issue Sep 10, 2025 that may be closed by this pull request

Data Model Tab #50

Open

erikjohnson24 requested changes Sep 11, 2025

View reviewed changes

NEStock reviewed Sep 11, 2025

View reviewed changes

Updating standards pages

4a9e3b5

yarikoptic reviewed Oct 16, 2025

View reviewed changes

frontend/src/pages/WorkflowGuidancePage.vue Outdated Show resolved Hide resolved

yarikoptic reviewed Oct 16, 2025

View reviewed changes

Update frontend/src/pages/WorkflowGuidancePage.vue

4519ce7

Co-authored-by: Yaroslav Halchenko <debian@onerussian.com>

CodyCBakerPhD reviewed Oct 22, 2025

View reviewed changes

Merge branch 'main' into 50-data-model-tab

c7eba0a

	<li>Maintain consistent folder structures and naming conventions</li>
	<li>Organize files and metadata following BIDS standard. In rare cases, "DANDI layout" organization of nwb and video files could suffice.</li>

	formats, along with hybrid layouts that combine both where appropriate, and anticipate accepting new standards.
	formats, along with hybrid layouts that combine both where appropriate.

	Neurophysiology including ephys, behavior, optical physiology, and multimodal time series.
	Neurophysiology data, such as extracellular or intracellular electrophysiology (including EEG/iEEG), optical physiology, together with behavior, other multimodal time series, metadata tables, and annotated events.

	MRI, EEG/MEG/iEEG, diffusion, functional, microscopy, behavioral logs, and derivatives.
	MRI/fMRI, EEG/MEG/iEEG, diffusion, microscopy, behavioral logs, and derivatives.

	Validate with <code>pynwb validate</code> or NWBInspector for schema compliance and metadata completeness.
	Validate with <a href="https://nwbinspector.readthedocs.io/en/dev/index.html" target="_blank" rel="noopener" class="link">NWB Inspector</a> for schema compliance and metadata completeness.

	<li>Use NWB for neurophysiology and behavioral time series</li>
	<li>Convert data files to NWB format for neurophysiology and behavioral time series</li>

	<li>Use file formats defined in BIDS for imaging, EEG/MEG/iEEG, and derivatives</li>
	<li>Use file formats defined in BIDS for imaging, EEG/MEG/iEEG (including NWB where applicable), and derivatives</li>

Conversation

guittari commented Sep 10, 2025

Uh oh!

netlify bot commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for emberarchive ready!

Uh oh!

erikjohnson24 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CodyCBakerPhD commented Oct 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

netlify bot commented Sep 10, 2025 •

edited

Loading