Quick Start¶
This page shows the fastest path to a usable dataset. The pattern: describe a network, simulate it many times with perturbed parameters, return the results in scikit-learn's (X, y) shape.
The library covers four capabilities — model building, solving ODEs, obtaining data, and using the data — each in its own section. This page uses the simplest entry to each: Builder.specify(degree_cascades=...) for the model, make_dataset_drug_response for the data. The other paths are covered in the Usage section; you can ignore them until you need them.
Your First Dataset¶
from synthetic import Builder, make_dataset_drug_response
vc = Builder.specify(degree_cascades=[3, 5], random_seed=42)
X, y = make_dataset_drug_response(n=1000, cell_model=vc, target_specie='Oa')
print(f"Feature matrix shape: {X.shape}") # (1000, n_features)
print(f"Target vector shape: {y.shape}") # (1000,)
Two things happened:
Builder.specify(degree_cascades=[3, 5])created a virtual cell. The[3, 5]argument defines a hierarchical network with 3 cascades at the first level and 5 at the second. A drug that targets the top-level receptors was created automatically.make_dataset_drug_response(n=1000, ...)simulated that virtual cell 1000 times, perturbing initial conditions and kinetic parameters each time. It returned a scikit-learn-compatible feature matrixX(one column per species) and a target vectory(the value of theOaspecies — the activated outcome — in each simulation).
You don't need to know what any of that means yet. Next: Model Building explains the network Builder.specify created and how to configure it (or swap in a different model-building path).
Customizing Your Model¶
Three knobs you'll reach for most often:
from synthetic import Builder, make_dataset_drug_response
# Bigger network (more degrees of regulation)
vc = Builder.specify(degree_cascades=[3, 6, 15, 25], random_seed=42)
# Reproducibility — same seed, same network
vc = Builder.specify(degree_cascades=[3, 5], random_seed=42)
# Speed up large sweeps with all CPUs
X, y = make_dataset_drug_response(n=10_000, cell_model=vc, n_cores=-1, verbose=True)
The rest of this page assumes you have a compiled vc ready to query.
What You Got¶
print(vc.get_species_names()) # All species, e.g. ['R1_1', 'R1_1a', ...]
print(vc.get_initial_values()) # Initial concentrations
print(X.columns.tolist()) # Feature columns match species names
Xis apandas.DataFrameof species concentrations — one column per species, one row per simulated sample.yis apandas.Seriesof theOaoutcome value, one per row ofX.- The two are aligned:
X.iloc[i]andy.iloc[i]come from the same simulation.
That's enough to drop the result into any scikit-learn workflow:
from sklearn.ensemble import RandomForestRegressor
from sklearn.model_selection import train_test_split
X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=0)
model = RandomForestRegressor(random_state=0).fit(X_train, y_train)
print(model.score(X_test, y_test))
The Other Paths¶
Builder.specify(degree_cascades=...) only produces hierarchical Michaelis-Menten networks. If that shape is wrong for your problem — or you want to control the network more directly — the other paths into Model Building are:
- The spec classes (
DegreeInteractionSpecdirectly, orMichaelisNetworkSpecfor non-hierarchical Michaelis-Menten networks). Both expose species, regulations, and drugs as code objects you can manipulate. See Model Building § The spec classes. - The
ModelBuilderAPI for arbitrary models — different kinetics, custom rate laws, hand-written reactions. See Model Building §ModelBuilder+Reaction. - Customising any layer of the pipeline — writing your own spec, your own rate equation, your own solver. See Advanced.