variantgrid-api 1.1.1__tar.gz → 1.3.0__tar.gz

{variantgrid_api-1.1.1/src/variantgrid_api.egg-info → variantgrid_api-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: variantgrid_api
-Version: 1.1.1
+Version: 1.3.0
 Summary: A Python API client for VariantGrid
 Author-email: Dave Lawrence <davmlaw@gmail.com>
 License: MIT License
@@ -66,6 +66,44 @@ enrichment_kit = EnrichmentKit(name="idt_haem", version=1)
 result = api.create_enrichment_kit(enrichment_kit)
 ```
 
+## Annotate a VCF and download it back
+
+Upload a VCF, wait for VariantGrid to import + annotate any novel variants, then download the
+cohort-level annotated export (all samples, single-sample VCFs included). The whole flow is a one-liner:
+
+```python
+from variantgrid_api.api_client import VariantGridAPI
+
+api = VariantGridAPI(server="https://variantgrid.com", api_token="YOUR_API_TOKEN")
+
+# export_type is "vcf" (gzipped *.vcf.gz) or "csv" (zipped *.csv.zip)
+path = api.annotate_vcf("input.vcf", export_type="vcf", dest_path="/data/results/")
+print(f"Annotated VCF written to {path}")
+```
+
+Or drive each step yourself:
+
+```python
+# For ad-hoc uploads pass path=None so the upload isn't treated as a SeqAuto backend-link hint
+upload = api.upload_file("input.vcf", path=None)
+uploaded_file_id = upload["uploaded_file_id"]           # or upload["sha256_hash"]
+api.wait_for_annotation(uploaded_file_id, timeout=3600, poll_interval=10)  # raises on error/timeout
+path = api.download_annotated(uploaded_file_id, export_type="csv", dest_path="/data/results/")
+```
+
+`poll_upload_status(uploaded_file_id)` returns the raw status dict (including `annotation_complete`,
+`progress_percent`, `error`, `vcf_id`, `samples`, ...) if you want to inspect progress directly. All of
+these accept `sha256=<hash>` instead of `uploaded_file_id` - the server dedups on the content hash, so it is
+stable across machines and useful if you didn't retain the id.
+
+Notes:
+
+- The `annotate_vcf` wrapper already uploads with `path=None`. Only pass a `path` to `upload_file` for SeqAuto
+  uploads that link to a registered `JointCalledVCF` / `SingleSampleVCF` (that is what `path` is for - it is
+  ignored on non-SeqAuto deployments).
+- Downloads require the target deployment to have the cohort export analysis templates configured
+  (`ANALYSIS_TEMPLATES_AUTO_COHORT_EXPORT`) - otherwise a clear error is returned.
+
 ## Testing
 
 ```

variantgrid_api-1.3.0/README.md

@@ -0,0 +1,70 @@
+# variantgrid_api
+
+[![PyPi version](https://img.shields.io/pypi/v/variantgrid_api.svg)](https://pypi.org/project/variantgrid_api/) [![Python versions](https://img.shields.io/pypi/pyversions/variantgrid_api.svg)](https://pypi.org/project/variantgrid_api/)
+
+Python API client for [VariantGrid](https://github.com/SACGF/variantgrid) Open source Variant database and analysis platform
+
+See [changelog](https://github.com/SACGF/variantgrid_api/blob/main/CHANGELOG.md)
+
+## Install
+
+```
+python3 -m pip install variantgrid_api
+```
+
+## Example
+
+```
+from variantgrid_api.api_client import VariantGridAPI
+from variantgrid_api.data_models import EnrichmentKit
+
+api = VariantGridAPI(server="https://variantgrid.com", api_token="YOUR_API_TOKEN")
+enrichment_kit = EnrichmentKit(name="idt_haem", version=1)
+result = api.create_enrichment_kit(enrichment_kit)
+```
+
+## Annotate a VCF and download it back
+
+Upload a VCF, wait for VariantGrid to import + annotate any novel variants, then download the
+cohort-level annotated export (all samples, single-sample VCFs included). The whole flow is a one-liner:
+
+```python
+from variantgrid_api.api_client import VariantGridAPI
+
+api = VariantGridAPI(server="https://variantgrid.com", api_token="YOUR_API_TOKEN")
+
+# export_type is "vcf" (gzipped *.vcf.gz) or "csv" (zipped *.csv.zip)
+path = api.annotate_vcf("input.vcf", export_type="vcf", dest_path="/data/results/")
+print(f"Annotated VCF written to {path}")
+```
+
+Or drive each step yourself:
+
+```python
+# For ad-hoc uploads pass path=None so the upload isn't treated as a SeqAuto backend-link hint
+upload = api.upload_file("input.vcf", path=None)
+uploaded_file_id = upload["uploaded_file_id"]           # or upload["sha256_hash"]
+api.wait_for_annotation(uploaded_file_id, timeout=3600, poll_interval=10)  # raises on error/timeout
+path = api.download_annotated(uploaded_file_id, export_type="csv", dest_path="/data/results/")
+```
+
+`poll_upload_status(uploaded_file_id)` returns the raw status dict (including `annotation_complete`,
+`progress_percent`, `error`, `vcf_id`, `samples`, ...) if you want to inspect progress directly. All of
+these accept `sha256=<hash>` instead of `uploaded_file_id` - the server dedups on the content hash, so it is
+stable across machines and useful if you didn't retain the id.
+
+Notes:
+
+- The `annotate_vcf` wrapper already uploads with `path=None`. Only pass a `path` to `upload_file` for SeqAuto
+  uploads that link to a registered `JointCalledVCF` / `SingleSampleVCF` (that is what `path` is for - it is
+  ignored on non-SeqAuto deployments).
+- Downloads require the target deployment to have the cohort export analysis templates configured
+  (`ANALYSIS_TEMPLATES_AUTO_COHORT_EXPORT`) - otherwise a clear error is returned.
+
+## Testing
+
+```
+# Install required testing packages
+python3 -m pip install -e ".[test]"
+python3 -m pytest --cov=variantgrid_api
+```

{variantgrid_api-1.1.1 → variantgrid_api-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "variantgrid_api"
-version = "1.1.1"
+version = "1.3.0"
 description = "A Python API client for VariantGrid"
 authors = [
     { name = "Dave Lawrence", email = "davmlaw@gmail.com" }

variantgrid_api-1.3.0/src/variantgrid_api/api_client.py

@@ -0,0 +1,419 @@
+import datetime
+import json
+import logging
+import re
+import time
+import urllib
+import warnings
+from enum import Enum
+from pathlib import Path
+from typing import List, Optional, Callable, Union
+
+import requests
+
+from variantgrid_api.data_models import EnrichmentKit, SequencingRun, SampleSheet, JointCalledVCF, \
+    SampleSheetLookup, SequencingFile, QCGeneList, QCExecStats, QCGeneCoverage, SequencerModel, Sequencer
+
+
+_UNSET = object()
+
+
+class DateTimeEncoder(json.JSONEncoder):
+    def default(self,o):
+        if isinstance(o,(datetime.date, datetime.datetime)):
+            return o.isoformat()
+        return super().default(o)
+
+
+class EmptyInputPolicy(Enum):
+    IGNORE = "ignore"
+    WARN = "warn"
+    ERROR = "error"
+
+
+class AnnotationError(Exception):
+    """Raised when the server reports an error while importing/annotating an uploaded file."""
+
+    def __init__(self, message, status: Optional[dict] = None):
+        super().__init__(message)
+        self.status = status
+
+
+class VariantGridAPI:
+    def __init__(self, server, api_token,
+                 empty_input_policy=EmptyInputPolicy.ERROR,
+                 logger: Optional[logging.Logger] = None,
+                 log_request=False, log_response=False
+    ):
+        self.server = server
+        self.headers = {"Authorization": f"Token {api_token}"}
+        if logger is None:
+            logger = logging.getLogger(__name__)
+        self.logger = logger
+        self.validation_handler = self._get_validation_handler(empty_input_policy, logger)
+        self.log_request = log_request
+        self.log_response = log_response
+
+    def _get_url(self, url):
+        return urllib.parse.urljoin(self.server, url)
+
+    def _post(self, path, json_data):
+        url = self._get_url(path)
+        json_string = json.dumps(json_data, cls=DateTimeEncoder)
+        if self.log_request:
+            self.logger.info("POST to '%s', JSON: %s", url, json_string)
+        response = requests.post(url,
+                                 headers={**self.headers, "Content-Type": "application/json"},
+                                 data=json_string)
+
+        extra_error_message = f"{url=}, {json_string=}"
+        return self._handle_json_response(response, extra_error_message)
+
+    def _handle_json_response(self, response, extra_error_message: Optional[str] = None):
+        try:
+            json_response = response.json()
+            if self.log_response:
+                self.logger.info("Response from '%s', JSON: %s", response.url, json_response)
+        except Exception as e:
+            json_response = f"Couldn't convert JSON: {e}"
+        if not response.ok:
+            if extra_error_message:
+                self.logger.error(extra_error_message)
+            self.logger.error("Response: %s", json_response)
+            response.raise_for_status()
+        return json_response
+
+    @staticmethod
+    def _get_validation_handler(empty_input_policy: EmptyInputPolicy, logger: logging.Logger) -> Callable:
+        def _ignore(msg):
+            pass
+
+        def _warn(msg):
+            logger.warning(msg)
+
+        def _error(msg):
+            raise ValueError(msg)
+
+        return {
+            EmptyInputPolicy.IGNORE: _ignore,
+            EmptyInputPolicy.WARN: _warn,
+            EmptyInputPolicy.ERROR: _error,
+        }[empty_input_policy]
+
+    def _validate_string(self, info: str, s: Optional[str]) -> None:
+        if s is None:
+            self.validation_handler(f"{info}: is None")
+        elif s == "":
+            self.validation_handler(f"{info}: empty string")
+
+    def _validate_object(self, info: str, obj):
+        if obj is None:
+            self.validation_handler(f"{info}: is None")
+
+    def _validate_list(self, info: str, list_obj: List):
+        if not list_obj:
+            self.validation_handler(f"{info}: empty list")
+
+    def create_experiment(self, experiment: str):
+        self._validate_string("experiment", experiment)
+        json_data = {
+            "name": experiment
+        }
+        return self._post("seqauto/api/v1/experiment/", json_data)
+
+    def create_enrichment_kit(self, enrichment_kit: EnrichmentKit):
+        self._validate_object("enrichment_kit", enrichment_kit)
+        return self._post("seqauto/api/v1/enrichment_kit/",
+                          enrichment_kit.to_dict())
+
+
+    def create_sequencer_model(self, sequencer_model: SequencerModel):
+        self._validate_object("sequencer_model", sequencer_model)
+        return self._post("seqauto/api/v1/sequencer_model/",
+                          sequencer_model.to_dict())
+
+    def create_sequencer(self, sequencer: Sequencer):
+        self._validate_object("sequencer", sequencer)
+        return self._post("seqauto/api/v1/sequencer/",
+                          sequencer.to_dict())
+
+    def create_sequencing_run(self, sequencing_run: SequencingRun):
+        self._validate_object("sequencing_run", sequencing_run)
+        return self._post("seqauto/api/v1/sequencing_run/",
+                          sequencing_run.to_dict())
+
+    def create_sample_sheet(self, sample_sheet: SampleSheet):
+        self._validate_object("sample_sheet", sample_sheet)
+        json_data = sample_sheet.to_dict()
+        # We don't want all sequencing_run just the name
+        sequencing_run = json_data.pop("sequencing_run")
+        json_data["sequencing_run"] = sequencing_run["name"]
+        return self._post("seqauto/api/v1/sample_sheet/",
+                          json_data)
+
+    def create_joint_called_vcf(self, joint_called_vcf: JointCalledVCF):
+        self._validate_object("joint_called_vcf", joint_called_vcf)
+        json_data = joint_called_vcf.to_dict()
+        return self._post("seqauto/api/v1/joint_called_vcf/",
+                          json_data)
+
+    def create_sample_sheet_combined_vcf_file(self, sample_sheet_combined_vcf_file: JointCalledVCF):
+        """Deprecated alias for :meth:`create_joint_called_vcf` - use that instead. """
+        warnings.warn(
+            "create_sample_sheet_combined_vcf_file is deprecated; use create_joint_called_vcf instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.create_joint_called_vcf(sample_sheet_combined_vcf_file)
+
+    def create_sequencing_data(self, sample_sheet_lookup: SampleSheetLookup, sequencing_files: List[SequencingFile]):
+        self._validate_object("sample_sheet_lookup", sample_sheet_lookup)
+        self._validate_list("sequencing_files", sequencing_files)
+        records = []
+        for sf in sequencing_files:
+            data = sf.to_dict()
+            # put into hierarchial JSON DRF expects
+            fastq_r1 = data.pop("fastq_r1")
+            fastq_r2 = data.pop("fastq_r2")
+            data["unaligned_reads"] = {
+                "fastq_r1": {"path": fastq_r1},
+                "fastq_r2": {"path": fastq_r2}
+            }
+            records.append(data)
+
+        json_data = {
+            "sample_sheet": sample_sheet_lookup.to_dict(),
+            "records": records
+        }
+        return self._post("seqauto/api/v1/sequencing_files/bulk_create",
+                          json_data)
+
+    def create_qc_gene_list(self, qc_gene_list: QCGeneList):
+        self._validate_object("qc_gene_list", qc_gene_list)
+        json_data = qc_gene_list.to_dict()
+        return self._post("seqauto/api/v1/qc_gene_list/",
+                          json_data)
+
+
+    def create_multiple_qc_gene_lists(self, qc_gene_lists: List[QCGeneList]):
+        self._validate_list("qc_gene_lists", qc_gene_lists)
+        json_data = {
+            "records": [
+                qcgl.to_dict() for qcgl in qc_gene_lists
+            ]
+        }
+        return self._post("seqauto/api/v1/qc_gene_list/bulk_create",
+                          json_data)
+
+    def create_qc_exec_stats(self, qc_exec_stats: QCExecStats):
+        self._validate_object("qc_exec_stats", qc_exec_stats)
+        json_data = qc_exec_stats.to_dict()
+        return self._post("seqauto/api/v1/qc_exec_summary/",
+                          json_data)
+
+    def create_multiple_qc_exec_stats(self, qc_exec_stats: List[QCExecStats]):
+        self._validate_list("qc_exec_stats", qc_exec_stats)
+        json_data = {
+            "records": [
+                qces.to_dict() for qces in qc_exec_stats
+            ]
+        }
+        return self._post("seqauto/api/v1/qc_exec_summary/bulk_create",
+                          json_data)
+
+    def create_multiple_qc_gene_coverage(self, qc_gene_coverage_list: List[QCGeneCoverage]):
+        self._validate_list("qc_gene_coverage_list", qc_gene_coverage_list)
+        json_data = {
+            "records": [
+                qcgc.to_dict() for qcgc in qc_gene_coverage_list
+            ]
+        }
+        return self._post("seqauto/api/v1/qc_gene_coverage/bulk_create",
+                          json_data)
+
+    def upload_file(self, filename: str, path=_UNSET):
+        """ Upload a file via multipart POST to upload/api/v1/file_upload.
+
+            Returns {"uploaded_file_id": <id>, "sha256_hash": <hash>, ...}; identify the upload by
+            uploaded_file_id and/or sha256_hash (the server dedups on the content hash).
+
+            path: SeqAuto-only server-side hint that links the upload to a registered sequencing VCF
+                  (JointCalledVCF / SingleSampleVCF) by path. Defaults to `filename` for backwards
+                  compatibility. Pass path=None to omit the query param entirely - required for ad-hoc
+                  uploads such as the annotate/download flow, where sending a client-side path makes
+                  SeqAuto deployments try (and fail) to match it to a registered VCF. """
+        url = self._get_url("upload/api/v1/file_upload")
+        if path is _UNSET:
+            path = filename
+        params = {"path": path} if path is not None else {}
+        with open(filename, "rb") as f:
+            response = requests.post(url, headers=self.headers, files={"file": f}, params=params)
+            extra_error_message = f"{filename=}"
+            return self._handle_json_response(response, extra_error_message)
+
+    ###############
+    ## Get methods
+
+    def _get(self, path, params=None):
+        url = self._get_url(path)
+        response = requests.get(url,
+                                params,
+                                headers=self.headers)
+
+        extra_error_message = f"{url=}, {params=}"
+        return self._handle_json_response(response, extra_error_message)
+
+    def sequencing_run_has_vcf(self, sequencing_run: SequencingRun, path: Optional[str] = None):
+        """ Returns whether the SequencingRun has a VCF associated with it. If path is set, VCF must match that path
+            otherwise - any VCF present will retur True """
+        return self.sequencing_run_name_has_vcf(sequencing_run.name, path)
+
+    def sequencing_run_name_has_vcf(self, sequencing_run_name: str, path: Optional[str] = None):
+        """ Returns whether the SequencingRun has a VCF associated with it. If path is set, VCF must match that path
+            otherwise - any VCF present will retur True """
+        data = self._get(f"seqauto/api/v1/sequencing_run/{sequencing_run_name}/")
+        found_vcf = False
+        for vcf in data["vcf_set"]:
+            if path is None or path in vcf["path"]:
+                found_vcf = True
+                break
+        return found_vcf
+
+    ##################################
+    ## Uploaded file annotation flow
+
+    @staticmethod
+    def _upload_key_segment(uploaded_file_id: Optional[int], sha256: Optional[str]) -> str:
+        """ URL segment identifying an uploaded file - by uploaded_file_id (preferred) or its SHA-256 hash. """
+        if uploaded_file_id is not None:
+            return str(uploaded_file_id)
+        if sha256:
+            return f"sha256/{sha256}"
+        raise ValueError("Must provide one of 'uploaded_file_id' or 'sha256'")
+
+    def poll_upload_status(self, uploaded_file_id: Optional[int] = None, sha256: Optional[str] = None) -> dict:
+        """ Single GET of an uploaded file's import/annotation status.
+
+            Keyed by uploaded_file_id (returned from upload_file) or the SHA-256 of the uploaded file.
+            See wait_for_annotation to block until annotation is complete. """
+        segment = self._upload_key_segment(uploaded_file_id, sha256)
+        return self._get(f"upload/api/v1/upload_status/{segment}")
+
+    def wait_for_annotation(self, uploaded_file_id: Optional[int] = None, sha256: Optional[str] = None,
+                            timeout: float = 3600, poll_interval: float = 10, sleep: Callable = time.sleep,
+                            max_transient_errors: int = 5) -> dict:
+        """ Poll poll_upload_status until 'annotation_complete' is true, then return the final status dict.
+
+            Raises AnnotationError if the server reports an 'error', or TimeoutError if 'timeout' seconds elapse.
+            'sleep' is injectable so tests can avoid real delays.
+
+            Transient server hiccups (5xx / connection / timeout - e.g. a brief 500 right after upload while the
+            server is still creating the upload record) are tolerated: up to 'max_transient_errors' *consecutive*
+            failures are retried before giving up. A 4xx response is treated as a real error and raised immediately.
+            The success counter resets whenever a poll succeeds. """
+        deadline = time.monotonic() + timeout
+        transient_errors = 0
+        while True:
+            try:
+                status = self.poll_upload_status(uploaded_file_id=uploaded_file_id, sha256=sha256)
+                transient_errors = 0
+            except (requests.HTTPError, requests.ConnectionError, requests.Timeout) as e:
+                status_code = getattr(getattr(e, "response", None), "status_code", None)
+                if status_code is not None and status_code < 500:
+                    raise  # 4xx is a real client error, not a transient blip
+                transient_errors += 1
+                if transient_errors > max_transient_errors:
+                    raise
+                self.logger.warning("Transient error polling upload status (%s/%s), retrying: %s",
+                                    transient_errors, max_transient_errors, e)
+                if time.monotonic() >= deadline:
+                    raise TimeoutError(f"Annotation did not complete within {timeout}s (last error: {e})")
+                sleep(poll_interval)
+                continue
+            if error := status.get("error"):
+                raise AnnotationError(error, status)
+            if status.get("annotation_complete"):
+                return status
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"Annotation did not complete within {timeout}s (status={status})")
+            sleep(poll_interval)
+
+    @staticmethod
+    def _attachment_filename(response, export_type: str) -> str:
+        content_disposition = response.headers.get("Content-Disposition", "")
+        if m := re.search(r'filename\*?=(?:UTF-8\'\')?"?([^";]+)"?', content_disposition):
+            return urllib.parse.unquote(m.group(1))
+        ext = ".vcf.gz" if export_type == "vcf" else ".csv.zip"
+        return f"download{ext}"
+
+    def download_annotated(self, uploaded_file_id: Optional[int] = None, sha256: Optional[str] = None,
+                           export_type: str = "vcf", dest_path: Optional[Union[str, Path]] = None,
+                           timeout: float = 3600, poll_interval: float = 10,
+                           sleep: Callable = time.sleep) -> Path:
+        """ Download the cohort-level annotated export of an uploaded VCF, saving it to disk.
+
+            export_type is 'vcf' (gzipped *.vcf.gz) or 'csv' (zipped *.csv.zip). The export covers all samples
+            in the uploaded VCF (single-sample VCFs included).
+
+            The endpoint returns 202 while the file is still being generated - this polls until it is ready (200),
+            then streams the attachment to dest_path. If dest_path is None the server's attachment filename is used
+            in the current directory; if it is an existing directory the attachment filename is placed inside it;
+            otherwise it is treated as the full destination path. Returns the Path written.
+
+            Raises TimeoutError if the file isn't ready within 'timeout' seconds. """
+        if export_type not in ("vcf", "csv"):
+            raise ValueError(f"export_type must be 'vcf' or 'csv', got {export_type!r}")
+        segment = self._upload_key_segment(uploaded_file_id, sha256)
+        url = self._get_url(f"upload/api/v1/download/{segment}/{export_type}")
+        deadline = time.monotonic() + timeout
+        while True:
+            response = requests.get(url, headers=self.headers, stream=True)
+            if response.status_code == 202:
+                if self.log_response:
+                    self.logger.info("Download of '%s' still generating: %s", url, self._safe_json(response))
+                if time.monotonic() >= deadline:
+                    raise TimeoutError(f"Download not ready within {timeout}s (url={url})")
+                sleep(poll_interval)
+                continue
+            if not response.ok:
+                # Raises with logging (JSON 'error' message from the server)
+                self._handle_json_response(response, f"download {export_type} for {segment}")
+            dest = self._resolve_download_dest(dest_path, response, export_type)
+            with open(dest, "wb") as f:
+                for chunk in response.iter_content(chunk_size=8192):
+                    if chunk:
+                        f.write(chunk)
+            return dest
+
+    def _resolve_download_dest(self, dest_path: Optional[Union[str, Path]], response, export_type: str) -> Path:
+        filename = self._attachment_filename(response, export_type)
+        if dest_path is None:
+            return Path(filename)
+        dest = Path(dest_path)
+        if dest.is_dir():
+            return dest / filename
+        return dest
+
+    @staticmethod
+    def _safe_json(response):
+        try:
+            return response.json()
+        except Exception:
+            return None
+
+    def annotate_vcf(self, filename: str, export_type: str = "vcf", dest_path: Optional[Union[str, Path]] = None,
+                     timeout: float = 3600, poll_interval: float = 10, sleep: Callable = time.sleep) -> Path:
+        """ Convenience one-liner: upload a VCF, wait for annotation to finish, download the annotated export.
+
+            Chains upload_file -> wait_for_annotation -> download_annotated and returns the Path written. """
+        # path is SeqAuto-only and makes ad-hoc uploads fail the import - omit it for the annotate flow
+        upload = self.upload_file(filename, path=None)
+        uploaded_file_id = upload["uploaded_file_id"]
+        self.wait_for_annotation(uploaded_file_id=uploaded_file_id,
+                                 timeout=timeout, poll_interval=poll_interval, sleep=sleep)
+        return self.download_annotated(uploaded_file_id=uploaded_file_id, export_type=export_type,
+                                       dest_path=dest_path, timeout=timeout, poll_interval=poll_interval, sleep=sleep)
+
+
+
+

{variantgrid_api-1.1.1 → variantgrid_api-1.3.0}/src/variantgrid_api/data_models.py

@@ -1,4 +1,5 @@
 import re
+import warnings
 from datetime import date, datetime
 from dataclasses import dataclass, field
 from typing import Optional, List
@@ -25,6 +26,30 @@ class SequencerModel:
     manufacturer: Manufacturer
     data_naming_convention: str # 'M' or 'H' for (HiSeq only)
 
+    # (prefix, model_name, data_naming_convention)
+    _ILLUMINA_PREFIXES = [
+        ("LH", "NovaSeq X",    "M"),
+        ("NB", "NextSeq",      "M"),
+        ("NS", "NextSeq",      "M"),
+        ("A",  "NovaSeq 6000", "M"),
+        ("H",  "HiSeq",        "H"),
+        ("M",  "MiSeq",        "M"),
+    ]
+
+    @classmethod
+    def from_sequencer_name(cls, sequencer_name: str) -> 'SequencerModel':
+        """Infer SequencerModel from an Illumina sequencer instrument name.
+
+        Illumina instrument names begin with a letter code that identifies the
+        platform (e.g. ``M02027`` → MiSeq, ``A01234`` → NovaSeq 6000).
+        Returns an Unknown model when no prefix matches.
+        """
+        illumina = Manufacturer(name="Illumina")
+        for prefix, model_name, convention in cls._ILLUMINA_PREFIXES:
+            if sequencer_name.startswith(prefix):
+                return cls(model=model_name, manufacturer=illumina, data_naming_convention=convention)
+        return cls(model="Unknown", manufacturer=illumina, data_naming_convention="U")
+
 
 @dataclass_json
 @dataclass
@@ -109,12 +134,25 @@ class VariantCaller:
 
 @dataclass_json
 @dataclass
-class SampleSheetCombinedVCFFile:
+class JointCalledVCF:
+    """A joint-called multi-sample VCF (mirrors the server ``JointCalledVCF`` model). """
     path: str
     sample_sheet_lookup: SampleSheetLookup = field(metadata=config(field_name="sample_sheet"))
     variant_caller: VariantCaller
 
 
+@dataclass_json
+@dataclass
+class SampleSheetCombinedVCFFile(JointCalledVCF):
+    """Deprecated alias for :class:`JointCalledVCF` - use that instead. """
+    def __post_init__(self):
+        warnings.warn(
+            "SampleSheetCombinedVCFFile is deprecated; use JointCalledVCF instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+
 @dataclass_json
 @dataclass
 class BamFile:
@@ -124,11 +162,24 @@ class BamFile:
 
 @dataclass_json
 @dataclass
-class VCFFile:
+class SingleSampleVCF:
+    """A per-sample VCF - one BAM in, one VCF out (mirrors the server ``SingleSampleVCF`` model). """
     path: str
     variant_caller: Optional[VariantCaller] = field(default=None, metadata=config(exclude=lambda x: x is None))
 
 
+@dataclass_json
+@dataclass
+class VCFFile(SingleSampleVCF):
+    """Deprecated alias for :class:`SingleSampleVCF` - use that instead. """
+    def __post_init__(self):
+        warnings.warn(
+            "VCFFile is deprecated; use SingleSampleVCF instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+
 @dataclass_json
 @dataclass
 class SequencingFile:
@@ -136,7 +187,7 @@ class SequencingFile:
     fastq_r1: str
     fastq_r2: str
     bam_file: BamFile
-    vcf_file: VCFFile
+    vcf_file: SingleSampleVCF
 
 
 @dataclass_json
@@ -155,7 +206,7 @@ class QC:
      """
     sequencing_sample_lookup: SequencingSampleLookup = field(metadata=config(field_name="sequencing_sample"))
     bam_file: BamFile
-    vcf_file: VCFFile
+    vcf_file: SingleSampleVCF
 
 
 @dataclass_json