# genevievewager/hippo architecture

> Architecture diagram of the GitHub repository genevievewager/hippo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/genevievewager/hippo
- Repository: https://github.com/genevievewager/hippo

## Overview

HIPPO is a hippocampal BCI simulation, decoder-search, and deployment testbed. Its main workflow simulates behavior and neural populations, models acquisition degradation and sorting, constructs causal spike observations, compares static and dynamic representations and decoders, selects deployable models, then evaluates replay and closed-loop policies. Users enter through the CLI scripts or Streamlit UI; visualization inspects saved results rather than retraining. The graph follows the documented workflow and sampled pipeline-state/UI code; several scientific stage internals were not sampled, so their exact call wiring is not expanded.

Main entry points: [`hippo/dataset.py`](https://github.com/genevievewager/hippo/blob/master/hippo/dataset.py) (Experiment dataset), [`run_simulation.py`](https://github.com/genevievewager/hippo/blob/master/run_simulation.py) (CLI workflows), [`ui/app.py`](https://github.com/genevievewager/hippo/blob/master/ui/app.py) (Streamlit app), [`realtime/neural_features/extractor.py`](https://github.com/genevievewager/hippo/blob/master/realtime/neural_features/extractor.py) (Neural features)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["CLI workflows<br/>[run_simulation.py]"]
  node_ui["Streamlit app<br/>[app.py]"]
end

subgraph group_simulation["Simulation"]
  node_behavior["Behavior simulation<br/>[behavior.py]"]
  node_populations["Hippocampal populations"]
  node_anatomy["Probe anatomy<br/>[anatomy.py]"]
  node_acquisition["Acquisition and sorting<br/>[pipeline.py]"]
  node_dataset["Experiment dataset<br/>[dataset.py]"]
end

subgraph group_science["Neural decoding"]
  node_observation["Causal observations<br/>[observation.py]"]
  node_features["Neural features<br/>[extractor.py]"]
  node_representations["Static manifolds<br/>[registry.py]"]
  node_latents["Dynamic latents<br/>[registry.py]"]
  node_decoders["Decoder search"]
end

subgraph group_deployment["Deployment"]
  node_selection["Deployment selection"]
  node_registry["Lab registry<br/>[lab_deployable.py]"]
  node_replay["Realtime replay<br/>[live_decoder.py]"]
  node_closedloop["Closed-loop policy"]
  node_bundle["Live bundle"]
end

subgraph group_state["State and inspection"]
  node_pipeline[("Pipeline provenance<br/>[pipeline_graph.py]")]
  node_visualization["Saved-result figures<br/>[load_outputs.py]"]
end

node_user(("Experimenter"))
node_livehardware(("Open Ephys"))

node_user -->|"runs workflow"| node_cli
node_user -->|"uses pages"| node_ui
node_cli -->|"starts simulation"| node_behavior
node_behavior -->|"drives activity"| node_populations
node_populations -->|"uses anatomy"| node_anatomy
node_cli -->|"runs pipeline"| node_acquisition
node_acquisition -->|"writes dataset"| node_dataset
node_dataset -->|"supplies spikes"| node_observation
node_observation -->|"constructs inputs"| node_features
node_features -->|"fits representations"| node_representations
node_features -->|"fits latent states"| node_latents
node_representations -->|"provides embeddings"| node_decoders
node_latents -->|"provides states"| node_decoders
node_decoders -->|"scores candidates"| node_selection
node_selection -->|"exports winners"| node_registry
node_registry -->|"loads models"| node_replay
node_replay -->|"supplies predictions"| node_closedloop
node_selection -->|"packs deployment"| node_bundle
node_bundle -.->|"targets integration"| node_livehardware
node_ui -->|"selects dataset"| node_dataset
node_ui -->|"reads status"| node_pipeline
node_pipeline -->|"tracks stages"| node_dataset
node_cli -->|"visualizes outputs"| node_visualization
node_dataset -->|"loads saved results"| node_visualization

click node_cli "https://github.com/genevievewager/hippo/blob/master/run_simulation.py"
click node_ui "https://github.com/genevievewager/hippo/blob/master/ui/app.py"
click node_behavior "https://github.com/genevievewager/hippo/blob/master/hippo_sim/behavior.py"
click node_populations "https://github.com/genevievewager/hippo/blob/master/hippo_sim/hippocampal_populations.py"
click node_anatomy "https://github.com/genevievewager/hippo/blob/master/hippo_sim/anatomy.py"
click node_acquisition "https://github.com/genevievewager/hippo/blob/master/hippo_sim/pipeline.py"
click node_dataset "https://github.com/genevievewager/hippo/blob/master/hippo/dataset.py"
click node_observation "https://github.com/genevievewager/hippo/blob/master/realtime/observation.py"
click node_features "https://github.com/genevievewager/hippo/blob/master/realtime/neural_features/extractor.py"
click node_representations "https://github.com/genevievewager/hippo/blob/master/realtime/manifolds/registry.py"
click node_latents "https://github.com/genevievewager/hippo/blob/master/realtime/dynamic_latents/registry.py"
click node_decoders "https://github.com/genevievewager/hippo/blob/master/realtime/decoder_comparison.py"
click node_selection "https://github.com/genevievewager/hippo/blob/master/realtime/deployment_selection.py"
click node_registry "https://github.com/genevievewager/hippo/blob/master/realtime/lab_deployable.py"
click node_replay "https://github.com/genevievewager/hippo/blob/master/realtime/live_decoder.py"
click node_closedloop "https://github.com/genevievewager/hippo/blob/master/realtime/closed_loop_controller.py"
click node_bundle "https://github.com/genevievewager/hippo/blob/master/realtime/deployment_bundle.py"
click node_pipeline "https://github.com/genevievewager/hippo/blob/master/realtime/pipeline_graph.py"
click node_visualization "https://github.com/genevievewager/hippo/blob/master/visualization/load_outputs.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_ui toneBlue
class node_behavior,node_populations,node_anatomy,node_acquisition,node_dataset toneAmber
class node_observation,node_features,node_representations,node_latents,node_decoders toneMint
class node_selection,node_registry,node_replay,node_closedloop,node_bundle toneRose
class node_pipeline,node_visualization,node_user,node_livehardware toneIndigo
```

## Components

### User entry

- [CLI workflows](https://github.com/genevievewager/hippo/blob/master/run_simulation.py): `run_simulation.py`
- [Streamlit app](https://github.com/genevievewager/hippo/blob/master/ui/app.py): `ui/app.py`

### Simulation

- [Behavior simulation](https://github.com/genevievewager/hippo/blob/master/hippo_sim/behavior.py): `hippo_sim/behavior.py`
- [Hippocampal populations](https://github.com/genevievewager/hippo/blob/master/hippo_sim/hippocampal_populations.py): `hippo_sim/hippocampal_populations.py`
- [Probe anatomy](https://github.com/genevievewager/hippo/blob/master/hippo_sim/anatomy.py): `hippo_sim/anatomy.py`
- [Acquisition and sorting](https://github.com/genevievewager/hippo/blob/master/hippo_sim/pipeline.py): `hippo_sim/pipeline.py`
- [Experiment dataset](https://github.com/genevievewager/hippo/blob/master/hippo/dataset.py): `hippo/dataset.py`

### Neural decoding

- [Causal observations](https://github.com/genevievewager/hippo/blob/master/realtime/observation.py): `realtime/observation.py`
- [Neural features](https://github.com/genevievewager/hippo/blob/master/realtime/neural_features/extractor.py): `realtime/neural_features/extractor.py`
- [Static manifolds](https://github.com/genevievewager/hippo/blob/master/realtime/manifolds/registry.py): `realtime/manifolds/registry.py`
- [Dynamic latents](https://github.com/genevievewager/hippo/blob/master/realtime/dynamic_latents/registry.py): `realtime/dynamic_latents/registry.py`
- [Decoder search](https://github.com/genevievewager/hippo/blob/master/realtime/decoder_comparison.py): `realtime/decoder_comparison.py`

### Deployment

- [Deployment selection](https://github.com/genevievewager/hippo/blob/master/realtime/deployment_selection.py): `realtime/deployment_selection.py`
- [Lab registry](https://github.com/genevievewager/hippo/blob/master/realtime/lab_deployable.py): `realtime/lab_deployable.py`
- [Realtime replay](https://github.com/genevievewager/hippo/blob/master/realtime/live_decoder.py): `realtime/live_decoder.py`
- [Closed-loop policy](https://github.com/genevievewager/hippo/blob/master/realtime/closed_loop_controller.py): `realtime/closed_loop_controller.py`
- [Live bundle](https://github.com/genevievewager/hippo/blob/master/realtime/deployment_bundle.py): `realtime/deployment_bundle.py`

### State and inspection

- [Pipeline provenance](https://github.com/genevievewager/hippo/blob/master/realtime/pipeline_graph.py): `realtime/pipeline_graph.py`
- [Saved-result figures](https://github.com/genevievewager/hippo/blob/master/visualization/load_outputs.py): `visualization/load_outputs.py`

### Other components

- **Experimenter**
- **Open Ephys**

## Connections

- Experimenter → CLI workflows: runs workflow
- Experimenter → Streamlit app: uses pages
- CLI workflows → Behavior simulation: starts simulation
- Behavior simulation → Hippocampal populations: drives activity
- Hippocampal populations → Probe anatomy: uses anatomy
- CLI workflows → Acquisition and sorting: runs pipeline
- Acquisition and sorting → Experiment dataset: writes dataset
- Experiment dataset → Causal observations: supplies spikes
- Causal observations → Neural features: constructs inputs
- Neural features → Static manifolds: fits representations
- Neural features → Dynamic latents: fits latent states
- Static manifolds → Decoder search: provides embeddings
- Dynamic latents → Decoder search: provides states
- Decoder search → Deployment selection: scores candidates
- Deployment selection → Lab registry: exports winners
- Lab registry → Realtime replay: loads models
- Realtime replay → Closed-loop policy: supplies predictions
- Deployment selection → Live bundle: packs deployment
- Live bundle → Open Ephys: targets integration
- Streamlit app → Experiment dataset: selects dataset
- Streamlit app → Pipeline provenance: reads status
- Pipeline provenance → Experiment dataset: tracks stages
- CLI workflows → Saved-result figures: visualizes outputs
- Experiment dataset → Saved-result figures: loads saved results