biocentral 2.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- biocentral/__init__.py +14 -0
- biocentral/api/__init__.py +3 -0
- biocentral/api/api_backend.py +74 -0
- biocentral/base/__init__.py +4 -0
- biocentral/base/backend.py +65 -0
- biocentral/base/exceptions.py +4 -0
- biocentral/biocentral.py +261 -0
- biocentral/cli/__init__.py +3 -0
- biocentral/cli/cli.py +295 -0
- biocentral/cli/server_cli.py +295 -0
- biocentral/local/__init__.py +3 -0
- biocentral/local/local_backend.py +228 -0
- biocentral/tui/__init__.py +14 -0
- biocentral/tui/core.py +363 -0
- biocentral/tui/errors_view.py +420 -0
- biocentral/tui/stats_view.py +330 -0
- biocentral-2.0.0.dist-info/METADATA +80 -0
- biocentral-2.0.0.dist-info/RECORD +22 -0
- biocentral-2.0.0.dist-info/WHEEL +5 -0
- biocentral-2.0.0.dist-info/entry_points.txt +2 -0
- biocentral-2.0.0.dist-info/licenses/LICENSE +9 -0
- biocentral-2.0.0.dist-info/top_level.txt +1 -0
biocentral/__init__.py
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
from biocentral_vis import BiocentralChart
|
|
2
|
+
from biocentral_api import BiocentralAPI, CommonEmbedder
|
|
3
|
+
|
|
4
|
+
from .biocentral import Biocentral
|
|
5
|
+
from .base import NotAvailableError
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
__all__ = [
|
|
9
|
+
"Biocentral",
|
|
10
|
+
"BiocentralAPI",
|
|
11
|
+
"BiocentralChart",
|
|
12
|
+
"NotAvailableError",
|
|
13
|
+
"CommonEmbedder",
|
|
14
|
+
]
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from typing import Dict, Any, List, Optional
|
|
4
|
+
|
|
5
|
+
from biocentral_api import (
|
|
6
|
+
BiocentralAPI,
|
|
7
|
+
BiotrainerModelResult,
|
|
8
|
+
BiotrainerInferenceResult,
|
|
9
|
+
Prediction,
|
|
10
|
+
BiocentralPredictionModel,
|
|
11
|
+
SequenceData,
|
|
12
|
+
ProjectionResult,
|
|
13
|
+
)
|
|
14
|
+
from biocentral_api.clients import EmbeddingsResult
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class APIBackend:
|
|
18
|
+
"""Backend that delegates all operations to a remote biocentral server via BiocentralAPI."""
|
|
19
|
+
|
|
20
|
+
def __init__(self, custom_api: Optional[BiocentralAPI] = None):
|
|
21
|
+
self._api = custom_api if custom_api else BiocentralAPI()
|
|
22
|
+
self._api.wait_until_healthy(max_wait_seconds=30)
|
|
23
|
+
|
|
24
|
+
def embed(
|
|
25
|
+
self,
|
|
26
|
+
embedder_name: str,
|
|
27
|
+
sequence_data: Dict[str, str],
|
|
28
|
+
reduce: bool = True,
|
|
29
|
+
use_half_precision: bool = False,
|
|
30
|
+
) -> EmbeddingsResult:
|
|
31
|
+
task = self._api.embed(
|
|
32
|
+
embedder_name,
|
|
33
|
+
sequence_data,
|
|
34
|
+
reduce=reduce,
|
|
35
|
+
use_half_precision=use_half_precision,
|
|
36
|
+
)
|
|
37
|
+
return task.run()
|
|
38
|
+
|
|
39
|
+
def train(
|
|
40
|
+
self, config: Dict[str, Any], training_data: List[SequenceData]
|
|
41
|
+
) -> BiotrainerModelResult:
|
|
42
|
+
task = self._api.train(config, training_data)
|
|
43
|
+
return task.run()
|
|
44
|
+
|
|
45
|
+
def inference(
|
|
46
|
+
self, model_hash: str, inference_data: Dict[str, str]
|
|
47
|
+
) -> BiotrainerInferenceResult:
|
|
48
|
+
task = self._api.inference(model_hash, inference_data)
|
|
49
|
+
return task.run()
|
|
50
|
+
|
|
51
|
+
def project(
|
|
52
|
+
self,
|
|
53
|
+
embedder_name: str,
|
|
54
|
+
method: str,
|
|
55
|
+
sequence_data: Dict[str, str],
|
|
56
|
+
projection_config: Dict[str, str],
|
|
57
|
+
) -> ProjectionResult:
|
|
58
|
+
task = self._api.project(
|
|
59
|
+
embedder_name, method, sequence_data, projection_config
|
|
60
|
+
)
|
|
61
|
+
return task.run()
|
|
62
|
+
|
|
63
|
+
def predict(
|
|
64
|
+
self, model_names: List[str], sequence_data: Dict[str, str]
|
|
65
|
+
) -> Dict[str, List[Prediction]]:
|
|
66
|
+
prediction_models = [BiocentralPredictionModel(name) for name in model_names]
|
|
67
|
+
task = self._api.predict(prediction_models, sequence_data)
|
|
68
|
+
return task.run()
|
|
69
|
+
|
|
70
|
+
def cluster(
|
|
71
|
+
self, sequence_data: Dict[str, str], sequence_identity_threshold: float = 0.3
|
|
72
|
+
) -> Dict[str, List[str]]:
|
|
73
|
+
task = self._api.cluster(sequence_data, sequence_identity_threshold)
|
|
74
|
+
return task.run()
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from typing import Protocol, Dict, Any, List, runtime_checkable
|
|
4
|
+
|
|
5
|
+
from biocentral_api import (
|
|
6
|
+
BiotrainerModelResult,
|
|
7
|
+
BiotrainerInferenceResult,
|
|
8
|
+
Prediction,
|
|
9
|
+
SequenceData,
|
|
10
|
+
ProjectionResult,
|
|
11
|
+
)
|
|
12
|
+
from biocentral_api.clients import EmbeddingsResult
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@runtime_checkable
|
|
16
|
+
class BiocentralBackend(Protocol):
|
|
17
|
+
"""Protocol defining the unified interface for biocentral backends.
|
|
18
|
+
|
|
19
|
+
Both APIBackend and LocalBackend implement this interface.
|
|
20
|
+
Methods that are not available in a given mode raise NotAvailableError.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
def embed(
|
|
24
|
+
self,
|
|
25
|
+
embedder_name: str,
|
|
26
|
+
sequence_data: Dict[str, str],
|
|
27
|
+
reduce: bool = True,
|
|
28
|
+
use_half_precision: bool = False,
|
|
29
|
+
) -> EmbeddingsResult:
|
|
30
|
+
"""Compute embeddings for the given sequences."""
|
|
31
|
+
...
|
|
32
|
+
|
|
33
|
+
def train(
|
|
34
|
+
self, config: Dict[str, Any], training_data: List[SequenceData]
|
|
35
|
+
) -> BiotrainerModelResult:
|
|
36
|
+
"""Train a model using biotrainer."""
|
|
37
|
+
...
|
|
38
|
+
|
|
39
|
+
def inference(
|
|
40
|
+
self, model_hash: str, inference_data: Dict[str, str]
|
|
41
|
+
) -> BiotrainerInferenceResult:
|
|
42
|
+
"""Run inference using a model trained via biotrainer (identified by hash)."""
|
|
43
|
+
...
|
|
44
|
+
|
|
45
|
+
def project(
|
|
46
|
+
self,
|
|
47
|
+
embedder_name: str,
|
|
48
|
+
method: str,
|
|
49
|
+
sequence_data: Dict[str, str],
|
|
50
|
+
projection_config: Dict[str, str],
|
|
51
|
+
) -> ProjectionResult:
|
|
52
|
+
"""Run projection for the embeddings of the given sequences (e.g. UMAP, PCA)"""
|
|
53
|
+
...
|
|
54
|
+
|
|
55
|
+
def predict(
|
|
56
|
+
self, model_names: List[str], sequence_data: Dict[str, str]
|
|
57
|
+
) -> Dict[str, List[Prediction]]:
|
|
58
|
+
"""Predict using pre-trained server-hosted models (server only)."""
|
|
59
|
+
...
|
|
60
|
+
|
|
61
|
+
def cluster(
|
|
62
|
+
self, sequence_data: Dict[str, str], sequence_identity_threshold: float = 0.3
|
|
63
|
+
) -> Dict[str, List[str]]:
|
|
64
|
+
"""Cluster the provided sequences using pymmseqs."""
|
|
65
|
+
...
|
biocentral/biocentral.py
ADDED
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from biocentral_vis import BiocentralChart
|
|
4
|
+
from typing import Dict, Any, List, Optional, Union
|
|
5
|
+
|
|
6
|
+
from biocentral_api import (
|
|
7
|
+
BiotrainerModelResult,
|
|
8
|
+
BiotrainerInferenceResult,
|
|
9
|
+
Prediction,
|
|
10
|
+
BiocentralAPI,
|
|
11
|
+
SequenceData,
|
|
12
|
+
ProjectionResult,
|
|
13
|
+
)
|
|
14
|
+
from biocentral_api.clients import EmbeddingsResult
|
|
15
|
+
|
|
16
|
+
from .base import BiocentralBackend
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class Biocentral:
|
|
20
|
+
"""Unified entry point to the biocentral ecosystem.
|
|
21
|
+
|
|
22
|
+
Provides a single interface for embedding, training, inference, and prediction
|
|
23
|
+
that works both locally (via biotrainer) and remotely (via biocentral server API).
|
|
24
|
+
|
|
25
|
+
Examples:
|
|
26
|
+
|
|
27
|
+
# API mode (default) - requires a running biocentral server
|
|
28
|
+
bc = Biocentral(mode="api")
|
|
29
|
+
result = bc.embed("Rostlab/prot_t5_xl_uniref50", {"seq1": "MKTL"})
|
|
30
|
+
|
|
31
|
+
# Local mode - requires pip install biocentral[local]
|
|
32
|
+
bc = Biocentral(mode="local", device="cuda")
|
|
33
|
+
result = bc.embed("Rostlab/prot_t5_xl_uniref50", {"seq1": "MKTL"})
|
|
34
|
+
|
|
35
|
+
# Train and then run inference using the model hash
|
|
36
|
+
model_result = bc.train(config, training_data)
|
|
37
|
+
model_hash = model_result.derived_values.model_hash
|
|
38
|
+
inference_result = bc.inference(model_hash, {"seq1": "MKTL"})
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
def __init__(
|
|
42
|
+
self,
|
|
43
|
+
mode: str = "api",
|
|
44
|
+
custom_api: Optional[BiocentralAPI] = None,
|
|
45
|
+
device: Optional[str] = None,
|
|
46
|
+
):
|
|
47
|
+
"""
|
|
48
|
+
:param mode: Execution mode - "api" for remote server, "local" for local biotrainer execution.
|
|
49
|
+
:param custom_api: Custom BiocentralAPI instance (api mode only).
|
|
50
|
+
:param device: Device for local computation, e.g. "cuda" or "cpu" (local mode only).
|
|
51
|
+
"""
|
|
52
|
+
self._mode = mode
|
|
53
|
+
|
|
54
|
+
if mode == "api":
|
|
55
|
+
from .api import APIBackend
|
|
56
|
+
|
|
57
|
+
self._backend: BiocentralBackend = APIBackend(
|
|
58
|
+
custom_api=custom_api,
|
|
59
|
+
)
|
|
60
|
+
elif mode == "local":
|
|
61
|
+
from .local import LocalBackend
|
|
62
|
+
|
|
63
|
+
self._backend = LocalBackend(device=device)
|
|
64
|
+
else:
|
|
65
|
+
raise ValueError(f"Unknown mode: '{mode}'. Use 'api' or 'local'.")
|
|
66
|
+
|
|
67
|
+
@property
|
|
68
|
+
def mode(self) -> str:
|
|
69
|
+
return self._mode
|
|
70
|
+
|
|
71
|
+
@staticmethod
|
|
72
|
+
def _read_fasta(sequence_data: str) -> List[SequenceData]:
|
|
73
|
+
from biotrainer_core.input_files import read_FASTA
|
|
74
|
+
from pathlib import Path
|
|
75
|
+
|
|
76
|
+
fasta_path = Path(sequence_data)
|
|
77
|
+
if not fasta_path.exists():
|
|
78
|
+
raise ValueError(f"FASTA file not found: {fasta_path}")
|
|
79
|
+
records = read_FASTA(fasta_path)
|
|
80
|
+
return records
|
|
81
|
+
|
|
82
|
+
@staticmethod
|
|
83
|
+
def _parse_input_as_dict(
|
|
84
|
+
sequence_data: Union[str, Dict[str, str], List[SequenceData]],
|
|
85
|
+
) -> Dict[str, str]:
|
|
86
|
+
if isinstance(sequence_data, str):
|
|
87
|
+
records = Biocentral._read_fasta(sequence_data)
|
|
88
|
+
seq_dat = {r.seq_id: r.seq for r in records}
|
|
89
|
+
elif isinstance(sequence_data, list):
|
|
90
|
+
seq_dat = {r.seq_id: r.seq for r in sequence_data}
|
|
91
|
+
elif isinstance(sequence_data, dict):
|
|
92
|
+
seq_dat = sequence_data
|
|
93
|
+
else:
|
|
94
|
+
raise ValueError(f"Invalid sequence data type: {type(sequence_data)}")
|
|
95
|
+
|
|
96
|
+
if len(seq_dat) == 0:
|
|
97
|
+
raise ValueError("No sequences found in input data")
|
|
98
|
+
|
|
99
|
+
return seq_dat
|
|
100
|
+
|
|
101
|
+
@staticmethod
|
|
102
|
+
def _parse_input_as_sequence_data(
|
|
103
|
+
sequence_data: Union[str, Dict[str, str], List[SequenceData]],
|
|
104
|
+
) -> List[SequenceData]:
|
|
105
|
+
if isinstance(sequence_data, str):
|
|
106
|
+
seq_dat = Biocentral._read_fasta(sequence_data)
|
|
107
|
+
elif isinstance(sequence_data, list) and len(sequence_data) > 0 and isinstance(sequence_data[0], SequenceData):
|
|
108
|
+
seq_dat = sequence_data
|
|
109
|
+
elif isinstance(sequence_data, dict):
|
|
110
|
+
seq_dat = [SequenceData(seq_id=k, seq=v) for k, v in sequence_data.items()]
|
|
111
|
+
else:
|
|
112
|
+
raise ValueError(f"Invalid sequence data type: {type(sequence_data)}")
|
|
113
|
+
|
|
114
|
+
if len(seq_dat) == 0:
|
|
115
|
+
raise ValueError("No sequences found in input data")
|
|
116
|
+
|
|
117
|
+
return seq_dat
|
|
118
|
+
|
|
119
|
+
@staticmethod
|
|
120
|
+
def visualize(sequence_data: Union[str, Dict[str, str], List[SequenceData]], save: bool = False) -> List[
|
|
121
|
+
BiocentralChart]:
|
|
122
|
+
"""
|
|
123
|
+
Visualize a given set of proteins. Automatically tries to find the best available visualization method(s).
|
|
124
|
+
For more fine-grained visualizations, use the BiocentralChart class directly.
|
|
125
|
+
|
|
126
|
+
:param sequence_data: Dict of {id: sequence} or path to a FASTA file.
|
|
127
|
+
:param save: Whether to save generated svg files in the current working directory. Defaults to False.
|
|
128
|
+
"""
|
|
129
|
+
seq_dat = Biocentral._parse_input_as_sequence_data(sequence_data)
|
|
130
|
+
have_labels = any([data_point.label is not None for data_point in seq_dat])
|
|
131
|
+
have_splits = any([data_point.set is not None for data_point in seq_dat])
|
|
132
|
+
|
|
133
|
+
plots_to_generate = [("Sequence Length Distribution",
|
|
134
|
+
lambda sd: BiocentralChart.sequence_length_distribution(dataset=sd))]
|
|
135
|
+
if have_labels:
|
|
136
|
+
plots_to_generate.append(("Label Distribution",
|
|
137
|
+
lambda sd: BiocentralChart.label_distribution(dataset=sd)),
|
|
138
|
+
)
|
|
139
|
+
if have_splits:
|
|
140
|
+
plots_to_generate.append(("Splits Distribution",
|
|
141
|
+
lambda sd: BiocentralChart.split_distribution(dataset=sd)))
|
|
142
|
+
if have_labels and have_splits:
|
|
143
|
+
plots_to_generate.append(("Label Distribution By Split",
|
|
144
|
+
lambda sd: BiocentralChart.labels_by_split_distribution(dataset=sd)))
|
|
145
|
+
|
|
146
|
+
plots: List[BiocentralChart] = []
|
|
147
|
+
|
|
148
|
+
print(f"Generating plots for dataset of {len(seq_dat)} sequences..")
|
|
149
|
+
for title, plotter in plots_to_generate:
|
|
150
|
+
print(f"Generating plot: {title}")
|
|
151
|
+
plot = plotter(seq_dat)
|
|
152
|
+
plots.append(plot)
|
|
153
|
+
|
|
154
|
+
if save:
|
|
155
|
+
for plot in plots:
|
|
156
|
+
plot.save(output_path=".")
|
|
157
|
+
|
|
158
|
+
return plots
|
|
159
|
+
|
|
160
|
+
def embed(
|
|
161
|
+
self,
|
|
162
|
+
embedder_name: str,
|
|
163
|
+
sequence_data: Union[str, Dict[str, str], List[SequenceData]],
|
|
164
|
+
reduce: bool = True,
|
|
165
|
+
use_half_precision: bool = False,
|
|
166
|
+
) -> EmbeddingsResult:
|
|
167
|
+
"""Compute embeddings for the given sequences.
|
|
168
|
+
|
|
169
|
+
:param embedder_name: Embedder identifier (e.g. "Rostlab/prot_t5_xl_uniref50").
|
|
170
|
+
:param sequence_data: Dict of {id: sequence} or path to a FASTA file.
|
|
171
|
+
:param reduce: Whether to reduce embeddings to per-sequence. Defaults to True.
|
|
172
|
+
:param use_half_precision: Use half precision to reduce memory. Defaults to False.
|
|
173
|
+
:return: EmbeddingsResult containing the computed embeddings.
|
|
174
|
+
"""
|
|
175
|
+
seq_dat = self._parse_input_as_dict(sequence_data)
|
|
176
|
+
|
|
177
|
+
return self._backend.embed(
|
|
178
|
+
embedder_name, seq_dat, reduce=reduce, use_half_precision=use_half_precision
|
|
179
|
+
)
|
|
180
|
+
|
|
181
|
+
def train(
|
|
182
|
+
self, config: Dict[str, Any], training_data: Union[str, List[SequenceData]]
|
|
183
|
+
) -> BiotrainerModelResult:
|
|
184
|
+
"""Train a model using biotrainer.
|
|
185
|
+
|
|
186
|
+
:param config: Training configuration dict (must include "embedder_name" and "protocol").
|
|
187
|
+
:param training_data: List of SequenceData objects for training or path to biotrainer fasta file.
|
|
188
|
+
:return: BiotrainerModelResult with training results and model hash.
|
|
189
|
+
"""
|
|
190
|
+
training_data = self._parse_input_as_sequence_data(training_data)
|
|
191
|
+
return self._backend.train(config, training_data)
|
|
192
|
+
|
|
193
|
+
def inference(
|
|
194
|
+
self,
|
|
195
|
+
model_result: Union[str, BiotrainerModelResult],
|
|
196
|
+
inference_data: Union[str, Dict[str, str], List[SequenceData]],
|
|
197
|
+
) -> BiotrainerInferenceResult:
|
|
198
|
+
"""Run inference using a model trained via biotrainer, identified by its hash.
|
|
199
|
+
|
|
200
|
+
:param model_result: Either hash of the trained model (from BiotrainerModelResult.derived_values.model_hash)
|
|
201
|
+
or provide the BiotrainerModelResult directly.
|
|
202
|
+
:param inference_data: Dict of {id: sequence} or path to a FASTA file.
|
|
203
|
+
:return: BiotrainerInferenceResult with predictions.
|
|
204
|
+
"""
|
|
205
|
+
inference_dat = self._parse_input_as_dict(inference_data)
|
|
206
|
+
if isinstance(model_result, BiotrainerModelResult):
|
|
207
|
+
model_hash = model_result.derived_values.model_hash
|
|
208
|
+
if model_hash is None:
|
|
209
|
+
raise ValueError(
|
|
210
|
+
"Model hash is None. Please provide a valid model hash or BiotrainerModelResult."
|
|
211
|
+
)
|
|
212
|
+
else:
|
|
213
|
+
model_hash = model_result
|
|
214
|
+
return self._backend.inference(model_hash, inference_dat)
|
|
215
|
+
|
|
216
|
+
def project(
|
|
217
|
+
self,
|
|
218
|
+
embedder_name: str,
|
|
219
|
+
method: str,
|
|
220
|
+
sequence_data: Union[str, Dict[str, str], List[SequenceData]],
|
|
221
|
+
projection_config: Dict[str, str],
|
|
222
|
+
) -> ProjectionResult:
|
|
223
|
+
project_dat = self._parse_input_as_dict(sequence_data)
|
|
224
|
+
|
|
225
|
+
return self._backend.project(
|
|
226
|
+
embedder_name, method, project_dat, projection_config
|
|
227
|
+
)
|
|
228
|
+
|
|
229
|
+
def predict(
|
|
230
|
+
self,
|
|
231
|
+
model_names: List[str],
|
|
232
|
+
sequence_data: Union[str, Dict[str, str], List[SequenceData]],
|
|
233
|
+
) -> Dict[str, List[Prediction]]:
|
|
234
|
+
"""Predict using pre-trained server-hosted models (API mode only).
|
|
235
|
+
|
|
236
|
+
:param model_names: List of BiocentralPredictionModel names.
|
|
237
|
+
:param sequence_data: Dict of {id: sequence} or path to a FASTA file.
|
|
238
|
+
:return: Dict mapping model names to lists of Predictions.
|
|
239
|
+
:raises NotAvailableError: If called in local mode.
|
|
240
|
+
"""
|
|
241
|
+
predict_dat = self._parse_input_as_dict(sequence_data)
|
|
242
|
+
|
|
243
|
+
return self._backend.predict(model_names, predict_dat)
|
|
244
|
+
|
|
245
|
+
def cluster(
|
|
246
|
+
self, sequence_data: Union[str, Dict[str, str], List[SequenceData]],
|
|
247
|
+
sequence_identity_threshold: float = 0.3
|
|
248
|
+
) -> Dict[str, List[str]]:
|
|
249
|
+
"""
|
|
250
|
+
Cluster sequences into groups based on sequence identity.
|
|
251
|
+
|
|
252
|
+
:param sequence_data: Dict of {id: sequence} or path to a FASTA file.
|
|
253
|
+
:param sequence_identity_threshold: Threshold for sequence identity.
|
|
254
|
+
:return: Dict mapping sequence IDs to cluster IDs.
|
|
255
|
+
"""
|
|
256
|
+
cluster_dat = self._parse_input_as_dict(sequence_data)
|
|
257
|
+
|
|
258
|
+
if len(cluster_dat) <= 1:
|
|
259
|
+
raise ValueError("At least two sequences are required for clustering!")
|
|
260
|
+
|
|
261
|
+
return self._backend.cluster(cluster_dat, sequence_identity_threshold)
|