XspecT 0.4.1__tar.gz → 0.5.0__tar.gz

xspect-0.5.0/.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: mkdocs
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  mkdocs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache 
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install '.[docs]'
+      - run: mkdocs gh-deploy --force

{xspect-0.4.1 → xspect-0.5.0}/.github/workflows/pypi.yml

@@ -12,6 +12,17 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "23"
+      - name: Build XspecT web dist
+        run: |
+          cd src/xspect/xspect-web
+          npm install
+          npx vite build
+          cd ../../..
+
       - uses: actions/setup-python@v5
         with:
           python-version: "3.x"

{xspect-0.4.1 → xspect-0.5.0}/.github/workflows/test.yml

@@ -2,9 +2,20 @@ name: test
 on: [push]
 jobs:
   pytest:
+    name: Run pytest
     runs-on: ubuntu-latest
     steps:
         - uses: actions/checkout@v4
+        - name: Set up Node.js
+          uses: actions/setup-node@v4
+          with:
+            node-version: "23"
+        - name: Build dist
+          run: |
+            cd src/xspect/xspect-web
+            npm install
+            npx vite build
+            cd ../../..
         - name: Set up Python
           uses: actions/setup-python@v4
           with:
@@ -18,7 +29,7 @@ jobs:
             xspect models download
         - name: Test with pytest
           run: |
-            pytest --cov
+            pytest --cov --retries 2 --retry-delay 5
         - name: Upload coverage reports to Codecov
           uses: codecov/codecov-action@v4
           env:

{xspect-0.4.1 → xspect-0.5.0}/.gitignore

@@ -14,7 +14,6 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
 lib64/
 parts/
 sdist/

{xspect-0.4.1 → xspect-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: XspecT
-Version: 0.4.1
+Version: 0.5.0
 Summary: Tool to monitor and characterize pathogens using Bloom filters.
 License: MIT License
         
@@ -46,14 +46,12 @@ Requires-Dist: fastapi
 Requires-Dist: uvicorn
 Requires-Dist: python-multipart
 Provides-Extra: docs
-Requires-Dist: sphinx; extra == "docs"
-Requires-Dist: furo; extra == "docs"
-Requires-Dist: myst-parser; extra == "docs"
-Requires-Dist: sphinx-copybutton; extra == "docs"
-Requires-Dist: sphinx-autobuild; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocs-include-markdown-plugin; extra == "docs"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-retry; extra == "test"
 Requires-Dist: httpx; extra == "test"
 Dynamic: license-file
 
@@ -79,7 +77,7 @@ To install XspecT, please download the lastest 64 bit Python version and install
 ```
 pip install xspect
 ```
-Please note that Windows and Alpine Linux is currently not supported.
+Please note that Windows and Alpine Linux are currently not supported.
 
 ## Usage
 ### Get the models
@@ -107,5 +105,5 @@ For further instructions on how to use the command line interface, please refer
 ```
 xspect --help
 ```
-[documentation]: https://bionf.github.io/XspecT2/cli.html
+[documentation]: https://bionf.github.io/XspecT2/cli/index.html
 <!-- end quickstart -->

{xspect-0.4.1 → xspect-0.5.0}/README.md

@@ -20,7 +20,7 @@ To install XspecT, please download the lastest 64 bit Python version and install
 ```
 pip install xspect
 ```
-Please note that Windows and Alpine Linux is currently not supported.
+Please note that Windows and Alpine Linux are currently not supported.
 
 ## Usage
 ### Get the models
@@ -48,5 +48,5 @@ For further instructions on how to use the command line interface, please refer
 ```
 xspect --help
 ```
-[documentation]: https://bionf.github.io/XspecT2/cli.html
+[documentation]: https://bionf.github.io/XspecT2/cli/index.html
 <!-- end quickstart -->

xspect-0.5.0/docs/cli.md

@@ -0,0 +1,146 @@
+# How to use the CLI
+
+XspecT comes with a built-in command line interface (CLI), which enables quick classifications without the need to use the web interface. The command line interface can also be used to download and train models.
+
+After installing XspecT, a list of available commands can be viewed by running:
+
+```bash
+xspect --help
+```
+
+In general, XspecT commands will prompt you for parameters if they are not provided. However, you can also provide them directly in the command line, for example when using scripts or tools such as Slurm. Simply run the command with the `--help` option to see all available parameters.
+
+## Model Management
+
+At its core, XspecT uses models to classify and filter samples. These models are based on kmer indices trained on publicly availabel genomes as well as, possibly, a support vector machine (SVM) classifier.
+
+To manage models, the `xspect models` command can be used. This command allows you to download, train, and view available models.
+
+### Viewing Available Models
+
+To view a list of available models, run:
+
+```bash
+xspect models list
+```
+This will show a list of all available models, separated by their type (species, genus, MLST).
+
+### Downloading Models
+
+To download a basic set of pre-trained models (Acinetobacter and Salonella), run:
+
+```bash
+xspect models download
+```
+
+### Model Training
+
+Models can be trained based on data from NCBI, which is automatically downloaded and processed by XspecT.
+
+To train a model with NCBI data, run the following command:
+
+```bash
+xspect models train ncbi
+```
+
+If you would like to train models with manually curated data from a directory, you can use:
+
+```bash
+xspect models train directory
+```
+
+Your directory should have the following structure:
+```
+your-directory/
+├── cobs
+│   ├── species1
+│   │   ├── genome1.fna
+│   │   ├── genome2.fna
+│   │   └── ...
+│   ├── species2
+│   │   ├── genome1.fna
+│   │   ├── genome2.fna
+│   │   └── ...
+│   └── ...
+├── svm
+│   ├── species1
+│   │   ├── genome1.fna
+│   │   ├── genome2.fna
+│   │   └── ...
+│   ├── species2
+│   │   ├── genome1.fna
+│   │   ├── genome2.fna
+│   │   └── ...
+│   └── ...
+```
+
+To train models for MLST classifications, run:
+
+```bash
+xspect models train mlst
+```
+
+## Classification
+
+To classify samples, the command `xspect classify` can be used. This command will classify the sample based on the models available in your XspecT installation.
+
+### Genus Classification
+
+To classify a sample based on its genus, run the following command:
+
+```bash
+xspect classify genus
+```
+
+XspecT will prompt you for the genus and path to your sample directory.
+
+### Species Classification
+
+To classify a sample based on its species, run the following command:
+
+```bash
+xspect classify species
+```
+
+XspecT will prompt you for the genus and path to your sample directory.
+
+### Sparse Sampling
+XspecT uses a kmer-based approach to classify samples. This means that the entire sample is analyzed, which can be time-consuming for large samples. To speed up the analysis, you can use the `--sparse-sampling-step` option to only consider every nth kmer:
+
+**Example**:
+```bash
+xspect classify species --sparse-sampling-step 10 Acinetobacter path
+```
+
+This will only consider every 10th kmer in the sample.
+
+### MLST Classification
+
+Samples can also be classified based on Multi-locus sequence type schemas. To MLST-classify a sample, run:
+
+```bash
+xspect classify-mlst -p path
+```
+
+## Filtering
+XspecT can also be used to filter samples based on their classification results. This is useful when analyzing metagenome samples, for example when looking at genomic bycatch.
+
+To filter samples, the command `xspect filter` can be used. This command will filter the samples based on the specified criteria.
+
+### Filtering by Genus
+
+To filter samples by genus, run the following command:
+
+```bash
+xspect filter genus
+```
+XspecT will prompt you for the genus and path to your sample directory, as well as for a threshold to use for filtering.
+
+### Filtering by Species
+To filter samples by species, run the following command:
+
+```bash
+xspect filter species
+```
+
+You will be prompted for the genus and path to your sample directory, as well for the species to filter by and for a threshold to use for filtering. Next to normal threshold-based filtering, you can also enter a threshold of `-1` to only include contigs if the selected species is the maximum scoring species.

xspect-0.5.0/docs/contributing.md

@@ -0,0 +1,3 @@
+# Contributing to XspecT
+
+Coming soon...

xspect-0.5.0/docs/index.md

@@ -0,0 +1,7 @@
+# Home
+{%
+    include-markdown "../README.md"
+    start="<!-- start intro -->"
+    end="<!-- end intro -->"
+%}
+[Get started](quickstart.md){ .md-button .md-button--primary}

xspect-0.5.0/docs/quickstart.md

@@ -0,0 +1,6 @@
+# Quickstart
+{%
+    include-markdown "../README.md"
+    start="<!-- start quickstart -->"
+    end="<!-- end quickstart -->"
+%}

xspect-0.5.0/docs/understanding.md

@@ -0,0 +1,3 @@
+# Understanding XspecT
+
+Coming soon...

xspect-0.5.0/docs/web.md

@@ -0,0 +1,17 @@
+# How to use the Web app
+
+To run XspecT in a web browser, you can use the following command:
+
+```bash
+xspect web
+```
+This will start a web server running on port 8000. You can access the web app by navigating to [http://localhost:8000](http://localhost:8000) in your web browser.
+
+## Web App Features
+
+Within the web app, you can perform the following tasks:
+
+- Upload samples for classification
+- Submit samples for classification and view results
+- Submit samples for filtering and view results
+- Manage models

xspect-0.5.0/mkdocs.yml

@@ -0,0 +1,19 @@
+site_name: XspecT Documentation
+theme:
+  name: material
+  features:
+    - navigation.tabs
+    - content.code.copy
+plugins:
+  - include-markdown
+  - search
+repo_url: https://github.com/BIONF/XspecT2
+markdown_extensions:
+  - attr_list
+nav:
+  - Home: index.md
+  - Quickstart: quickstart.md
+  - CLI: cli.md
+  - "Web App": web.md
+  - "Understanding XspecT": understanding.md
+  - Contributing: contributing.md

{xspect-0.4.1 → xspect-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "XspecT"
-version = "0.4.1"
+version = "0.5.0"
 description = "Tool to monitor and characterize pathogens using Bloom filters."
 readme = {file = "README.md", content-type = "text/markdown"}
 license = {file = "LICENSE"}
@@ -44,11 +44,14 @@ where = ["src"]
 include = ["xspect"]
 namespaces = false
 
+[tool.setuptools.package-data]
+xspect = ["xspect-web/dist/**/*"]
+
 [tool.pytest.ini_options]
 pythonpath = [
   "src"
 ]
 
 [project.optional-dependencies]
-docs = ["sphinx", "furo", "myst-parser", "sphinx-copybutton", "sphinx-autobuild"]
-test = ["pytest", "pytest-cov", "httpx"]
+docs = ["mkdocs-material", "mkdocs-include-markdown-plugin"]
+test = ["pytest", "pytest-cov", "pytest-retry", "httpx"]

{xspect-0.4.1 → xspect-0.5.0}/src/XspecT.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: XspecT
-Version: 0.4.1
+Version: 0.5.0
 Summary: Tool to monitor and characterize pathogens using Bloom filters.
 License: MIT License
         
@@ -46,14 +46,12 @@ Requires-Dist: fastapi
 Requires-Dist: uvicorn
 Requires-Dist: python-multipart
 Provides-Extra: docs
-Requires-Dist: sphinx; extra == "docs"
-Requires-Dist: furo; extra == "docs"
-Requires-Dist: myst-parser; extra == "docs"
-Requires-Dist: sphinx-copybutton; extra == "docs"
-Requires-Dist: sphinx-autobuild; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocs-include-markdown-plugin; extra == "docs"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-retry; extra == "test"
 Requires-Dist: httpx; extra == "test"
 Dynamic: license-file
 
@@ -79,7 +77,7 @@ To install XspecT, please download the lastest 64 bit Python version and install
 ```
 pip install xspect
 ```
-Please note that Windows and Alpine Linux is currently not supported.
+Please note that Windows and Alpine Linux are currently not supported.
 
 ## Usage
 ### Get the models
@@ -107,5 +105,5 @@ For further instructions on how to use the command line interface, please refer
 ```
 xspect --help
 ```
-[documentation]: https://bionf.github.io/XspecT2/cli.html
+[documentation]: https://bionf.github.io/XspecT2/cli/index.html
 <!-- end quickstart -->

xspect-0.5.0/src/XspecT.egg-info/SOURCES.txt

@@ -0,0 +1,115 @@
+.gitignore
+LICENSE
+README.md
+mkdocs.yml
+pyproject.toml
+.github/workflows/black.yml
+.github/workflows/docs.yml
+.github/workflows/pylint.yml
+.github/workflows/pypi.yml
+.github/workflows/test.yml
+docs/cli.md
+docs/contributing.md
+docs/index.md
+docs/quickstart.md
+docs/understanding.md
+docs/web.md
+src/XspecT.egg-info/PKG-INFO
+src/XspecT.egg-info/SOURCES.txt
+src/XspecT.egg-info/dependency_links.txt
+src/XspecT.egg-info/entry_points.txt
+src/XspecT.egg-info/requires.txt
+src/XspecT.egg-info/top_level.txt
+src/xspect/__init__.py
+src/xspect/classify.py
+src/xspect/definitions.py
+src/xspect/download_models.py
+src/xspect/file_io.py
+src/xspect/filter_sequences.py
+src/xspect/main.py
+src/xspect/model_management.py
+src/xspect/ncbi.py
+src/xspect/train.py
+src/xspect/web.py
+src/xspect/mlst_feature/__init__.py
+src/xspect/mlst_feature/mlst_helper.py
+src/xspect/mlst_feature/pub_mlst_handler.py
+src/xspect/models/__init__.py
+src/xspect/models/probabilistic_filter_mlst_model.py
+src/xspect/models/probabilistic_filter_model.py
+src/xspect/models/probabilistic_filter_svm_model.py
+src/xspect/models/probabilistic_single_filter_model.py
+src/xspect/models/result.py
+src/xspect/xspect-web/.gitignore
+src/xspect/xspect-web/README.md
+src/xspect/xspect-web/components.json
+src/xspect/xspect-web/eslint.config.js
+src/xspect/xspect-web/index.html
+src/xspect/xspect-web/package-lock.json
+src/xspect/xspect-web/package.json
+src/xspect/xspect-web/pnpm-lock.yaml
+src/xspect/xspect-web/tsconfig.app.json
+src/xspect/xspect-web/tsconfig.json
+src/xspect/xspect-web/tsconfig.node.json
+src/xspect/xspect-web/vite.config.ts
+src/xspect/xspect-web/dist/index.html
+src/xspect/xspect-web/dist/vite.svg
+src/xspect/xspect-web/dist/assets/index-CMG4V7fZ.js
+src/xspect/xspect-web/dist/assets/index-jIKg1HIy.css
+src/xspect/xspect-web/public/vite.svg
+src/xspect/xspect-web/src/App.tsx
+src/xspect/xspect-web/src/api.tsx
+src/xspect/xspect-web/src/index.css
+src/xspect/xspect-web/src/main.tsx
+src/xspect/xspect-web/src/types.tsx
+src/xspect/xspect-web/src/utils.tsx
+src/xspect/xspect-web/src/vite-env.d.ts
+src/xspect/xspect-web/src/assets/react.svg
+src/xspect/xspect-web/src/components/classification-form.tsx
+src/xspect/xspect-web/src/components/classify.tsx
+src/xspect/xspect-web/src/components/data-table.tsx
+src/xspect/xspect-web/src/components/dropdown-checkboxes.tsx
+src/xspect/xspect-web/src/components/dropdown-slider.tsx
+src/xspect/xspect-web/src/components/filter-form.tsx
+src/xspect/xspect-web/src/components/filter.tsx
+src/xspect/xspect-web/src/components/header.tsx
+src/xspect/xspect-web/src/components/landing.tsx
+src/xspect/xspect-web/src/components/models-details.tsx
+src/xspect/xspect-web/src/components/models.tsx
+src/xspect/xspect-web/src/components/result-chart.tsx
+src/xspect/xspect-web/src/components/result.tsx
+src/xspect/xspect-web/src/components/spinner.tsx
+src/xspect/xspect-web/src/components/ui/accordion.tsx
+src/xspect/xspect-web/src/components/ui/button.tsx
+src/xspect/xspect-web/src/components/ui/card.tsx
+src/xspect/xspect-web/src/components/ui/chart.tsx
+src/xspect/xspect-web/src/components/ui/command.tsx
+src/xspect/xspect-web/src/components/ui/dialog.tsx
+src/xspect/xspect-web/src/components/ui/dropdown-menu.tsx
+src/xspect/xspect-web/src/components/ui/file-upload.tsx
+src/xspect/xspect-web/src/components/ui/form.tsx
+src/xspect/xspect-web/src/components/ui/input.tsx
+src/xspect/xspect-web/src/components/ui/label.tsx
+src/xspect/xspect-web/src/components/ui/navigation-menu.tsx
+src/xspect/xspect-web/src/components/ui/popover.tsx
+src/xspect/xspect-web/src/components/ui/select.tsx
+src/xspect/xspect-web/src/components/ui/separator.tsx
+src/xspect/xspect-web/src/components/ui/slider.tsx
+src/xspect/xspect-web/src/components/ui/switch.tsx
+src/xspect/xspect-web/src/components/ui/table.tsx
+src/xspect/xspect-web/src/components/ui/tabs.tsx
+src/xspect/xspect-web/src/lib/utils.ts
+tests/__init__.py
+tests/conftest.py
+tests/test_cli.py
+tests/test_file_io.py
+tests/test_model_management.py
+tests/test_model_result.py
+tests/test_ncbi.py
+tests/test_probabilisitc_filter_mlst_model.py
+tests/test_probabilistic_filter_model.py
+tests/test_probabilistic_filter_svm_model.py
+tests/test_probabilistic_single_filter_model.py
+tests/test_pub_mlst_handler.py
+tests/test_train.py
+tests/test_web.py

{xspect-0.4.1 → xspect-0.5.0}/src/XspecT.egg-info/requires.txt

@@ -13,13 +13,11 @@ uvicorn
 python-multipart
 
 [docs]
-sphinx
-furo
-myst-parser
-sphinx-copybutton
-sphinx-autobuild
+mkdocs-material
+mkdocs-include-markdown-plugin
 
 [test]
 pytest
 pytest-cov
+pytest-retry
 httpx

xspect-0.5.0/src/xspect/classify.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+from xspect.mlst_feature.mlst_helper import pick_scheme_from_models_dir
+import xspect.model_management as mm
+from xspect.models.probabilistic_filter_mlst_model import (
+    ProbabilisticFilterMlstSchemeModel,
+)
+
+
+def classify_genus(
+    model_genus: str, input_path: Path, output_path: Path, step: int = 1
+):
+    """Classify the input file using the genus model."""
+    model = mm.get_genus_model(model_genus)
+    result = model.predict(input_path, step=step)
+    result.input_source = input_path.name
+    result.save(output_path)
+
+
+def classify_species(model_genus, input_path, output_path, step=1):
+    """Classify the input file using the species model."""
+    model = mm.get_species_model(model_genus)
+    result = model.predict(input_path, step=step)
+    result.input_source = input_path.name
+    result.save(output_path)
+
+
+def classify_mlst(input_path, output_path):
+    """Classify the input file using the MLST model."""
+    scheme_path = pick_scheme_from_models_dir()
+    model = ProbabilisticFilterMlstSchemeModel.load(scheme_path)
+    result = model.predict(scheme_path, input_path)
+    result.save(output_path)

{xspect-0.4.1 → xspect-0.5.0}/src/xspect/file_io.py

@@ -20,17 +20,11 @@ def delete_zip_files(dir_path):
 
 
 def extract_zip(zip_path: Path, unzipped_path: Path):
-    """Extracts all files from a directory with zip files."""
-    # Make new directory.
+    """Extracts all files from a zip file."""
     unzipped_path.mkdir(parents=True, exist_ok=True)
 
-    file_names = os.listdir(zip_path)
-    for file in file_names:
-        file_path = zip_path / file
-        if zipfile.is_zipfile(file_path):
-            with zipfile.ZipFile(file_path) as item:
-                directory = unzipped_path / file.replace(".zip", "")
-                item.extractall(directory)
+    with zipfile.ZipFile(zip_path) as item:
+        item.extractall(unzipped_path)
 
 
 def concatenate_meta(path: Path, genus: str):

xspect-0.5.0/src/xspect/filter_sequences.py

@@ -0,0 +1,56 @@
+from pathlib import Path
+from xspect.model_management import get_genus_model, get_species_model
+from xspect.file_io import filter_sequences
+
+
+def filter_species(
+    model_genus: str,
+    model_species: str,
+    input_path: Path,
+    output_path: Path,
+    threshold: float,
+):
+    """Filter sequences by species.
+    This function filters sequences from the input file based on the species model.
+    It uses the genus model to identify the genus of the sequences and then applies
+    the species model to filter the sequences.
+
+    Args:
+        model_genus (str): The genus model slug.
+        model_species (str): The species model slug.
+        input_path (Path): The path to the input file containing sequences.
+        output_path (Path): The path to the output file where filtered sequences will be saved.
+        threshold (float): The threshold for filtering sequences. Only sequences with a score
+            above this threshold will be included in the output file.
+    """
+    species_model = get_species_model(model_genus)
+    result = species_model.predict(input_path)
+    included_ids = result.get_filtered_subsequence_labels(model_species, threshold)
+    if not included_ids:
+        print("No sequences found for the given species.")
+        return
+    filter_sequences(
+        input_path,
+        output_path,
+        included_ids,
+    )
+
+
+def filter_genus(
+    model_genus: str,
+    input_path: Path,
+    output_path: Path,
+    threshold: float,
+):
+    genus_model = get_genus_model(model_genus)
+    result = genus_model.predict(Path(input_path))
+    included_ids = result.get_filtered_subsequence_labels(model_genus, threshold)
+    if not included_ids:
+        print("No sequences found for the given genus.")
+        return
+
+    filter_sequences(
+        input_path,
+        output_path,
+        included_ids,
+    )