From f11dc6d492a16e35ef1efa2732414a722a4bf7bf Mon Sep 17 00:00:00 2001
From: mschwoerer <82171591+mschwoer@users.noreply.github.com>
Date: Tue, 27 Jan 2026 14:42:01 +0100
Subject: [PATCH 1/3] make alphamap optional and update installation
 instructions

---
 .github/workflows/e2e_tests_quick.yml         |  2 +-
 .../e2e_tests_quick_multiple_platforms.yml    |  4 +--
 .github/workflows/install_and_unit_tests.yml  |  2 +-
 ...tall_and_unit_tests_multiple_platforms.yml |  4 +--
 .github/workflows/run_example_nbs.yml         |  2 +-
 README.md                                     | 10 ++++++
 alphaquant/plotting/alphamapviz.py            | 33 +++++++++++++++----
 alphaquant/plotting/fcviz.py                  | 12 ++++++-
 .../ui/dashboard_parts_plots_proteoforms.py   |  6 ++++
 pyproject.toml                                |  2 ++
 requirements/requirements.txt                 |  1 -
 requirements/requirements_alphamap.txt        |  1 +
 requirements/requirements_alphamap_loose.txt  |  1 +
 requirements/requirements_loose.txt           |  1 -
 14 files changed, 64 insertions(+), 17 deletions(-)
 create mode 100644 requirements/requirements_alphamap.txt
 create mode 100644 requirements/requirements_alphamap_loose.txt

diff --git a/.github/workflows/e2e_tests_quick.yml b/.github/workflows/e2e_tests_quick.yml
index b91ba434..4e498919 100644
--- a/.github/workflows/e2e_tests_quick.yml
+++ b/.github/workflows/e2e_tests_quick.yml
@@ -28,5 +28,5 @@ jobs:
     with:
       python-version: ${{ matrix.python-version }}
       os: ${{ matrix.os }}
-      install-script: ./pip_install.sh tests,gui,dask
+      install-script: ./pip_install.sh tests,gui,dask,alphamap
       test-script: ./run_e2e_tests_quick.sh
diff --git a/.github/workflows/e2e_tests_quick_multiple_platforms.yml b/.github/workflows/e2e_tests_quick_multiple_platforms.yml
index 8beb55fb..78292b67 100644
--- a/.github/workflows/e2e_tests_quick_multiple_platforms.yml
+++ b/.github/workflows/e2e_tests_quick_multiple_platforms.yml
@@ -29,7 +29,7 @@ jobs:
     with:
       python-version: ${{ matrix.python-version }}
       os: ${{ matrix.os }}
-      install-script: ./pip_install.sh stable,tests,gui,dask-stable
+      install-script: ./pip_install.sh stable,tests,gui,dask-stable,alphamap-stable
       test-script: ./run_e2e_tests_quick.sh
 
   run-unit-tests-loose:
@@ -43,5 +43,5 @@ jobs:
     with:
       python-version: ${{ matrix.python-version }}
       os: ${{ matrix.os }}
-      install-script: ./pip_install.sh tests,gui,dask
+      install-script: ./pip_install.sh tests,gui,dask,alphamap
       test-script: ./run_e2e_tests_quick.sh
diff --git a/.github/workflows/install_and_unit_tests.yml b/.github/workflows/install_and_unit_tests.yml
index e2911ffa..0a48ad36 100644
--- a/.github/workflows/install_and_unit_tests.yml
+++ b/.github/workflows/install_and_unit_tests.yml
@@ -30,5 +30,5 @@ jobs:
     with:
       python-version: ${{ matrix.python-version }}
       os: ${{ matrix.os }}
-      install-script: ./pip_install.sh tests,gui,dask
+      install-script: ./pip_install.sh tests,gui,dask,alphamap
       test-script: ./run_unit_tests.sh
diff --git a/.github/workflows/install_and_unit_tests_multiple_platforms.yml b/.github/workflows/install_and_unit_tests_multiple_platforms.yml
index 16ae5482..3a34b963 100644
--- a/.github/workflows/install_and_unit_tests_multiple_platforms.yml
+++ b/.github/workflows/install_and_unit_tests_multiple_platforms.yml
@@ -26,7 +26,7 @@ jobs:
     with:
       python-version: ${{ matrix.python-version }}
       os: ${{ matrix.os }}
-      install-script: ./pip_install.sh stable,tests,gui,dask-stable
+      install-script: ./pip_install.sh stable,tests,gui,dask-stable,alphamap-stable
       test-script: ./run_unit_tests.sh
 
   run-unit-tests-loose:
@@ -40,5 +40,5 @@ jobs:
     with:
       python-version: ${{ matrix.python-version }}
       os: ${{ matrix.os }}
-      install-script: ./pip_install.sh tests,gui,dask
+      install-script: ./pip_install.sh tests,gui,dask,alphamap
       test-script: ./run_unit_tests.sh
diff --git a/.github/workflows/run_example_nbs.yml b/.github/workflows/run_example_nbs.yml
index 7262b4bb..e71f3a9e 100644
--- a/.github/workflows/run_example_nbs.yml
+++ b/.github/workflows/run_example_nbs.yml
@@ -28,5 +28,5 @@ jobs:
     with:
       python-version: ${{ matrix.python-version }}
       os: ${{ matrix.os }}
-      install-script: ./pip_install.sh tests,gui,dask
+      install-script: ./pip_install.sh tests,gui,dask,alphamap
       test-script: ./run_example_notebooks.sh
diff --git a/README.md b/README.md
index 8199ce68..fa594ea6 100644
--- a/README.md
+++ b/README.md
@@ -114,6 +114,16 @@ or the version with a pinned dependency (recommended)
 pip install "alphaquant[dask-stable]"
 ```
 
+For AlphaMap visualization features (sequence alignment plots), install the optional alphamap extra:
+
+```bash
+pip install "alphaquant[alphamap]"
+```
+or the version with a pinned dependency (recommended)
+```bash
+pip install "alphaquant[alphamap-stable]"
+```
+
 ### Developer installation
 
 AlphaQuant can also be installed in editable (i.e. developer) mode with a few `bash` commands. This allows to fully customize the software and even modify the source code to your specific needs. When an editable Python package is installed, its source code is stored in a transparent location of your choice. While optional, it is advised to first (create and) navigate to e.g. a general software folder:
diff --git a/alphaquant/plotting/alphamapviz.py b/alphaquant/plotting/alphamapviz.py
index d8fc0aba..6ab9eb59 100644
--- a/alphaquant/plotting/alphamapviz.py
+++ b/alphaquant/plotting/alphamapviz.py
@@ -1,14 +1,10 @@
+import warnings
+
 import numpy as np
 import pandas as pd
 import anytree
 import alphaquant.utils.utils as aqutils
 import alphaquant.resources.database_loader as aq_db_loader
-
-
-import alphamap.preprocessing
-import alphamap.organisms_data
-import alphamap.sequenceplot
-import alphamap.uniprot_integration
 import alphaquant.plotting.fcviz as aq_plot_fc
 import alphaquant.plotting.colors as aq_plot_colors
 
@@ -17,13 +13,31 @@
 aqconfig.setup_logging()
 LOGGER = logging.getLogger(__name__)
 
+try:
+    import alphamap.preprocessing
+    import alphamap.organisms_data
+    import alphamap.sequenceplot
+    import alphamap.uniprot_integration
+    HAS_ALPHAMAP = True
+except ModuleNotFoundError:
+    warnings.warn(
+        "Dependency 'alphamap' not installed. If you want to use its functionality, install alphaquant with the 'alphamap' extra."
+    )
+    HAS_ALPHAMAP = False
+
 
 class AlphaMapVisualizer:
     def __init__(self, condition1, condition2, results_directory, samplemap_file,
             order_along_protein_sequence = True, organism = 'Human',colorlist = aq_plot_colors.AlphaQuantColorMap().colorlist, tree_level = 'seq',
             protein_identifier = 'gene_symbol', label_rotation = 90, add_stripplot = False,
             narrowing_factor_for_fcplot = 1/14, rescale_factor_x = 1.0, rescale_factor_y = 2):
-        
+
+        if not HAS_ALPHAMAP:
+            raise ImportError(
+                "alphamap is required for AlphaMapVisualizer. "
+                "Install it with: pip install \"alphaquant[alphamap]\""
+            )
+
         """
         Initializes an object for visualizing peptide fold changes and AlphaMap sequence alignment. 
         This class allows for the visualization of different proteins by using the visualize_protein method 
@@ -86,6 +100,11 @@ def visualize_protein(self, protein):
 class AlphaMapDfGenerator:
 
     def __init__(self, condpair_node, gene2protein_mapper, organism = 'Human', colorlist = []):
+        if not HAS_ALPHAMAP:
+            raise ImportError(
+                "alphamap is required for AlphaMapDfGenerator. "
+                "Install it with: pip install \"alphaquant[alphamap]\""
+            )
         self._condpair_node = condpair_node
         self._gene2protein_mapper = gene2protein_mapper
 
diff --git a/alphaquant/plotting/fcviz.py b/alphaquant/plotting/fcviz.py
index ce49fe7e..1851d857 100644
--- a/alphaquant/plotting/fcviz.py
+++ b/alphaquant/plotting/fcviz.py
@@ -3,11 +3,16 @@
 import alphaquant.cluster.cluster_utils as aqclustutils
 import alphaquant.plotting.base_functions as aq_plot_base
 import alphaquant.config.variables as aqvars
-import alphamap.organisms_data
 import alphaquant.utils.utils as aq_utils
 import alphaquant.resources.database_loader as aq_db_loader
 import re
 
+try:
+    import alphamap.organisms_data
+    HAS_ALPHAMAP = True
+except ModuleNotFoundError:
+    HAS_ALPHAMAP = False
+
 def _format_tree_label_string(labelstring: str) -> str:
     """Local copy of the tree label formatter to avoid circular imports.
 
@@ -198,6 +203,11 @@ def _load_sequences(self):
 
 
 def get_pyteomics_fasta(organism = 'Human'):
+        if not HAS_ALPHAMAP:
+            raise ImportError(
+                "alphamap is required for get_pyteomics_fasta. "
+                "Install it with: pip install \"alphaquant[alphamap]\""
+            )
         return alphamap.organisms_data.import_fasta(organism)
 
 class CondpairQuantificationInfo():
diff --git a/alphaquant/ui/dashboard_parts_plots_proteoforms.py b/alphaquant/ui/dashboard_parts_plots_proteoforms.py
index 3c86524f..2ed1a9dd 100644
--- a/alphaquant/ui/dashboard_parts_plots_proteoforms.py
+++ b/alphaquant/ui/dashboard_parts_plots_proteoforms.py
@@ -365,6 +365,12 @@ def _on_load_alphamap_clicked(self, event):
             self.visualization_elements.visible = True
             self.viz_warning_pane.object = ""  # Clear any previous warnings
 
+        except ImportError as import_error:
+            print("ImportError initializing visualizers:", str(import_error))
+            error_msg = f"AlphaMap is not installed. Install it with: pip install \"alphaquant[alphamap]\""
+            self.viz_warning_pane.object = f"### Note\n{error_msg}"
+            self.visualization_elements.visible = False
+
         except Exception as viz_error:
             print("Error initializing visualizers:", str(viz_error))
             print("Exception type:", type(viz_error))
diff --git a/pyproject.toml b/pyproject.toml
index 5b1126f4..67bb521c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -55,6 +55,8 @@ optional-dependencies = { stable = { file = ["requirements/requirements.txt",
 ] }, development = { file = ["requirements/requirements_development.txt", "requirements/requirements_tests.txt",
 ] }, dask = { file = [ "requirements/requirements_dask_loose.txt",
 ] }, dask-stable = { file = [ "requirements/requirements_dask.txt",
+] }, alphamap = { file = [ "requirements/requirements_alphamap_loose.txt",
+] }, alphamap-stable = { file = [ "requirements/requirements_alphamap.txt",
 ] }}
 
 version = {attr = "alphaquant.__version__"}
diff --git a/requirements/requirements.txt b/requirements/requirements.txt
index 09f7aeb6..de07783c 100644
--- a/requirements/requirements.txt
+++ b/requirements/requirements.txt
@@ -12,6 +12,5 @@ lmfit==1.3.2
 multiprocess==0.70.17
 openpyxl==3.1.5
 scikit-learn==1.6.1
-alphamap==0.2.0
 alphabase==1.6.0
 pyarrow==19.0.0
diff --git a/requirements/requirements_alphamap.txt b/requirements/requirements_alphamap.txt
new file mode 100644
index 00000000..1b80b934
--- /dev/null
+++ b/requirements/requirements_alphamap.txt
@@ -0,0 +1 @@
+alphamap==0.2.0
diff --git a/requirements/requirements_alphamap_loose.txt b/requirements/requirements_alphamap_loose.txt
new file mode 100644
index 00000000..1c317e43
--- /dev/null
+++ b/requirements/requirements_alphamap_loose.txt
@@ -0,0 +1 @@
+alphamap
diff --git a/requirements/requirements_loose.txt b/requirements/requirements_loose.txt
index 7be25089..07a6e379 100644
--- a/requirements/requirements_loose.txt
+++ b/requirements/requirements_loose.txt
@@ -13,5 +13,4 @@ multiprocess
 openpyxl
 scikit-learn
 alphabase
-alphamap
 pyarrow

From bc514f55b7fde7c051e7c454efc6d8a0c0a99f23 Mon Sep 17 00:00:00 2001
From: mschwoerer <82171591+mschwoer@users.noreply.github.com>
Date: Tue, 27 Jan 2026 14:55:48 +0100
Subject: [PATCH 2/3] update alphamap dependency handling and installation
 instructions

---
 alphaquant/plotting/alphamapviz.py | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/alphaquant/plotting/alphamapviz.py b/alphaquant/plotting/alphamapviz.py
index 6ab9eb59..1a785bdb 100644
--- a/alphaquant/plotting/alphamapviz.py
+++ b/alphaquant/plotting/alphamapviz.py
@@ -21,7 +21,7 @@
     HAS_ALPHAMAP = True
 except ModuleNotFoundError:
     warnings.warn(
-        "Dependency 'alphamap' not installed. If you want to use its functionality, install alphaquant with the 'alphamap' extra."
+        "Dependency 'alphamap' not installed. If you want to use its functionality, install it with `pip install \"alphaquant[alphamap]\"` ."
     )
     HAS_ALPHAMAP = False
 
@@ -31,13 +31,6 @@ def __init__(self, condition1, condition2, results_directory, samplemap_file,
             order_along_protein_sequence = True, organism = 'Human',colorlist = aq_plot_colors.AlphaQuantColorMap().colorlist, tree_level = 'seq',
             protein_identifier = 'gene_symbol', label_rotation = 90, add_stripplot = False,
             narrowing_factor_for_fcplot = 1/14, rescale_factor_x = 1.0, rescale_factor_y = 2):
-
-        if not HAS_ALPHAMAP:
-            raise ImportError(
-                "alphamap is required for AlphaMapVisualizer. "
-                "Install it with: pip install \"alphaquant[alphamap]\""
-            )
-
         """
         Initializes an object for visualizing peptide fold changes and AlphaMap sequence alignment. 
         This class allows for the visualization of different proteins by using the visualize_protein method 
@@ -61,7 +54,12 @@ def __init__(self, condition1, condition2, results_directory, samplemap_file,
             identifier (str): Identifier for proteins. Can be 'gene_symbol' or 'uniprot_id'.
 
         """
-        
+        if not HAS_ALPHAMAP:
+            raise ImportError(
+                "alphamap is required for AlphaMapVisualizer. "
+                "Install it with: pip install \"alphaquant[alphamap]\""
+            )
+
         self._fc_visualizer = aq_plot_fc.FoldChangeVisualizer(condition1, condition2, results_directory, samplemap_file,
             order_along_protein_sequence = order_along_protein_sequence, organism = organism, colorlist = colorlist, 
             tree_level = tree_level, protein_identifier = protein_identifier, label_rotation = label_rotation, 

From acc9573f4fdd6681c0c311136f175b74ba8213ca Mon Sep 17 00:00:00 2001
From: mschwoerer <82171591+mschwoer@users.noreply.github.com>
Date: Wed, 28 Jan 2026 19:41:34 +0100
Subject: [PATCH 3/3] merge alphamap extra with gui

---
 .github/workflows/e2e_tests_quick.yml                  |  2 +-
 .../workflows/e2e_tests_quick_multiple_platforms.yml   |  4 ++--
 .github/workflows/install_and_unit_tests.yml           |  2 +-
 .../install_and_unit_tests_multiple_platforms.yml      |  4 ++--
 .github/workflows/run_example_nbs.yml                  |  2 +-
 README.md                                              | 10 ----------
 pyproject.toml                                         |  2 --
 requirements/requirements_alphamap.txt                 |  1 -
 requirements/requirements_alphamap_loose.txt           |  1 -
 requirements/requirements_gui.txt                      |  1 +
 requirements/requirements_gui_loose.txt                |  1 +
 11 files changed, 9 insertions(+), 21 deletions(-)
 delete mode 100644 requirements/requirements_alphamap.txt
 delete mode 100644 requirements/requirements_alphamap_loose.txt

diff --git a/.github/workflows/e2e_tests_quick.yml b/.github/workflows/e2e_tests_quick.yml
index 4e498919..b91ba434 100644
--- a/.github/workflows/e2e_tests_quick.yml
+++ b/.github/workflows/e2e_tests_quick.yml
@@ -28,5 +28,5 @@ jobs:
     with:
       python-version: ${{ matrix.python-version }}
       os: ${{ matrix.os }}
-      install-script: ./pip_install.sh tests,gui,dask,alphamap
+      install-script: ./pip_install.sh tests,gui,dask
       test-script: ./run_e2e_tests_quick.sh
diff --git a/.github/workflows/e2e_tests_quick_multiple_platforms.yml b/.github/workflows/e2e_tests_quick_multiple_platforms.yml
index 78292b67..429512dc 100644
--- a/.github/workflows/e2e_tests_quick_multiple_platforms.yml
+++ b/.github/workflows/e2e_tests_quick_multiple_platforms.yml
@@ -29,7 +29,7 @@ jobs:
     with:
       python-version: ${{ matrix.python-version }}
       os: ${{ matrix.os }}
-      install-script: ./pip_install.sh stable,tests,gui,dask-stable,alphamap-stable
+      install-script: ./pip_install.sh stable,tests,gui-stable,dask-stable
       test-script: ./run_e2e_tests_quick.sh
 
   run-unit-tests-loose:
@@ -43,5 +43,5 @@ jobs:
     with:
       python-version: ${{ matrix.python-version }}
       os: ${{ matrix.os }}
-      install-script: ./pip_install.sh tests,gui,dask,alphamap
+      install-script: ./pip_install.sh tests,gui,dask
       test-script: ./run_e2e_tests_quick.sh
diff --git a/.github/workflows/install_and_unit_tests.yml b/.github/workflows/install_and_unit_tests.yml
index 0a48ad36..e2911ffa 100644
--- a/.github/workflows/install_and_unit_tests.yml
+++ b/.github/workflows/install_and_unit_tests.yml
@@ -30,5 +30,5 @@ jobs:
     with:
       python-version: ${{ matrix.python-version }}
       os: ${{ matrix.os }}
-      install-script: ./pip_install.sh tests,gui,dask,alphamap
+      install-script: ./pip_install.sh tests,gui,dask
       test-script: ./run_unit_tests.sh
diff --git a/.github/workflows/install_and_unit_tests_multiple_platforms.yml b/.github/workflows/install_and_unit_tests_multiple_platforms.yml
index 3a34b963..c5867f55 100644
--- a/.github/workflows/install_and_unit_tests_multiple_platforms.yml
+++ b/.github/workflows/install_and_unit_tests_multiple_platforms.yml
@@ -26,7 +26,7 @@ jobs:
     with:
       python-version: ${{ matrix.python-version }}
       os: ${{ matrix.os }}
-      install-script: ./pip_install.sh stable,tests,gui,dask-stable,alphamap-stable
+      install-script: ./pip_install.sh stable,tests,gui-stable,dask-stable
       test-script: ./run_unit_tests.sh
 
   run-unit-tests-loose:
@@ -40,5 +40,5 @@ jobs:
     with:
       python-version: ${{ matrix.python-version }}
       os: ${{ matrix.os }}
-      install-script: ./pip_install.sh tests,gui,dask,alphamap
+      install-script: ./pip_install.sh tests,gui,dask
       test-script: ./run_unit_tests.sh
diff --git a/.github/workflows/run_example_nbs.yml b/.github/workflows/run_example_nbs.yml
index e71f3a9e..7262b4bb 100644
--- a/.github/workflows/run_example_nbs.yml
+++ b/.github/workflows/run_example_nbs.yml
@@ -28,5 +28,5 @@ jobs:
     with:
       python-version: ${{ matrix.python-version }}
       os: ${{ matrix.os }}
-      install-script: ./pip_install.sh tests,gui,dask,alphamap
+      install-script: ./pip_install.sh tests,gui,dask
       test-script: ./run_example_notebooks.sh
diff --git a/README.md b/README.md
index fa594ea6..8199ce68 100644
--- a/README.md
+++ b/README.md
@@ -114,16 +114,6 @@ or the version with a pinned dependency (recommended)
 pip install "alphaquant[dask-stable]"
 ```
 
-For AlphaMap visualization features (sequence alignment plots), install the optional alphamap extra:
-
-```bash
-pip install "alphaquant[alphamap]"
-```
-or the version with a pinned dependency (recommended)
-```bash
-pip install "alphaquant[alphamap-stable]"
-```
-
 ### Developer installation
 
 AlphaQuant can also be installed in editable (i.e. developer) mode with a few `bash` commands. This allows to fully customize the software and even modify the source code to your specific needs. When an editable Python package is installed, its source code is stored in a transparent location of your choice. While optional, it is advised to first (create and) navigate to e.g. a general software folder:
diff --git a/pyproject.toml b/pyproject.toml
index 67bb521c..5b1126f4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -55,8 +55,6 @@ optional-dependencies = { stable = { file = ["requirements/requirements.txt",
 ] }, development = { file = ["requirements/requirements_development.txt", "requirements/requirements_tests.txt",
 ] }, dask = { file = [ "requirements/requirements_dask_loose.txt",
 ] }, dask-stable = { file = [ "requirements/requirements_dask.txt",
-] }, alphamap = { file = [ "requirements/requirements_alphamap_loose.txt",
-] }, alphamap-stable = { file = [ "requirements/requirements_alphamap.txt",
 ] }}
 
 version = {attr = "alphaquant.__version__"}
diff --git a/requirements/requirements_alphamap.txt b/requirements/requirements_alphamap.txt
deleted file mode 100644
index 1b80b934..00000000
--- a/requirements/requirements_alphamap.txt
+++ /dev/null
@@ -1 +0,0 @@
-alphamap==0.2.0
diff --git a/requirements/requirements_alphamap_loose.txt b/requirements/requirements_alphamap_loose.txt
deleted file mode 100644
index 1c317e43..00000000
--- a/requirements/requirements_alphamap_loose.txt
+++ /dev/null
@@ -1 +0,0 @@
-alphamap
diff --git a/requirements/requirements_gui.txt b/requirements/requirements_gui.txt
index fba5805e..e84757a0 100644
--- a/requirements/requirements_gui.txt
+++ b/requirements/requirements_gui.txt
@@ -1,3 +1,4 @@
 plotly==5.24.1
 bokeh==3.6.2
 panel==1.6.0
+alphamap==0.2.0
diff --git a/requirements/requirements_gui_loose.txt b/requirements/requirements_gui_loose.txt
index 3022de00..d992a0d7 100644
--- a/requirements/requirements_gui_loose.txt
+++ b/requirements/requirements_gui_loose.txt
@@ -1,3 +1,4 @@
 plotly
 bokeh
 panel
+alphamap