Merge pull request #34 from aertslab/update_docs

Update docs, add checks for formatting/docs building, and refactor modisco and utils modules

.github/workflows/docs.yaml

@@ -0,0 +1,51 @@
+name: Check Sphinx Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  docs:
+    name: Build Sphinx Documentation
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -eo pipefail {0} # Fail on error and enable pipefail
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+          cache: "pip"
+          cache-dependency-path: "**/pyproject.toml"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip wheel
+          pip install ".[doc]"
+
+      - name: Build Documentation and Check for Issues
+        working-directory: docs
+        run: |
+          make clean
+          # Build the docs and capture output, treat warnings as errors (-W)
+          sphinx-build -b html -W . _build/html 2>&1 | tee sphinx-output.log
+
+      - name: Upload Documentation Artifacts (HTML Pages)
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: sphinx-docs
+          path: docs/_build/html
+
+      - name: Upload Log if Build Failed
+        if: failure()
+        uses: actions/upload-artifact@v3
+        with:
+          name: sphinx-output-log
+          path: docs/sphinx-output.log

.github/workflows/ruff.yaml

@@ -0,0 +1,16 @@
+name: Ruff
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 5 1,15 * *"
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: chartboost/ruff-action@v1

README.md

@@ -46,7 +46,7 @@ pip install torch
 pip install crested
 ```
 
-3. If you plan on doing motif analysis using the tf-modisco (lite) and tangermeme functionality inside CREsted, you will need to run the following additional install:
+3. If you plan on doing motif analysis using the tf-modisco (lite) and tangermeme's tomtom functionality inside CREsted, you will need to run the following additional install:
 
 ```bash
 pip install crested[tfmodisco]

docs/api/index.md

@@ -12,5 +12,5 @@ io
 preprocessing
 tools/index.md
 plotting/index.md
-logging
+utils
 ```

docs/api/plotting/hist.md

@@ -11,4 +11,5 @@ Plots for inspecting distributions of ground truth and predictions?
     :toctree: _autosummary
 
     distribution
+    locus_scoring
 ```

docs/api/plotting/patterns.md

@@ -12,4 +12,10 @@ Plot contribution scores and analyze them using tfmodisco.
 
     contribution_scores
     modisco_results
+    selected_instances
+    class_instances
+    clustermap
+    clustermap_tf_motif
+    tf_expression_per_cell_type
+    similarity_heatmap
 ```

docs/api/tools/index.md

@@ -10,11 +10,9 @@
 
     Crested
     TaskConfig
-    tfmodisco
     default_configs
 ```
 
-
 ```{toctree}
 :maxdepth: 2
 :hidden:
@@ -23,6 +21,7 @@ data
 zoo
 losses
 metrics
+modisco
 ```
 
 ## Data
@@ -59,4 +58,24 @@ metrics
     metrics.PearsonCorrelation
     metrics.PearsonCorrelationLog
     metrics.ZeroPenaltyMetric
-```
+```
+
+## Modisco
+
+```{eval-rst}
+.. autosummary::
+    modisco.tfmodisco
+    modisco.match_h5_files_to_classes
+    modisco.process_patterns
+    modisco.create_pattern_matrix
+    modisco.generate_nucleotide_sequences
+    modisco.pattern_similarity
+    modisco.find_pattern
+    modisco.find_pattern_matches
+    modisco.calculate_similarity_matrix
+    modisco.calculate_mean_expression_per_cell_type
+    modisco.generate_html_paths
+    modisco.read_motif_to_tf_file
+    modisco.create_pattern_tf_dict
+    modisco.create_tf_ct_matrix
+```

docs/api/tools/modisco.md

@@ -0,0 +1,27 @@
+# Modisco `tl.modisco`
+
+Tfmodisco (utility) functions. Requires the `modisco-lite` package to be installed.
+
+```{eval-rst}
+.. currentmodule:: crested.tl.modisco
+```
+
+```{eval-rst}
+.. autosummary::
+    :toctree: _autosummary
+
+    tfmodisco
+    match_h5_files_to_classes
+    process_patterns
+    create_pattern_matrix
+    generate_nucleotide_sequences
+    pattern_similarity
+    find_pattern
+    find_pattern_matches
+    calculate_similarity_matrix
+    calculate_mean_expression_per_cell_type
+    generate_html_paths
+    read_motif_to_tf_file
+    create_pattern_tf_dict
+    create_tf_ct_matrix
+```

docs/api/utils.md

@@ -0,0 +1,18 @@
+# Utils
+
+CREsted provides a few utility function to help with sequence encoding, function optimization, ...
+
+```{eval-rst}
+.. currentmodule:: crested.utils
+```
+
+```{eval-rst}
+.. autosummary::
+    :toctree: _autosummary
+
+    EnhancerOptimizer
+    extract_bigwig_values_per_bp
+    hot_encoding_to_sequence
+    one_hot_encode_sequence
+    setup_logging
+```

docs/conf.py

@@ -96,6 +96,8 @@
     "anndata": ("https://anndata.readthedocs.io/en/stable/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
+    "pandas": ("http://pandas.pydata.org/pandas-docs/stable/", None),
+    "seaborn": ("https://seaborn.pydata.org/", None),
 }
 
 # List of patterns, relative to source directory, that match files and
@@ -137,7 +139,9 @@
     ("py:class", "keras.metrics.Metric"),
     ("py:class", "keras.src.losses.loss.Loss"),
     ("py:class", "keras.src.metrics.metric.Metric"),
+    ("py:class", "seaborn.matrix.ClusterGrid"),
 ]
+
 suppress_warnings = [
     "autosummary.import_cycle",
 ]