biocentral 2.0.0__tar.gz

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.
@@ -0,0 +1,9 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright © 2026 biocentral (Sebastian Franz)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
6
+
7
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8
+
9
+ THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,80 @@
1
+ Metadata-Version: 2.4
2
+ Name: biocentral
3
+ Version: 2.0.0
4
+ Summary: Unified Python access to the biocentral ecosystem.
5
+ Author-email: Sebastian Franz <sebastian.franz@tum.de>
6
+ Project-URL: Repository, https://github.com/biocentral/biocentral
7
+ Keywords: Biocentral,Biotrainer,Protein,Embeddings,Deep Learning
8
+ Requires-Python: <3.14,>=3.12
9
+ Description-Content-Type: text/markdown
10
+ License-File: LICENSE
11
+ Requires-Dist: biocentral-api<3.0.0,>=2.0.0
12
+ Requires-Dist: biotrainer-core<3.0.0,>=2.0.0
13
+ Requires-Dist: biocentral-vis<3.0.0,>=2.0.0
14
+ Requires-Dist: click<9.0.0,>=8.0.0
15
+ Requires-Dist: platformdirs<5.0.0,>=4.0.0
16
+ Provides-Extra: server
17
+ Requires-Dist: biocentral-server<3.0.0,>=2.0.0; extra == "server"
18
+ Provides-Extra: local
19
+ Requires-Dist: biotrainer<3.0.0,>=2.0.0; extra == "local"
20
+ Requires-Dist: pymmseqs>=1.2.0; extra == "local"
21
+ Provides-Extra: all
22
+ Requires-Dist: biotrainer<3.0.0,>=2.0.0; extra == "all"
23
+ Requires-Dist: biocentral-server<3.0.0,>=2.0.0; extra == "all"
24
+ Dynamic: license-file
25
+
26
+ # biocentral
27
+
28
+ This is the *biocentral* python package, providing all functionality of the biocentral ecosystem in one package.
29
+
30
+ ## Installation
31
+
32
+ Install from [pypi](https://pypi.org/project/biocentral/) using pip:
33
+ ```shell
34
+ pip install biocentral
35
+ ```
36
+
37
+ If you want to deploy your own [server](https://github.com/biocentral/biocentral/tree/main/biocentral_server),
38
+ add the *server* extra:
39
+ ```shell
40
+ pip install biocentral[server]
41
+ ```
42
+
43
+ If you want to run local functionality, add the *local* extra:
44
+ ```shell
45
+ pip install biocentral[local]
46
+ ```
47
+
48
+ *Note that local and server install require large dependencies, while the default mode is minimal and lightweight.*
49
+
50
+ ## Quick Start
51
+
52
+ 1. Create a biocentral object:
53
+ ```python
54
+ from biocentral import Biocentral
55
+
56
+ biocentral = Biocentral(mode="api") # or "local"
57
+ ```
58
+
59
+ 2. Visualize some data:
60
+ ```python
61
+ from biocentral import BiocentralChart
62
+ from biotrainer_core.input_files import read_FASTA
63
+
64
+ sequence_data = read_FASTA("your_sequences.fasta")
65
+
66
+ sequence_length_distribution = BiocentralChart.sequence_length_distribution(sequence_data)
67
+ sequence_length_distribution.chart.interactive()
68
+ ```
69
+
70
+ 3. Embed the sequences via a *protein language model*:
71
+ ```python
72
+ embeddings = biocentral.embed(embedder_name="Rostlab/ProstT5", sequence_data=sequence_data, reduce=True)
73
+ print(embeddings)
74
+ ```
75
+
76
+ Find more examples in the [examples directory](examples)!
77
+
78
+ ## License
79
+
80
+ This package is subject to the [MIT License](LICENSE).
@@ -0,0 +1,55 @@
1
+ # biocentral
2
+
3
+ This is the *biocentral* python package, providing all functionality of the biocentral ecosystem in one package.
4
+
5
+ ## Installation
6
+
7
+ Install from [pypi](https://pypi.org/project/biocentral/) using pip:
8
+ ```shell
9
+ pip install biocentral
10
+ ```
11
+
12
+ If you want to deploy your own [server](https://github.com/biocentral/biocentral/tree/main/biocentral_server),
13
+ add the *server* extra:
14
+ ```shell
15
+ pip install biocentral[server]
16
+ ```
17
+
18
+ If you want to run local functionality, add the *local* extra:
19
+ ```shell
20
+ pip install biocentral[local]
21
+ ```
22
+
23
+ *Note that local and server install require large dependencies, while the default mode is minimal and lightweight.*
24
+
25
+ ## Quick Start
26
+
27
+ 1. Create a biocentral object:
28
+ ```python
29
+ from biocentral import Biocentral
30
+
31
+ biocentral = Biocentral(mode="api") # or "local"
32
+ ```
33
+
34
+ 2. Visualize some data:
35
+ ```python
36
+ from biocentral import BiocentralChart
37
+ from biotrainer_core.input_files import read_FASTA
38
+
39
+ sequence_data = read_FASTA("your_sequences.fasta")
40
+
41
+ sequence_length_distribution = BiocentralChart.sequence_length_distribution(sequence_data)
42
+ sequence_length_distribution.chart.interactive()
43
+ ```
44
+
45
+ 3. Embed the sequences via a *protein language model*:
46
+ ```python
47
+ embeddings = biocentral.embed(embedder_name="Rostlab/ProstT5", sequence_data=sequence_data, reduce=True)
48
+ print(embeddings)
49
+ ```
50
+
51
+ Find more examples in the [examples directory](examples)!
52
+
53
+ ## License
54
+
55
+ This package is subject to the [MIT License](LICENSE).
@@ -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"]