Skip to content

BigScape

nplinker.genomics.bigscape

BigscapeGCFLoader 

BigscapeGCFLoader(cluster_file: str | PathLike)

Bases: GCFLoaderBase

Data loader for BiG-SCAPE GCF cluster file.

Attributes:

Parameters:

  • cluster_file (str | PathLike) –

    Path to the BiG-SCAPE cluster file, the filename has a pattern of <class>_clustering_c0.xx.tsv.

Source code in src/nplinker/genomics/bigscape/bigscape_loader.py 
20
21
22
23
24
25
26
27
28
def __init__(self, cluster_file: str | PathLike, /) -> None:
    """Initialize the BiG-SCAPE GCF loader.

    Args:
        cluster_file: Path to the BiG-SCAPE cluster file,
            the filename has a pattern of `<class>_clustering_c0.xx.tsv`.
    """
    self.cluster_file: str = str(cluster_file)
    self._gcf_list = self._parse_gcf(self.cluster_file)

cluster_file instance-attribute 

cluster_file: str = str(cluster_file)

get_gcfs 

get_gcfs(
    keep_mibig_only: bool = False,
    keep_singleton: bool = False,
) -> list[GCF]

Get all GCF objects.

Parameters:

  • keep_mibig_only (bool, default: False ) –

    True to keep GCFs that contain only MIBiG BGCs.

  • keep_singleton (bool, default: False ) –

    True to keep singleton GCFs. A singleton GCF is a GCF that contains only one BGC.

Returns:

  • list[GCF] –

    A list of GCF objects.

Source code in src/nplinker/genomics/bigscape/bigscape_loader.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def get_gcfs(self, keep_mibig_only: bool = False, keep_singleton: bool = False) -> list[GCF]:
    """Get all GCF objects.

    Args:
        keep_mibig_only: True to keep GCFs that contain only MIBiG
            BGCs.
        keep_singleton: True to keep singleton GCFs. A singleton GCF
            is a GCF that contains only one BGC.

    Returns:
        A list of GCF objects.
    """
    gcf_list = self._gcf_list
    if not keep_mibig_only:
        gcf_list = [gcf for gcf in gcf_list if not gcf.has_mibig_only()]
    if not keep_singleton:
        gcf_list = [gcf for gcf in gcf_list if not gcf.is_singleton()]
    return gcf_list

BigscapeV2GCFLoader 

BigscapeV2GCFLoader(db_file: str | PathLike)

Bases: GCFLoaderBase

Data loader for BiG-SCAPE v2 database file.

Attributes:

  • db_file –

    Path to the BiG-SCAPE database file.

Parameters:

  • db_file (str | PathLike) –

    Path to the BiG-SCAPE v2 database file

Source code in src/nplinker/genomics/bigscape/bigscape_loader.py 
71
72
73
74
75
76
77
78
def __init__(self, db_file: str | PathLike, /) -> None:
    """Initialize the BiG-SCAPE v2 GCF loader.

    Args:
        db_file: Path to the BiG-SCAPE v2 database file
    """
    self.db_file = str(db_file)
    self._gcf_list = self._parse_gcf(self.db_file)

db_file instance-attribute 

db_file = str(db_file)

get_gcfs 

get_gcfs(
    keep_mibig_only: bool = False,
    keep_singleton: bool = False,
) -> list[GCF]

Get all GCF objects.

Parameters:

  • keep_mibig_only (bool, default: False ) –

    True to keep GCFs that contain only MIBiG BGCs.

  • keep_singleton (bool, default: False ) –

    True to keep singleton GCFs. A singleton GCF is a GCF that contains only one BGC.

Returns:

  • list[GCF] –

    a list of GCF objects.

Source code in src/nplinker/genomics/bigscape/bigscape_loader.py 
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
def get_gcfs(self, keep_mibig_only: bool = False, keep_singleton: bool = False) -> list[GCF]:
    """Get all GCF objects.

    Args:
        keep_mibig_only: True to keep GCFs that contain only MIBiG BGCs.
        keep_singleton: True to keep singleton GCFs.
            A singleton GCF is a GCF that contains only one BGC.

    Returns:
        a list of GCF objects.
    """
    gcf_list = self._gcf_list
    if not keep_mibig_only:
        gcf_list = [gcf for gcf in gcf_list if not gcf.has_mibig_only()]
    if not keep_singleton:
        gcf_list = [gcf for gcf in gcf_list if not gcf.is_singleton()]
    return gcf_list

run_bigscape 

run_bigscape(
    antismash_path: str | PathLike,
    output_path: str | PathLike,
    extra_params: str,
    version: Literal["1", "2"] = "1",
) -> bool

Runs BiG-SCAPE to cluster BGCs.

The behavior of this function is slightly different depending on the version of BiG-SCAPE that is set to run using the configuration file. Mostly this means a different set of parameters is used between the two versions.

The AntiSMASH output directory should be a directory that contains GBK files. The directory can contain subdirectories, in which case BiG-SCAPE will search recursively for GBK files. E.g.:

example_folder
    ├── organism_1
    │  ├── organism_1.region001.gbk
    │  ├── organism_1.region002.gbk
    │  ├── organism_1.region003.gbk
    │  ├── organism_1.final.gbk          <- skipped!
    │  └── ...
    ├── organism_2
    │  ├── ...
    └── ...

By default, only GBK Files with "cluster" or "region" in the filename are accepted. GBK Files with "final" in the filename are excluded.

Parameters:

  • antismash_path (str | PathLike) –

    Path to the antismash output directory.

  • output_path (str | PathLike) –

    Path to the output directory where BiG-SCAPE will write its results.

  • extra_params (str) –

    Additional parameters to pass to BiG-SCAPE.

  • version (Literal['1', '2'], default: '1' ) –

    The version of BiG-SCAPE to run. Must be "1" or "2".

Returns:

  • bool –

    True if BiG-SCAPE ran successfully, False otherwise.

Raises:

  • ValueError –

    If an unexpected BiG-SCAPE version number is specified.

  • FileNotFoundError –

    If the antismash_path does not exist or if the BiG-SCAPE python script could not be found.

  • RuntimeError –

    If BiG-SCAPE fails to run.

Examples:

>>>  from nplinker.genomics.bigscape import run_bigscape
>>> run_bigscape(antismash_path="./antismash", output_path="./output",
... extra_params="--help", version="1")
Source code in src/nplinker/genomics/bigscape/runbigscape.py 
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def run_bigscape(
    antismash_path: str | PathLike,
    output_path: str | PathLike,
    extra_params: str,
    version: Literal["1", "2"] = "1",
) -> bool:
    """Runs BiG-SCAPE to cluster BGCs.

    The behavior of this function is slightly different depending on the version of
    BiG-SCAPE that is set to run using the configuration file.
    Mostly this means a different set of parameters is used between the two versions.

    The AntiSMASH output directory should be a directory that contains GBK files.
    The directory can contain subdirectories, in which case BiG-SCAPE will search
    recursively for GBK files. E.g.:

    ```
    example_folder
        ├── organism_1
        │  ├── organism_1.region001.gbk
        │  ├── organism_1.region002.gbk
        │  ├── organism_1.region003.gbk
        │  ├── organism_1.final.gbk          <- skipped!
        │  └── ...
        ├── organism_2
        │  ├── ...
        └── ...
    ```

    By default, only GBK Files with "cluster" or "region" in the filename are
    accepted. GBK Files with "final" in the filename are excluded.

    Args:
        antismash_path: Path to the antismash output directory.
        output_path: Path to the output directory where BiG-SCAPE will write its results.
        extra_params: Additional parameters to pass to BiG-SCAPE.
        version: The version of BiG-SCAPE to run. Must be "1" or "2".

    Returns:
        True if BiG-SCAPE ran successfully, False otherwise.

    Raises:
        ValueError: If an unexpected BiG-SCAPE version number is specified.
        FileNotFoundError: If the antismash_path does not exist or if the BiG-SCAPE python
            script could not be found.
        RuntimeError: If BiG-SCAPE fails to run.

    Examples:
        >>>  from nplinker.genomics.bigscape import run_bigscape
        >>> run_bigscape(antismash_path="./antismash", output_path="./output",
        ... extra_params="--help", version="1")
    """
    # switch to correct version of BiG-SCAPE
    if version == "1":
        bigscape_py_path = "bigscape.py"
    elif version == "2":
        bigscape_py_path = "bigscape"
    else:
        raise ValueError("Invalid BiG-SCAPE version number. Expected: '1' or '2'.")

    try:
        subprocess.run([bigscape_py_path, "-h"], capture_output=True, check=True)
    except Exception as e:
        raise FileNotFoundError(
            f"Failed to find/run BiG-SCAPE executable program (path={bigscape_py_path}, err={e})"
        ) from e

    if not os.path.exists(antismash_path):
        raise FileNotFoundError(f'antismash_path "{antismash_path}" does not exist!')

    logger.info(f"Running BiG-SCAPE version {version}")
    logger.info(
        f'run_bigscape: input="{antismash_path}", output="{output_path}", extra_params={extra_params}"'
    )

    # assemble arguments. first argument is the python file
    args = [bigscape_py_path]

    # version 2 points to specific Pfam file, version 1 points to directory
    # version 2 also requires the cluster subcommand
    if version == "1":
        args.extend(["--pfam_dir", PFAM_PATH])
    elif version == "2":
        args.extend(
            [
                "cluster",
                "--pfam-path",
                os.path.join(PFAM_PATH, "Pfam-A.hmm"),
                "--db-only-output",
            ]
        )

    # add input and output paths. these are unchanged
    args.extend(["-i", str(antismash_path), "-o", str(output_path)])

    # append the user supplied params, if any
    if len(extra_params) > 0:
        params = extra_params.split(" ")
        # BiG-SCAPE v2 uses Click which requires hyphens in option names,
        # while v1 used argparse which accepted both. Convert underscores
        # to hyphens in option names for v2 compatibility.
        if version == "2":
            params = [p.replace("_", "-") if p.startswith("-") else p for p in params]
        args.extend(params)

    logger.info(f"BiG-SCAPE command: {args}")
    result = subprocess.run(args, stdout=sys.stdout, stderr=sys.stderr)

    # return true on any non-error return code
    if result.returncode == 0:
        logger.info(f"BiG-SCAPE completed with return code {result.returncode}")
        return True

    # otherwise log details and raise a runtime error
    logger.error(f"BiG-SCAPE failed with return code {result.returncode}")
    logger.error(f"output: {str(result.stdout)}")
    logger.error(f"stderr: {str(result.stderr)}")

    raise RuntimeError(f"Failed to run BiG-SCAPE with error code {result.returncode}")