Merge pull request #135 from arnor-sigurdsson/add-how-eir-works-docs

Add how eir works docs

Author: arnor-sigurdsson

docs/configuration_guides/guides_index.rst

@@ -1,3 +1,5 @@
+.. _configuration_guides:
+
 Configuration Guides
 ====================
 

docs/design/design.rst

@@ -0,0 +1,83 @@
+.. _how-eir-works:
+
+How EIR Works
+=============
+
+The idea with EIR is to make deep learning
+**modular, reproducible, and accessible across different data types**.
+
+Core Design Philosophy
+----------------------
+
+**Declarative Design**
+    Everything, from data sources, how data is processed,
+    to model architectures and output specifications,
+    is defined in YAML files.
+    No scripting required for standard workflows.
+
+**Modular Architecture**
+    Each component (inputs, fusion, outputs) is independent and configurable.
+    Mix and match different data types (kind of like LEGO blocks)
+    and models without changing code.
+
+**Consistent Interface**
+    Whether you're working with genomics, images, text or something else
+    - the workflow is the same:
+    **configure → train → predict/serve**.
+
+Architecture Overview
+---------------------
+
+The diagram below shows a typical workflow in EIR
+and, what each configuration file is responsible for,
+and how the different neural network "blocks" specified
+via the configurations interact with each other.
+**Click on the image to enlarge it.**
+
+.. figure:: static/img/eir_design.svg
+   :width: 100%
+   :align: center
+
+|
+
+Why This Design?
+----------------
+
+**Reproducibility**
+    YAML configs capture the entire experiment and can be shared easily.
+
+**Extensibility**
+    Add new data types or models without breaking existing workflows.
+    The modular design means you can experiment with one
+    component while keeping others fixed.
+
+**Practical ML**
+    Real-world problems often involve multiple data types,
+    where different samples can be missing for different modalities.
+    EIR makes developing models for this type of multi-modal data easier.
+
+**From Research to Production**
+    The same model that trains on your laptop,
+    or on your HPC cluster,
+    can be deployed as a web service with one command.
+
+Other Key Features
+------------------
+
+**Explainability**
+    Built-in attribution analysis shows which features matter most for predictions
+    when doing supervised learning (classification and regression).
+
+**Streaming Support**
+   Implement your own data streaming logic to handle large datasets, or if you
+   want to customize how data is fed into the model.
+
+**Easy Deployment**
+    Every trained model becomes a REST API with ``eirserve``.
+    No additional infrastructure needed.
+
+Getting Started
+---------------
+
+The best way to understand EIR is to try it,
+check :ref:`01-genotype-tutorial` to see the basic workflow

docs/design/static/img/eir_design.svg

@@ -1,10 +1,11 @@
 EIR
 ===
 
-``EIR`` is a framework for
+EIR is a framework for
 supervised modelling,
-sequence generation and
-array generation
+sequence generation,
+survival analysis, and
+image/array generation
 on genotype, tabular, sequence, image, array, and binary input data.
 It is designed to provide
 a high-level, yet modular API
@@ -20,6 +21,10 @@ and pre-processing required to train a model.
 
 |
 
+.. contents::
+   :local:
+   :depth: 1
+
 TL;DR - Just Show Me How It Works
 ---------------------------------
 
@@ -37,6 +42,29 @@ for an example that covers:
 
 Or browse the :doc:`tutorials/tutorial_index` to see examples for your specific data type.
 
+How to Navigate This Documentation
+----------------------------------
+
+The documentation is not designed to be read from start to finish,
+so feel free to jump around and explore the sections that interest you.
+
+Generally we do recommend starting with either:
+
+* :ref:`01-genotype-tutorial` for a complete end-to-end example, or
+* :ref:`how-eir-works` for an overview of the framework's design and general architecture.
+
+Then, you can for example explore the following sections:
+
+* :ref:`tutorials_index` for various tutorials ranging from
+  supervised learning with a single modality,
+  to multi-modal generative modelling and serving.
+* :ref:`configuration_guides` for kind of a mix between cheat-sheets and more in-depth
+  guides focusing on specific configurations
+  (e.g., a boilerplate ``globals.yaml`` file) or data types
+  (e.g., how to configure EIR for genomic data).
+* :ref:`api-reference` for a complete reference of all configuration options.
+* :ref:`user-guides-index` for various user guides, tips and tricks.
+
 Installation
 ------------
 
@@ -118,17 +146,13 @@ EIR automatically detects and uses GPU acceleration when available.
 No additional configuration is required if you have a CUDA-compatible setup
 with PyTorch GPU support. It should also work with MPS on macOS.
 
-Quick Start
------------
-
-**Ready to start?** Follow the :ref:`01-genotype-tutorial` for a complete walkthrough.
-
 Documentation
 -------------
 
 .. toctree::
     :maxdepth: 2
 
+    design/design
     tutorials/tutorial_index
     user_guides/user_guides_index
     api/api_index

docs/index.rst

@@ -1,3 +1,5 @@
+.. _tutorials_index:
+
 Tutorials: Supervised Learning
 ==============================
 

docs/tutorials/tutorial_index.rst

@@ -1,3 +1,5 @@
+.. _user-guides-index:
+
 User Guides
 ===========