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 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,3 @@
1
+ from .api_backend import APIBackend
2
+
3
+ __all__ = ["APIBackend"]
@@ -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,4 @@
1
+ from .backend import BiocentralBackend
2
+ from .exceptions import NotAvailableError
3
+
4
+ __all__ = ["BiocentralBackend", "NotAvailableError"]
@@ -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
+ ...
@@ -0,0 +1,4 @@
1
+ class NotAvailableError(Exception):
2
+ """Raised when a feature is not available in the current execution mode."""
3
+
4
+ pass
@@ -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)
@@ -0,0 +1,3 @@
1
+ from .cli import biocentral
2
+
3
+ __all__ = ["biocentral"]