API Reference¶
Auto-generated API documentation from source code docstrings.
High-Level API¶
The Builder and VirtualCell classes provide the simplest interface for creating and simulating virtual cell models. See Quick Start for usage examples.
synthetic.api.Builder
¶
Factory for creating virtual cell models.
Provides a static method for creating VirtualCell instances with a clean, fluent API.
Source code in src/synthetic/api.py
470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 | |
from_endpoint(endpoint: str, simulation_end: float = 10000.0, drug_names: Optional[List[str]] = None, timeout: float = 300.0, auto_compile: bool = True) -> RemoteCell
staticmethod
¶
Create a remote cell model from an HTTP endpoint.
The server must implement the HTTP Solver API: - POST /simulate: Run simulation with optional state/parameter overrides - GET /states: Return default state values - GET /parameters: Return default parameter values
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
endpoint
|
str
|
HTTP endpoint URL (e.g., "http://localhost:8000/simulate") |
required |
simulation_end
|
float
|
Simulation end time for make_dataset_drug_response (default: 10000.0) |
10000.0
|
drug_names
|
Optional[List[str]]
|
Names of drug species on the server to exclude from features |
None
|
timeout
|
float
|
Request timeout in seconds (default: 300.0) |
300.0
|
auto_compile
|
bool
|
Validate endpoint and fetch metadata immediately (default: True) |
True
|
Returns:
| Type | Description |
|---|---|
RemoteCell
|
RemoteCell instance (compiled if auto_compile=True) |
Source code in src/synthetic/api.py
528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 | |
specify(degree_cascades: List[int], name: str = 'VirtualCell', random_seed: Optional[int] = None, feedback_density: float = 1, auto_compile: bool = True, auto_drug: bool = True, drug_name: str = 'D', drug_start_time: float = 5000.0, drug_value: float = 100.0, drug_regulation_type: str = 'down', simulation_end: float = 10000.0) -> VirtualCell
staticmethod
¶
Create a virtual cell specification.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
degree_cascades
|
List[int]
|
List of cascade counts per degree, e.g., [1, 2, 5] |
required |
name
|
str
|
Name for the virtual cell |
'VirtualCell'
|
random_seed
|
Optional[int]
|
Optional random seed for reproducibility |
None
|
feedback_density
|
float
|
Proportion of feedback connections (0-1) |
1
|
auto_compile
|
bool
|
Compile immediately after creation (default: True) |
True
|
auto_drug
|
bool
|
Auto-generate a drug targeting degree 1 R species (default: True) |
True
|
drug_name
|
str
|
Name for auto-generated drug (default: "D") |
'D'
|
drug_start_time
|
float
|
Time at which auto-drug becomes active (default: 5000.0) |
5000.0
|
drug_value
|
float
|
Active concentration for auto-drug (default: 100.0) |
100.0
|
drug_regulation_type
|
str
|
Regulation type for auto-drug: "up" or "down" (default: "down") |
'down'
|
simulation_end
|
float
|
Simulation end time for make_dataset_drug_response (default: 10000.0) |
10000.0
|
Returns:
| Type | Description |
|---|---|
VirtualCell
|
VirtualCell instance (compiled if auto_compile=True) |
Source code in src/synthetic/api.py
478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 | |
synthetic.api.VirtualCell
¶
High-level abstraction for a virtual cell model.
Uses DegreeInteractionSpec for network topology and KineticParameterTuner for biologically plausible kinetic parameters.
This class provides a simple API for creating and managing virtual cell models without needing to understand the underlying complexity of the Synthetic library's architecture.
Source code in src/synthetic/api.py
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 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 | |
compile(mean_range_species: Tuple[int, int] = (50, 150), rangeScale_params: Tuple[float, float] = (0.8, 1.2), rangeMultiplier_params: Tuple[float, float] = (0.9, 1.1), use_kinetic_tuner: bool = True, active_percentage_range: Tuple[float, float] = (0.3, 0.7), X_total_multiplier: float = 5.0, ki_val: float = 100.0, v_max_f_random_range: Tuple[float, float] = (5.0, 10.0)) -> VirtualCell
¶
Compile the model (lazy initialization).
Creates the underlying DegreeInteractionSpec, ModelBuilder, and optionally applies KineticParameterTuner for biologically plausible parameters.
If auto_drug is enabled, automatically generates a drug targeting degree 1 R species and applies its parameters to the model.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mean_range_species
|
Tuple[int, int]
|
Range for initial species values |
(50, 150)
|
rangeScale_params
|
Tuple[float, float]
|
Range for parameter scaling |
(0.8, 1.2)
|
rangeMultiplier_params
|
Tuple[float, float]
|
Range for parameter multiplier |
(0.9, 1.1)
|
use_kinetic_tuner
|
bool
|
Whether to use KineticParameterTuner (default: True) |
True
|
active_percentage_range
|
Tuple[float, float]
|
Target active percentage range for tuning |
(0.3, 0.7)
|
X_total_multiplier
|
float
|
Multiplier for Km_b calculation |
5.0
|
ki_val
|
float
|
Constant Ki value for inhibitors |
100.0
|
v_max_f_random_range
|
Tuple[float, float]
|
Range for total forward Vmax |
(5.0, 10.0)
|
Returns:
| Type | Description |
|---|---|
VirtualCell
|
self for method chaining |
Source code in src/synthetic/api.py
171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 | |
add_drug(name: str, start_time: float = 500.0, default_value: float = 0.0, regulation: Optional[List[str]] = None, regulation_type: Optional[List[str]] = None, value: Optional[float] = None) -> VirtualCell
¶
Add a drug to the cell model.
Drugs can only target degree 1 R species. The drug appears at start_time via a piecewise assignment rule and regulates the specified species.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name of the drug |
required |
start_time
|
float
|
Time at which drug becomes active (default: 500.0) |
500.0
|
default_value
|
float
|
Default value when drug is not active (default: 0.0) |
0.0
|
regulation
|
Optional[List[str]]
|
List of target species (must be degree 1 R species) |
None
|
regulation_type
|
Optional[List[str]]
|
List of regulation types ('up' or 'down') |
None
|
value
|
Optional[float]
|
Optional override value for when drug is active |
None
|
Returns:
| Type | Description |
|---|---|
VirtualCell
|
self for method chaining |
Source code in src/synthetic/api.py
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 | |
list_drugs() -> List[Dict[str, Any]]
¶
List all drugs in the system (both auto-generated and manually added).
Returns:
| Type | Description |
|---|---|
List[Dict[str, Any]]
|
List of dictionaries with drug information: |
List[Dict[str, Any]]
|
[{'name': 'D', 'targets': ['R1_1'], 'types': ['down'], 'start_time': 5000.0, 'default_value': 0.0, 'is_auto': True}, ...] |
Source code in src/synthetic/api.py
126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 | |
get_species_names(exclude_drugs: bool = True) -> List[str]
¶
Get list of species names.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
exclude_drugs
|
bool
|
Whether to exclude drug species (default: True) |
True
|
Returns:
| Type | Description |
|---|---|
List[str]
|
List of species names |
Source code in src/synthetic/api.py
251 252 253 254 255 256 257 258 259 260 261 262 263 | |
get_initial_values(exclude_drugs: bool = True) -> Dict[str, float]
¶
Get initial species values from the compiled model.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
exclude_drugs
|
bool
|
Whether to exclude drug species (default: True) |
True
|
Returns:
| Type | Description |
|---|---|
Dict[str, float]
|
Dictionary mapping species names to initial values |
Source code in src/synthetic/api.py
265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 | |
get_target_concentrations() -> Dict[str, float]
¶
Get target active concentrations from the kinetic tuner.
Returns an empty dict if kinetic tuning was not used during compilation.
Returns:
| Type | Description |
|---|---|
Dict[str, float]
|
Dictionary mapping species names to target concentrations |
Source code in src/synthetic/api.py
287 288 289 290 291 292 293 294 295 296 297 298 299 300 | |
synthetic.api.make_dataset_drug_response(n: int, cell_model: Union[VirtualCell, RemoteCell], target_specie: str = 'Oa', perturbation_type: str = 'conserve_rules', perturbation_params: Optional[Dict[str, Any]] = None, parameter_values: Optional[Dict[str, float]] = None, param_perturbation_type: str = 'lognormal', param_perturbation_params: Optional[Dict[str, Any]] = None, simulation_params: Optional[Dict[str, Any]] = None, seed: Optional[int] = None, param_seed: Optional[int] = None, solver_type: str = 'scipy', jit: bool = True, verbose: bool = False, n_cores: int = 1, require_all_successful: bool = False, return_details: bool = True, capture_all_species: bool = True, exclude_outcome_from_features: bool = True, exclude_activated_from_features: bool = True, as_pandas: bool = True, return_timecourse: bool = False) -> Union[Tuple[pd.DataFrame, pd.Series], Tuple[np.ndarray, np.ndarray], Dict[str, Any]]
¶
Generate synthetic drug response dataset.
Creates a dataset compatible with scikit-learn's make_regression format. The feature matrix X contains species concentrations, and the target vector y contains the outcome values.
Drugs are NOT included in the X features - they affect the simulation but are not part of the feature matrix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
int
|
Number of samples to generate |
required |
cell_model
|
Union[VirtualCell, RemoteCell]
|
VirtualCell instance (must be compiled) |
required |
target_specie
|
str
|
Name of the outcome species to use as target (default: 'Oa') |
'Oa'
|
perturbation_type
|
str
|
Type of initial value perturbation ('uniform', 'gaussian', 'lognormal', 'lhs') |
'conserve_rules'
|
perturbation_params
|
Optional[Dict[str, Any]]
|
Parameters for perturbation distribution |
None
|
parameter_values
|
Optional[Dict[str, float]]
|
Dictionary of kinetic parameter values to perturb (optional) |
None
|
param_perturbation_type
|
str
|
Type of kinetic parameter perturbation ('none', 'uniform', 'gaussian', 'lognormal', 'lhs') |
'lognormal'
|
param_perturbation_params
|
Optional[Dict[str, Any]]
|
Parameters for kinetic parameter perturbation (optional) |
None
|
simulation_params
|
Optional[Dict[str, Any]]
|
Dictionary with 'start', 'end', 'points' keys |
None
|
seed
|
Optional[int]
|
Random seed for reproducibility (initial value perturbations) |
None
|
param_seed
|
Optional[int]
|
Random seed for parameter perturbations (uses seed if not provided) |
None
|
solver_type
|
str
|
Type of solver ('scipy', 'roadrunner', or 'http') |
'scipy'
|
jit
|
bool
|
Whether to use JIT compilation (only for scipy solver) |
True
|
verbose
|
bool
|
Whether to show progress bar |
False
|
require_all_successful
|
bool
|
Whether to require all samples to succeed (default: False) |
False
|
return_details
|
bool
|
If True, returns extended data structure with intermediate datasets (default: True) |
True
|
capture_all_species
|
bool
|
If True, captures timecourses for all species in returned data. |
True
|
as_pandas
|
bool
|
If True (default), returns pandas DataFrame for X and Series for y with feature names. If False, returns numpy arrays for X and y. |
True
|
return_timecourse
|
bool
|
If True, returns dictionary with X, y, timecourse, parameters, and metadata (default: False) |
False
|
Returns:
| Type | Description |
|---|---|
Union[Tuple[DataFrame, Series], Tuple[ndarray, ndarray], Dict[str, Any]]
|
If return_timecourse=False: If as_pandas=True: Tuple of (X, y) where X is pandas DataFrame with feature names and y is pandas Series If as_pandas=False: Tuple of (X, y) where X is numpy array (n_samples, n_features) and y is numpy array (n_samples,) |
Union[Tuple[DataFrame, Series], Tuple[ndarray, ndarray], Dict[str, Any]]
|
If return_timecourse=True: Dictionary with keys: - 'X': Feature matrix (basal state values) - 'y': Target values - 'timecourse': Timecourse simulation data (DataFrame with numpy arrays) - 'parameters': Kinetic parameters dataframe (None if not perturbed) - 'metadata': Dictionary with metadata about generation process |
Raises:
| Type | Description |
|---|---|
ValueError
|
If cell_model is not compiled or has invalid parameters |
Source code in src/synthetic/api.py
565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 | |
Model Building¶
Core classes for building biochemical reaction networks from scratch. See Model Building for the full guide.
synthetic.ModelBuilder.ModelBuilder
¶
Docstring
Source code in src/synthetic/ModelBuilder.py
11 12 13 14 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 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 | |
add_reaction(reaction: Reaction)
¶
Add a reaction to the model, the reaction must be an instance of the Reaction class
Source code in src/synthetic/ModelBuilder.py
177 178 179 180 181 182 183 184 185 186 187 188 189 190 | |
delete_reaction(reaction_name: str)
¶
Deletes a reaction from the model
Source code in src/synthetic/ModelBuilder.py
227 228 229 230 231 232 233 234 235 236 | |
precompile()
¶
Populates the state and parameter variables list in the class which are used to generate the antimony text The pre-compiled model will have functionalities for getting and setting specific state and parameter values, which gets passed directly into the antimony string
Source code in src/synthetic/ModelBuilder.py
292 293 294 295 296 297 298 299 300 | |
get_parameters() -> dict
¶
Extracts parameters and their values from all reactions in the class and returns a dict while subjecting to a naming rule.
If model is pre-compiled, returns the cached parameters.
Source code in src/synthetic/ModelBuilder.py
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 | |
get_state_variables() -> dict
¶
Extracts state variables and their values from all reactions in the class and returns a dict
non-unique state variables will only be repeated once, their default value will only follow the first repeated state variable
If model is pre-compiled, returns the cached states.
Source code in src/synthetic/ModelBuilder.py
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | |
set_parameter(parameter_name: str, value: float)
¶
Set a parameter value in the model
Source code in src/synthetic/ModelBuilder.py
30 31 32 33 34 35 36 37 38 | |
get_parameter(parameter_name: str) -> float
¶
Get a parameter value in the model
Source code in src/synthetic/ModelBuilder.py
40 41 42 43 44 45 46 | |
set_state(state_name: str, value: float)
¶
Set a state value in the model
Source code in src/synthetic/ModelBuilder.py
48 49 50 51 52 53 54 55 56 | |
get_state(state_name: str) -> float
¶
Get a state value in the model
Source code in src/synthetic/ModelBuilder.py
58 59 60 61 62 63 64 | |
get_regulator_parameter_map() -> dict
¶
Returns mapping from regulator (extra_state) names to parameter names (with r_index). The mapping is aggregated across all reactions in the model.
Source code in src/synthetic/ModelBuilder.py
140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 | |
get_parameter_regulator_map() -> dict
¶
Returns mapping from parameter names (with r_index) to regulator (extra_state) names. The mapping is aggregated across all reactions in the model.
Source code in src/synthetic/ModelBuilder.py
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 | |
get_antimony_model()
¶
Doc
Source code in src/synthetic/ModelBuilder.py
302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 | |
get_sbml_model() -> str
¶
Doc
Source code in src/synthetic/ModelBuilder.py
374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 | |
add_simple_piecewise(before_value: float, activation_time: float, after_value: float, state_name: str)
¶
Adds a simple piecewise function to the state variable state_name
Source code in src/synthetic/ModelBuilder.py
220 221 222 223 224 | |
combine(model: ModelBuilder, reactions_only=False) -> ModelBuilder
¶
Combine two models
Source code in src/synthetic/ModelBuilder.py
260 261 262 263 264 265 266 267 268 269 270 271 272 | |
copy(overwrite_name='') -> ModelBuilder
¶
Copy the model
Source code in src/synthetic/ModelBuilder.py
238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 | |
head()
¶
Returns the general characteristics of the model
Source code in src/synthetic/ModelBuilder.py
278 279 280 281 282 283 284 285 286 287 288 289 290 | |
synthetic.Reaction.Reaction
¶
This class represents a reaction in the system. ENSURE: use (a,) instead of (a) for tuples typing reaction_archtype: ReactionArchtype, reactants: Tuple[str], products: Tuple[str], extra_states: Tuple[str] = (), parameters_values: Union[dict, tuple] = (), reactant_values: Union[dict, tuple] = (), product_values: Union[dict, tuple] = ()
This class performs two types of matching:
- Index-based matching.
- Name-based matching < - far more reliable but difficult to implement
Source code in src/synthetic/Reaction.py
7 8 9 10 11 12 13 14 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 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 | |
copy() -> Reaction
¶
returns a copy of the reaction
Source code in src/synthetic/Reaction.py
403 404 405 406 407 | |
get_antimony_reaction_str(r_index: str) -> str
¶
generates an antimony string for the reaction, given the index of the reaction r_index: str, represents reaction name in the system, usually an simple index
Source code in src/synthetic/Reaction.py
276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 | |
get_antimony_reactions_reverse_str(r_index: str) -> str
¶
generates an antimony string for the reverse reaction, given the index of the reaction r_index: str, represents reaction name in the system, usually an simple index
Source code in src/synthetic/Reaction.py
344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 | |
get_parameters_for_regulator(regulator_name: str) -> list
¶
Returns list of parameter base names associated with the given regulator.
Source code in src/synthetic/Reaction.py
185 186 187 188 189 | |
get_reaction_parameters(r_index) -> Dict[str, float]
¶
returns a dictionary of the parameters in the reaction
Source code in src/synthetic/Reaction.py
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 | |
get_reaction_states() -> Dict[str, float]
¶
Extracts state variables and their values from all reactions in the class and returns a dict, where state variables are the reactants and products
non-unique state variables will only be repeated once, their default value will only follow the first repeated state variable
Source code in src/synthetic/Reaction.py
240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 | |
get_regulator_for_parameter(param_name: str) -> str
¶
Returns the regulator name associated with the given parameter base name. Returns empty string if no association.
Source code in src/synthetic/Reaction.py
191 192 193 194 195 196 | |
synthetic.ReactionArchtype.ReactionArchtype
¶
ReactionArchtype is a factory class that generates Reaction objects name: str, reactants: Tuple[str], products: Tuple[str], parameters: Tuple[str], rate_law: str, extra_states: Tuple[str] = (), assume_parameters_values: Union[dict, tuple] = None, assume_reactant_values: Union[dict, tuple] = None, assume_product_values: Union[dict, tuple] = None
Source code in src/synthetic/ReactionArchtype.py
3 4 5 6 7 8 9 10 11 12 13 14 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 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 | |
validate_parameters(parameter_values, parameters_list) -> bool
¶
Delegate to abstract implementation at _abstract_validate_values
Source code in src/synthetic/ReactionArchtype.py
156 157 158 159 160 161 162 | |
validate_product_values(product_values, products_list) -> bool
¶
Delegate to abstract implementation at _abstract_validate_values
Source code in src/synthetic/ReactionArchtype.py
174 175 176 177 178 179 180 | |
validate_rate_law(rate_law) -> bool
¶
this function validates the rate_law against the archtype It expects the rate_law to contain the parameters It expects the rate_law to contain the extra states ^ copilot generated
Source code in src/synthetic/ReactionArchtype.py
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 | |
validate_rate_laws(rate_law, reverse_rate_law) -> bool
¶
this function validates the rate_law against the archtype It expects the rate_law to contain the parameters It expects the rate_law to contain the extra states ^ copilot generated
Source code in src/synthetic/ReactionArchtype.py
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 | |
validate_reactant_values(reactant_values, reactant_list) -> bool
¶
Delegate to abstract implementation at _abstract_validate_values
Source code in src/synthetic/ReactionArchtype.py
165 166 167 168 169 170 171 | |
Specifications¶
Classes for defining network topology, regulations, and drug interactions. See Model Building for details.
synthetic.Specs.BaseSpec.BaseSpec
¶
Bases: ABC
Minimal abstract model specification. Contains only the essential contract for generating models. At the core, generate specifications takes in specific inputs from the user, which is then used to infer the regulation list.
Attributes:
| Name | Type | Description |
|---|---|---|
regulations |
List[Regulation]
|
List of regulations applicable to the model. |
Source code in src/synthetic/Specs/BaseSpec.py
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | |
generate_network(network_name: str, **kwargs) -> ModelBuilder
abstractmethod
¶
Generate a complete ModelBuilder instance from the specification.
Source code in src/synthetic/Specs/BaseSpec.py
33 34 35 36 37 38 | |
generate_specifications(**kwargs)
abstractmethod
¶
Populate the specification's internal state. This includes species lists and regulations based on the specific model type.
Source code in src/synthetic/Specs/BaseSpec.py
25 26 27 28 29 30 31 | |
synthetic.Specs.DegreeInteractionSpec.DegreeInteractionSpec
¶
Bases: MichaelisNetworkSpec
Multi-degree drug interaction network specification.
Generates networks with hierarchical degrees of interaction: - Degree 1: D -> {R} -> {I} -> O (central pathway) - Degrees 2+: R -> I only (independent cascades influencing lower degrees)
Each degree contains multiple cascades defined by degree_cascades list. Higher degrees provide feedback regulation to immediate lower degrees.
Example
spec = DegreeInteractionSpec(degree_cascades=[1, 2, 5, 10]) spec.generate_specifications(random_seed=42) model = spec.generate_network("multi_degree_network")
Source code in src/synthetic/Specs/DegreeInteractionSpec.py
11 12 13 14 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 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 | |
generate_specifications(random_seed: Optional[int] = None, feedback_density: float = 0.5, **kwargs)
¶
Generate complete network specifications.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
random_seed
|
Optional[int]
|
Random seed for reproducibility |
None
|
feedback_density
|
float
|
Proportion of feedback connections to create (0-1) |
0.5
|
**kwargs
|
Additional arguments (unused, for compatibility) |
{}
|
Source code in src/synthetic/Specs/DegreeInteractionSpec.py
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 | |
add_drug(drug: Drug, value: Optional[float] = None)
¶
Add a drug to the model, validating it only targets degree 1 R species.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
drug
|
Drug
|
Drug object containing name, start_time, default_value, and regulations |
required |
value
|
Optional[float]
|
Optional override for drug value |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If drug targets non-degree-1 species or non-R species |
Source code in src/synthetic/Specs/DegreeInteractionSpec.py
290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 | |
get_species_by_degree(degree: int, species_type: str = 'all') -> List[str]
¶
Get species for a specific degree.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
degree
|
int
|
Degree number (1-indexed) |
required |
species_type
|
str
|
'R', 'I', or 'all' |
'all'
|
Returns:
| Type | Description |
|---|---|
List[str]
|
List of species names |
Source code in src/synthetic/Specs/DegreeInteractionSpec.py
318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 | |
get_regulations_by_degree(degree: Optional[int] = None) -> List[Regulation]
¶
Get regulations for a specific degree or all degrees.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
degree
|
Optional[int]
|
Degree number (1-indexed) or None for all |
None
|
Returns:
| Type | Description |
|---|---|
List[Regulation]
|
List of Regulation objects |
Source code in src/synthetic/Specs/DegreeInteractionSpec.py
342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 | |
synthetic.Specs.MichaelisNetworkSpec.MichaelisNetworkSpec
¶
Bases: BaseSpec
Generic Michaelis-Menten network specification with ModelSpec4-style drug mechanism.
Features: 1. Generic species management (any network topology) 2. ModelSpec4's reaction generation scheme 3. ModelSpec4's drug mechanism (drugs as species with regulations) 4. Flexible specification generation (random or manual) 5. Michaelis-Menten kinetics with up/down regulation
Example usage:
spec = MichaelisNetworkSpec()
spec.generate_specifications(num_species=5, num_regulations=8, random_seed=42)
model = spec.generate_network("my_network")
print(model.get_antimony_model())
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
13 14 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 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 | |
__str__() -> str
¶
String representation of the specification.
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
478 479 480 481 | |
add_drug(drug: Drug, value: Optional[float] = None)
¶
Add a drug to the model using ModelSpec4's mechanism.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
drug
|
Drug
|
Drug object containing name, start_time, default_value, and regulations |
required |
value
|
Optional[float]
|
Optional override for drug value |
None
|
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
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 | |
add_regulation(from_specie: str, to_specie: str, reg_type: str, is_feedback: bool = False)
¶
Add regulation between species.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
from_specie
|
str
|
Regulating species |
required |
to_specie
|
str
|
Regulated species |
required |
reg_type
|
str
|
'up' or 'down' |
required |
is_feedback
|
bool
|
Whether this is a feedback regulation |
False
|
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 | |
add_species(species: str, group: str = 'default')
¶
Add species to the model.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
species
|
str
|
Name of the species |
required |
group
|
str
|
Optional group name for categorization |
'default'
|
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
45 46 47 48 49 50 51 52 53 54 55 56 57 58 | |
clear_drugs()
¶
Remove all drugs and their associated regulations.
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 | |
generate_forward_archtype_and_regulators(specie: str) -> Tuple[ReactionArchtype, List[str]]
¶
Generate forward reaction archtype and regulators for a species. Direct copy from ModelSpec4.
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 | |
generate_forward_archtype_and_regulators_basal(specie: str) -> Tuple[ReactionArchtype, List[str]]
¶
Generate forward reaction archtype with basal activation. Direct copy from ModelSpec4.
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 | |
generate_network(network_name: str, mean_range_species: Tuple[int, int] = (1, 100), rangeScale_params: Tuple[float, float] = (0.5, 2.0), rangeMultiplier_params: Tuple[float, float] = (0.8, 1.2), random_seed: Optional[int] = None, receptor_basal_activation: bool = False, **kwargs) -> ModelBuilder
¶
Generate ModelBuilder using Michaelis-Menten reaction scheme.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
network_name
|
str
|
Name of the network |
required |
mean_range_species
|
Tuple[int, int]
|
Range for initial species values |
(1, 100)
|
rangeScale_params
|
Tuple[float, float]
|
Range for parameter scaling |
(0.5, 2.0)
|
rangeMultiplier_params
|
Tuple[float, float]
|
Range for parameter multiplier |
(0.8, 1.2)
|
random_seed
|
Optional[int]
|
Random seed for reproducibility |
None
|
receptor_basal_activation
|
bool
|
Whether to use basal activation for all species |
False
|
Returns:
| Type | Description |
|---|---|
ModelBuilder
|
Pre-compiled ModelBuilder object |
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 | |
generate_random_parameters(reaction_archtype: ReactionArchtype, scale_range: Tuple[float, float], multiplier_range: Tuple[float, float], random_seed: Optional[int] = None) -> Tuple
¶
Generate random parameters informed by scale. Direct copy from ModelSpec4.
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 | |
generate_reverse_archtype_and_regulators(specie: str) -> Tuple[ReactionArchtype, List[str]]
¶
Generate reverse reaction archtype and regulators. Direct copy from ModelSpec4.
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 | |
generate_specifications(num_species: Optional[int] = None, num_regulations: Optional[int] = None, species_names: Optional[List[str]] = None, regulation_list: Optional[List[Tuple[str, str, str]]] = None, random_seed: Optional[int] = None, **kwargs)
¶
Generate network specifications.
Can generate random network or use provided species/regulations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
num_species
|
Optional[int]
|
Number of species for random generation |
None
|
num_regulations
|
Optional[int]
|
Number of regulations for random generation |
None
|
species_names
|
Optional[List[str]]
|
List of species names for manual specification |
None
|
regulation_list
|
Optional[List[Tuple[str, str, str]]]
|
List of (from_specie, to_specie, reg_type) tuples |
None
|
random_seed
|
Optional[int]
|
Random seed for reproducibility |
None
|
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 | |
get_all_species(include_drugs: bool = True, include_default: bool = True) -> List[str]
¶
Get all species in the model.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
include_drugs
|
bool
|
Whether to include drug species |
True
|
include_default
|
bool
|
Whether to include non-drug species |
True
|
Returns:
| Type | Description |
|---|---|
List[str]
|
List of species names |
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 | |
get_forward_reaction(specie: str, mean_range_species: Tuple[int, int], rangeScale_params: Tuple[float, float], rangeMultiplier_params: Tuple[float, float], rng: np.random.Generator, basal: bool = False) -> Reaction
¶
Create forward reaction for a species. Adapted from ModelSpec4.
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 | |
get_regulators_for_species(specie: str) -> List[Tuple[str, str]]
¶
Get all regulators for a species.
Returns:
| Type | Description |
|---|---|
List[Tuple[str, str]]
|
List of (regulator_name, reg_type) tuples |
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
143 144 145 146 147 148 149 150 151 152 153 154 | |
get_reverse_reaction(specie: str, rangeScale_params: Tuple[float, float], rangeMultiplier_params: Tuple[float, float], rng: np.random.Generator) -> Reaction
¶
Create reverse reaction for a species. Adapted from ModelSpec4.
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 | |
get_species_by_group(group: str) -> List[str]
¶
Get all species in a specific group.
Source code in src/synthetic/Specs/MichaelisNetworkSpec.py
60 61 62 | |
synthetic.Specs.Drug.Drug
¶
Source code in src/synthetic/Specs/Drug.py
1 2 3 4 5 6 7 8 9 10 11 12 13 14 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 | |
__init__(name, start_time, default_value, regulation=None, regulation_type=None)
¶
A drug class that represents a drug that can be applied to a model. Input: name: str | The name of the drug start_time: int | The time at which the drug is applied to the model. default_value: float | The default value of the drug in the model regulation: List[str] | The list of species that the drug regulates regulation_type: List[str] | The type of regulation that the drug has on the species, either 'up' or 'down'
Source code in src/synthetic/Specs/Drug.py
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | |
add_regulation(specie, type)
¶
Adds a regulation to the drug. Input: specie: str | The name of the specie to regulate type: str | The type of regulation, either 'up' or 'down'
Source code in src/synthetic/Specs/Drug.py
26 27 28 29 30 31 32 33 34 | |
add_regulations(species, types)
¶
Adds multiple regulations to the drug. Input: species: List[str] | The list of species to regulate types: List[str] | The list of types of regulation, either 'up' or 'down'
Source code in src/synthetic/Specs/Drug.py
36 37 38 39 40 41 42 43 44 45 | |
print_regulation()
¶
Prints the regulation of the drug.
Source code in src/synthetic/Specs/Drug.py
47 48 49 50 51 52 | |
synthetic.Specs.Regulation.Regulation
dataclass
¶
Class to store the regulation information
Source code in src/synthetic/Specs/Regulation.py
3 4 5 6 7 8 | |
Solvers¶
ODE simulation backends. Both concrete solvers inherit from the abstract Solver base class, which defines the compile() and simulate() interface. See Solving ODEs for usage.
synthetic.Solver.ScipySolver.ScipySolver
¶
Bases: Solver
Solver using scipy to solve the ODEs.
Source code in src/synthetic/Solver/ScipySolver.py
13 14 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 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 | |
compile(compile_str: str, **kwargs) -> None
¶
Compile the model from an Antimony string and generate ODE function. Assignment rule variables are treated like pseudo-parameters with time-based value changes during simulation.
Source code in src/synthetic/Solver/ScipySolver.py
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 | |
simulate(start: float, stop: float, step: float) -> pd.DataFrame
¶
Simulate the ODE system from start to stop with a given step size. Handles piecewise assignment rule changes at change-points.
Source code in src/synthetic/Solver/ScipySolver.py
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 | |
set_state_values(state_values: Dict[str, float]) -> bool
¶
Hot swapping of state variables in the running instance of the model, note this is setting the initial values of the state variables. Set the values of state variables in the model instance, this should only possible after compiling the model. Not every solver will support this, so it is possible that this function to return an not implemented error. returns True if the state variable was set successfully, False otherwise.
Source code in src/synthetic/Solver/ScipySolver.py
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 | |
set_parameter_values(parameter_values: Dict[str, float]) -> bool
¶
Hot swapping of parameters in the running instance of the model. Set the values of parameter variables in the model instance, this should only possible after compiling the model. Not every solver will support this, so it is possible that this function to return an not implemented error. returns True if the state variable was set successfully, False otherwise.
Source code in src/synthetic/Solver/ScipySolver.py
154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 | |
synthetic.Solver.RoadrunnerSolver.RoadrunnerSolver
¶
Bases: Solver
RoadRunner-based ODE solver for biochemical models.
This solver uses the libRoadRunner library to compile and simulate biochemical models defined in Antimony or SBML formats. It provides an interface for setting initial states and parameters, and returns simulation results as pandas DataFrames.
Inherits from
Solver: Abstract base class for ODE solvers
Source code in src/synthetic/Solver/RoadrunnerSolver.py
7 8 9 10 11 12 13 14 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 | |
compile(compile_str: str, **kwargs)
¶
Compile a model string using libRoadRunner.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
compile_str
|
str
|
Model definition in Antimony or SBML format |
required |
**kwargs
|
Additional options passed to RoadRunner constructor |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
RoadRunner |
The compiled RoadRunner instance |
Source code in src/synthetic/Solver/RoadrunnerSolver.py
25 26 27 28 29 30 31 32 33 34 35 36 37 | |
simulate(start: float, stop: float, step: float) -> pd.DataFrame
¶
Simulate the problem from start to stop with a given step size. Returns a pandas dataframe with the results with the following columns: - time: time points of the simulation - [species]: species names with each row corresponds to a time point and each column corresponds to a species.
Source code in src/synthetic/Solver/RoadrunnerSolver.py
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 | |
set_state_values(state_values: Dict[str, float]) -> bool
¶
Hot swapping of state variables in the running instance of the model, note this is setting the initial values of the state variables. Set the values of state variables in the model instance, this should only possible after compiling the model. Not every solver will support this, so it is possible that this function to return an not implemented error. returns True if the state variable was set successfully, False otherwise.
Source code in src/synthetic/Solver/RoadrunnerSolver.py
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 | |
set_parameter_values(parameter_values: Dict[str, float]) -> bool
¶
Hot swapping of parameters in the running instance of the model. Set the values of parameter variables in the model instance, this should only possible after compiling the model. Not every solver will support this, so it is possible that this function to return an not implemented error. returns True if the state variable was set successfully, False otherwise.
Source code in src/synthetic/Solver/RoadrunnerSolver.py
112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 | |
Utilities¶
Helpers for parameter tuning, feature generation, and dataset creation. See Obtaining Data, Advanced, and Use Cases for context.
synthetic.utils.kinetic_tuner.KineticParameterTuner
¶
Generate kinetic parameters that achieve target active percentage ranges.
This tuner solves the full nonlinear kinetic equations to ensure that each species reaches a specified active percentage at steady state, enabling robust signal propagation through multi-degree networks.
Attributes:
| Name | Type | Description |
|---|---|---|
model |
The ModelBuilder object containing the network structure |
|
rng |
numpy random number generator for reproducibility |
Source code in src/synthetic/utils/kinetic_tuner.py
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 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 | |
generate_parameters(active_percentage_range: Tuple[float, float] = (0.3, 0.7), X_total_multiplier: float = 5.0, ki_val: float = 100.0, v_max_f_random_range: Tuple[float, float] = (5.0, 10.0)) -> Dict[str, float]
¶
Generate kinetic parameters to achieve target active percentages.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
active_percentage_range
|
Tuple[float, float]
|
Range for target active percentages (e.g., (0.3, 0.7)) |
(0.3, 0.7)
|
X_total_multiplier
|
float
|
Multiplier for setting km_b = X_total × multiplier |
5.0
|
ki_val
|
float
|
Constant value for all inhibition constants Ki |
100.0
|
v_max_f_random_range
|
Tuple[float, float]
|
Range for total forward vmax (Σ kc_i × [Y_i_a]) |
(5.0, 10.0)
|
Returns:
| Type | Description |
|---|---|
Dict[str, float]
|
Dictionary mapping parameter names to tuned values |
Raises:
| Type | Description |
|---|---|
ValueError
|
If target active percentages cannot be achieved |
RuntimeError
|
If parameter structure doesn't match expected pattern |
Source code in src/synthetic/utils/kinetic_tuner.py
138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 | |
get_target_concentrations() -> Dict[str, float]
¶
Get the target active concentrations for all species.
Returns:
| Type | Description |
|---|---|
Dict[str, float]
|
Dictionary mapping active state names to target concentrations |
Source code in src/synthetic/utils/kinetic_tuner.py
496 497 498 499 500 501 502 503 | |
synthetic.utils.make_feature_data.make_feature_data(initial_values: Dict[str, float], perturbation_type: str, perturbation_params: Dict[str, Any], n_samples: int, seed: Optional[int] = None) -> pd.DataFrame
¶
Generate feature data using specified perturbation type.
This function provides a unified interface for generating feature data using the enhanced perturbation functions from PerturbationUtils.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
initial_values
|
Dict[str, float]
|
Dictionary mapping parameter names to initial values |
required |
perturbation_type
|
str
|
Type of perturbation ('uniform', 'gaussian', 'lognormal', 'lhs', 'conserve_rules') |
required |
perturbation_params
|
Dict[str, Any]
|
Parameters for the perturbation distribution |
required |
n_samples
|
int
|
Number of samples to generate |
required |
seed
|
Optional[int]
|
Random seed for reproducibility |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame with shape (n_samples, n_parameters) |
Raises:
| Type | Description |
|---|---|
ValueError
|
If parameters are invalid or unsupported perturbation type |
Examples:
>>> initial_values = {'A': 10.0, 'B': 20.0}
>>> params = {'std': 2.0}
>>> df = make_feature_data(initial_values, 'gaussian', params, n_samples=100, seed=42)
Source code in src/synthetic/utils/make_feature_data.py
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 | |
synthetic.utils.make_target_data.make_target_data_with_params(solver: Solver, feature_df: pd.DataFrame, parameter_df: pd.DataFrame = None, simulation_params: Dict[str, Any] = None, n_cores: int = 1, outcome_var: str = 'Cp', capture_all_species: bool = False, verbose: bool = False, target_method: str = 'last_point') -> Tuple[pd.DataFrame, Union[List[np.ndarray], pd.DataFrame]]
¶
Generate target data with optional kinetic parameter perturbation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
solver
|
Solver
|
Solver object (ScipySolver or RoadrunnerSolver) - can load any SBML/Antimony model |
required |
feature_df
|
DataFrame
|
DataFrame of perturbed initial values |
required |
parameter_df
|
DataFrame
|
DataFrame of perturbed kinetic parameters (optional) |
None
|
simulation_params
|
Dict[str, Any]
|
Dictionary with 'start', 'end', 'points' keys |
None
|
n_cores
|
int
|
Number of cores for parallel processing (-1 for all cores) |
1
|
outcome_var
|
str
|
Variable to extract as target |
'Cp'
|
capture_all_species
|
bool
|
If True, returns DataFrame with timecourses for all species. If False, returns list of arrays for outcome_var only. |
False
|
verbose
|
bool
|
Whether to show progress bar |
False
|
target_method
|
str
|
Method for calculating target values ('last_point' or 'fold_change_drug'). 'last_point' (default) returns last time point value. 'fold_change_drug' returns fold change from drug start to end time. |
'last_point'
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
Tuple of (target_df, time_course_data) |
Union[List[ndarray], DataFrame]
|
time_course_data is either List[np.ndarray] (if capture_all_species=False) |
Tuple[DataFrame, Union[List[ndarray], DataFrame]]
|
or pd.DataFrame (if capture_all_species=True) |
Source code in src/synthetic/utils/make_target_data.py
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 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 | |
synthetic.utils.make_target_data.calculate_targets_from_timecourse(timecourse_data: Union[pd.DataFrame, List[np.ndarray]], outcome_var: str, target_method: str = 'last_point', simulation_params: Optional[Dict[str, Any]] = None, drug_start_time: Optional[float] = None) -> pd.DataFrame
¶
Calculate target values from timecourse data.
This is the target generation component that processes timecourse arrays to generate target values using specified methods.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
timecourse_data
|
Union[DataFrame, List[ndarray]]
|
Timecourse data (DataFrame with species columns or list of outcome arrays) |
required |
outcome_var
|
str
|
Variable to extract as target |
required |
target_method
|
str
|
Method for calculating targets ('last_point' or 'fold_change_drug') |
'last_point'
|
simulation_params
|
Optional[Dict[str, Any]]
|
Simulation parameters (required for fold_change_drug) |
None
|
drug_start_time
|
Optional[float]
|
Drug start time (required for fold_change_drug) |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame with single column containing target values |
Raises:
| Type | Description |
|---|---|
ValueError
|
If target_method is invalid or required parameters missing |
Examples:
>>> timecourse_df = pd.DataFrame({
... 'Cp': [np.array([1, 2, 3]), np.array([4, 5, 6])],
... 'Oa': [np.array([0.5, 1.0, 1.5]), np.array([2.0, 2.5, 3.0])]
... })
>>> targets = calculate_targets_from_timecourse(
... timecourse_df, 'Cp', target_method='last_point'
... )
>>> targets
Cp
0 3.0
1 6.0
Source code in src/synthetic/utils/make_target_data.py
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 | |