1. AstroLogics Tutorial, Boolean Network Analysis and Clustering : Bonesis Tutorial

This tutorial demonstrates the AstroLogics framework for analyzing and comparing Boolean network model ensembles. AstroLogics is designed for benchmarking Boolean models through three major evaluation criteria: network evaluation, logical function evaluation, and dynamic evaluation.

1.1. Overview of AstroLogics Framework

AstroLogics addresses a critical gap in Boolean network modeling: while multiple methods exist for Boolean model synthesis (like Bonesis, BN-sketch), there hasn’t been a standardized way to evaluate and compare generated model ensembles. The framework focuses on:

• Dynamic properties: Examining state transition graphs and model behaviors through simulation

• Logical function evaluation: Analyzing and comparing logical rules that govern node behaviors

• Model clustering: Identifying groups of models with similar dynamics and logical features

1.2. Required Libraries

import pandas as pd
import os
import astrologics as ast
import seaborn as sns
import matplotlib.pyplot as plt

1.2.1. Dataset: CNS Differentiation Model

We’ll use the Central Nervous System (CNS) differentiation model from Qiu et al., 2017, which serves as the tutorial network for Bonesis. This model contains 12 nodes with moderate connectivity and demonstrates key concepts of cellular decision-making processes.

For more details on the Bonesis network and inferences, please checkout this link

1.3. Step 1: Load Model Ensemble

# Load the model path and create AstroLogics object
model_path = '../models/test_bonesis/'
model = ast.ensemble(model_path, project_name = 'test_bonesis')
model.create_simulation()

Simulation object created

The ensemble object is the core component of AstroLogics that handles:

• Loading multiple Boolean network models from a directory

• Managing simulation parameters and configurations

• Coordinating analysis across the model ensemble

1.4. Step 2: Simulate the model ensemble

In this part of the script we first simulate all the BN within the model ensemble. We utilize the MaBoSS engine as the main simulator.

This creates an initial state where all nodes have equal probability (0.5) of being active. This represents a neutral starting condition that allows the system to evolve according to its inherent dynamics.

We then start the simulation using MaBoSS.

MaBoSS (Markovian Boolean Stochastic Simulator) is crucial for the AstroLogics approach because:

• It converts Boolean network dynamics into continuous-time Markov processes

• Provides probabilistic approximation of complex state transition graphs

• Enables analysis of both transient and steady-state behaviors

• Scales computationally better than exhaustive state space exploration

# Configure simulation parameters
model.simulation.update_parameters(max_time = 15, sample_count = 1000)
model.simulation.run_simulation()

Start simulation

Simulation completed

1.5. Step 3 (Optional) : Trajectory visualization

In this steps the simulation trajectories of BNs in the model ensemble can be visualized using PCA. The method allows for a global view of the dynamics of all the models within the model ensembles perform, and may give insight to how the model can potentially be clustered.

model.create_trajectory()
model.trajectory.pca_trajectory()
model.trajectory.plot_pca_trajectory(color = 'timepoint')

Trajectory object created

1.6. Step 4: Calculate Distance Matrix

This step is fundamental to the AstroLogics methodology:

• Distance calculation: Compares models based on their endpoint activation probabilities

• Euclidean distance: Measures similarity in the final state distributions

• Model comparison: Enables identification of models with similar dynamics

In this function calculate_distancematrix, users can select the two options of data used to calculate the distance.

• endpoint : The endpoint utilize the node activation probability at the endpoint of MaBoSS simulation. User could also defines the timepoint to define a specific timepoint they want to use to define the distance

• trajectory : This options utilize the whole MaBoSS simulation trajectory and the dtw method to calculate the distances between models.

model.trajectory.calculate_distancematrix(mode = 'endpoint')

Calculating distance matrix for endpoint simulation...
Distance matrix calculated successfully.

model.trajectory.distance_matrix

model_id	bn56	bn6	bn62	bn61	bn2	bn19	bn77	bn40	bn24	bn63	bn67	bn10	bn4	bn48	bn87	bn55	bn82	bn18	bn20	bn26	bn1	bn22	bn72	bn69	bn31	bn42	bn21	bn3	bn45	bn86	bn16	bn36	bn30	bn9	bn76	bn65	bn68	bn78	bn75	bn37	bn33	bn60	bn79	bn73	bn71	bn47	bn44	bn39	bn32	bn35	bn59	bn43	bn17	bn0	bn46	bn53	bn50	bn13	bn74	bn83	bn49	bn25	bn11	bn81	bn23	bn38	bn85	bn28	bn5	bn51	bn34	bn80	bn54	bn27	bn12	bn8	bn58	bn57	bn70	bn7	bn64	bn84	bn41	bn15	bn66	bn52	bn14	bn29
model_id
bn56	0.000000	0.094657	0.092763	0.026702	0.136239	0.131628	0.048847	0.039962	0.135237	0.008367	0.036606	0.149274	0.050725	0.111382	0.170206	0.063547	0.142709	0.029580	0.124451	0.039459	0.042661	0.129677	0.132469	0.049437	0.017088	0.043405	0.143878	0.129861	0.102299	0.131609	0.143767	0.024269	0.040485	0.021656	0.147245	0.136839	0.132659	0.080529	0.062586	0.134677	0.043081	0.157886	0.132416	0.036069	0.074967	0.013892	0.026476	0.061814	0.060283	0.077006	0.051682	0.082006	0.062674	0.030610	0.051186	0.159518	0.031225	0.055344	0.143492	0.065131	0.070626	0.024718	0.127957	0.112783	0.051662	0.016643	0.142751	0.149660	0.021656	0.006403	0.057541	0.117337	0.041085	0.133210	0.020248	0.128410	0.079824	0.071777	0.031113	0.121742	0.125395	0.141810	0.042720	0.029682	0.136960	0.120657	0.126044	0.018028
bn6	0.094657	0.000000	0.052355	0.076870	0.154987	0.163218	0.066393	0.089828	0.140801	0.091082	0.101784	0.162685	0.075200	0.146935	0.158341	0.067955	0.144118	0.085820	0.141506	0.080081	0.102255	0.141492	0.155551	0.104575	0.097908	0.103325	0.171339	0.151618	0.157775	0.139259	0.138611	0.078006	0.060506	0.090006	0.142741	0.139302	0.161256	0.064630	0.035511	0.156064	0.070739	0.142099	0.134833	0.065856	0.061319	0.085913	0.079831	0.064722	0.089956	0.114018	0.073410	0.097360	0.090089	0.082771	0.059933	0.152079	0.065307	0.082735	0.140528	0.118979	0.069742	0.091198	0.160459	0.152105	0.051990	0.085843	0.167312	0.151809	0.094557	0.088346	0.092978	0.149305	0.118659	0.152686	0.086603	0.176830	0.087882	0.057519	0.072402	0.155052	0.142246	0.150579	0.078006	0.074719	0.149706	0.141972	0.138539	0.099825
bn62	0.092763	0.052355	0.000000	0.088544	0.147404	0.168621	0.046723	0.107033	0.134937	0.087607	0.113477	0.167660	0.063277	0.143182	0.140118	0.053494	0.147299	0.100110	0.141594	0.093808	0.085586	0.142622	0.139603	0.101376	0.104062	0.079981	0.174711	0.151053	0.150107	0.132174	0.139011	0.077974	0.065894	0.079950	0.135963	0.125491	0.157228	0.020000	0.057480	0.155354	0.057697	0.132654	0.129619	0.060332	0.069203	0.079574	0.070200	0.033823	0.062538	0.120843	0.072760	0.076551	0.109073	0.069166	0.064846	0.151839	0.065345	0.075326	0.130027	0.113662	0.084882	0.076223	0.160692	0.148287	0.042521	0.093038	0.165512	0.154237	0.087932	0.087932	0.108821	0.151806	0.121939	0.160686	0.095870	0.171453	0.044849	0.061422	0.078619	0.142373	0.132329	0.149937	0.063561	0.078664	0.150150	0.139675	0.126357	0.097673
bn61	0.026702	0.076870	0.088544	0.000000	0.136880	0.130457	0.050249	0.021166	0.134462	0.029069	0.028373	0.144781	0.048642	0.116090	0.169514	0.058696	0.138611	0.011832	0.124455	0.019494	0.054452	0.128285	0.136795	0.050090	0.023979	0.060241	0.141789	0.129248	0.113649	0.131765	0.140428	0.020976	0.034409	0.040050	0.145024	0.138188	0.133664	0.080821	0.043589	0.133600	0.043046	0.155348	0.133083	0.037148	0.059641	0.028914	0.033466	0.064094	0.067119	0.068418	0.042521	0.082012	0.043600	0.039623	0.037376	0.154328	0.028071	0.051342	0.142832	0.067119	0.052202	0.042895	0.128561	0.117427	0.047265	0.013711	0.141892	0.144959	0.033526	0.021633	0.040841	0.120004	0.045837	0.130323	0.014457	0.133581	0.086439	0.057976	0.028054	0.127271	0.127754	0.138986	0.045255	0.029833	0.134577	0.121996	0.128825	0.037523
bn2	0.136239	0.154987	0.147404	0.136880	0.000000	0.055848	0.130847	0.140399	0.038158	0.137379	0.138928	0.040816	0.125451	0.060638	0.069014	0.127196	0.052583	0.140627	0.057836	0.133940	0.126067	0.055290	0.025159	0.126921	0.141743	0.129418	0.045255	0.029950	0.085814	0.041012	0.065970	0.129892	0.142702	0.138434	0.044855	0.048332	0.021895	0.139929	0.138982	0.024104	0.127644	0.068272	0.079969	0.138145	0.131533	0.133041	0.129368	0.136191	0.126890	0.134093	0.126285	0.126941	0.137423	0.128553	0.129325	0.046530	0.136733	0.124611	0.048052	0.128767	0.132744	0.132981	0.038833	0.051352	0.136667	0.139040	0.027835	0.039154	0.129012	0.135425	0.135647	0.083096	0.137015	0.067171	0.140787	0.055172	0.136069	0.130813	0.143412	0.027092	0.032450	0.026926	0.126238	0.143269	0.030643	0.051990	0.044632	0.143861
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
bn15	0.029682	0.074719	0.078664	0.029833	0.143269	0.138597	0.046098	0.049193	0.134507	0.023516	0.054452	0.154189	0.058481	0.114652	0.170238	0.066495	0.139989	0.035496	0.122813	0.048642	0.063032	0.127495	0.140950	0.071589	0.032326	0.059791	0.153525	0.134689	0.109663	0.130668	0.137470	0.035553	0.014832	0.024698	0.145293	0.135359	0.142341	0.071694	0.049699	0.141028	0.046893	0.152299	0.124262	0.019799	0.076217	0.027893	0.036056	0.053423	0.069462	0.095692	0.060033	0.093188	0.072959	0.041231	0.052202	0.158710	0.017205	0.067231	0.141283	0.088685	0.074867	0.036222	0.136638	0.119712	0.037630	0.024083	0.152609	0.150389	0.044944	0.025729	0.070370	0.116237	0.067491	0.133199	0.025159	0.144478	0.079784	0.071681	0.003606	0.131643	0.127675	0.144364	0.051245	0.000000	0.139574	0.120818	0.125889	0.026192
bn66	0.136960	0.149706	0.150150	0.134577	0.030643	0.040200	0.135226	0.137495	0.027946	0.137586	0.138224	0.026020	0.132473	0.049193	0.082316	0.134427	0.025612	0.137190	0.036166	0.133488	0.135831	0.030984	0.052421	0.135122	0.139592	0.138809	0.042415	0.014071	0.081086	0.031828	0.044621	0.131958	0.138899	0.139366	0.039560	0.049950	0.033832	0.145386	0.136422	0.017720	0.132710	0.063372	0.063750	0.137248	0.135698	0.134993	0.133120	0.140239	0.137644	0.141669	0.131594	0.140787	0.137579	0.133645	0.131765	0.037014	0.135473	0.132699	0.046368	0.139950	0.135300	0.137029	0.033302	0.044632	0.136971	0.136766	0.038598	0.018655	0.133839	0.135687	0.136678	0.063750	0.140656	0.039987	0.137703	0.067164	0.146268	0.135063	0.139305	0.047043	0.032894	0.010198	0.132752	0.139574	0.000000	0.034467	0.043370	0.142418
bn52	0.120657	0.141972	0.139675	0.121996	0.051990	0.047202	0.123053	0.127863	0.032879	0.119975	0.128507	0.057189	0.125543	0.020976	0.096602	0.129127	0.034583	0.124294	0.009165	0.125758	0.126309	0.015492	0.062450	0.130606	0.123248	0.125650	0.065445	0.031081	0.054213	0.029479	0.039937	0.120503	0.121626	0.120179	0.051430	0.048857	0.052975	0.134183	0.128121	0.042732	0.122458	0.068819	0.040645	0.120237	0.135167	0.119378	0.119987	0.126614	0.129097	0.144021	0.126811	0.140061	0.135558	0.120768	0.125419	0.062944	0.119721	0.128612	0.051517	0.138311	0.135122	0.120487	0.044418	0.028983	0.123179	0.121281	0.064481	0.048990	0.121873	0.119962	0.133795	0.034409	0.131666	0.033630	0.122090	0.075013	0.135626	0.132966	0.121054	0.050725	0.029631	0.042379	0.123138	0.120818	0.034467	0.000000	0.033541	0.122242
bn14	0.126044	0.138539	0.126357	0.128825	0.044632	0.072367	0.116503	0.138007	0.020736	0.124503	0.138560	0.068720	0.119933	0.046336	0.067565	0.120854	0.044215	0.133881	0.038223	0.131894	0.122438	0.037908	0.044328	0.131328	0.132729	0.120071	0.079347	0.045067	0.072139	0.014967	0.041085	0.122417	0.124226	0.121951	0.032894	0.017889	0.057879	0.120706	0.127640	0.051894	0.117699	0.046271	0.040608	0.120025	0.130733	0.121310	0.118819	0.117252	0.118849	0.146714	0.124290	0.128406	0.142411	0.118119	0.123673	0.055145	0.121128	0.124113	0.026249	0.137975	0.135022	0.119398	0.061595	0.050408	0.118979	0.128942	0.068984	0.052106	0.123377	0.124900	0.140499	0.064846	0.139961	0.064529	0.130740	0.084404	0.120250	0.127550	0.126448	0.044045	0.013601	0.044079	0.118203	0.125889	0.043370	0.033541	0.000000	0.129198
bn29	0.018028	0.099825	0.097673	0.037523	0.143861	0.136202	0.057801	0.051108	0.139442	0.014318	0.049244	0.156298	0.065559	0.111897	0.177637	0.077209	0.146154	0.038210	0.125511	0.054148	0.057489	0.131457	0.140118	0.067298	0.021610	0.053563	0.151578	0.135163	0.099900	0.135226	0.145547	0.040050	0.040299	0.020100	0.152302	0.140855	0.140243	0.086487	0.071358	0.141255	0.055687	0.161904	0.131069	0.038158	0.089805	0.025846	0.039446	0.067201	0.072450	0.094578	0.067941	0.097417	0.077801	0.043151	0.065307	0.166015	0.036056	0.072028	0.148003	0.082565	0.086215	0.031875	0.133821	0.115434	0.057044	0.024331	0.151315	0.155670	0.038781	0.020881	0.073185	0.114861	0.054891	0.134907	0.025788	0.136103	0.087275	0.085957	0.028688	0.128320	0.129650	0.148003	0.056569	0.026192	0.142418	0.122242	0.129198	0.000000

88 rows × 88 columns

1.7. Step 5: Dimensionality Reduction and Visualization

Multidimensional Scaling (MDS) projects the high-dimensional distance matrix onto a 2D plane, preserving relative distances between models. This visualization reveals:

• Model clusters: Groups of models with similar dynamics

• Outliers: Models with unique behavioral patterns

• Gradient patterns: Continuous transitions between model types

# Perform MDS (Multidimensional Scaling) for visualization
model.trajectory.calculate_MDS()
model.trajectory.plot_MDS(s = 100, fig_size = (8,8))

1.8. Step 6: Model Clustering

Clustering reveals distinct groups within the model ensemble. In the CNS differentiation example, we found 2 major clusters corresponding to different attractor groups, representing distinct cellular fate decisions.

model.trajectory.calculate_kmean_cluster(n_cluster = 2,
                              random_state = 0)

Calculated k-means clustering with 2 clusters.

model.trajectory.plot_MDS(s = 100, fig_size = (8,8),plot_cluster = True)

1.9. Step 7 (Optional) : Trajectory Analysis

In this step, we projected the calculated clusters onto the trajectory PCA in the step 3.

model.trajectory.plot_pca_trajectory(plot_cluster=True)

1.10. Step 8: Logic Function Analysis

This step implements the logical function evaluation component of AstroLogics:

• Converts Boolean equations to Disjunctive Normal Form (DNF)

• Creates feature matrices comparing logical rules across models

• Identifies constant, varied, and marker clauses

model.create_logic()
model.logic.model_logic
model.logic.create_flattend_logic_clause()

Loading models logics

Concatenate results into matrix

Logic object created
Flatten models logic clauses

Concatenate results into matrix

Flattend logic clause created

1.11. Step 9 : Calculate statistic of Logic features (clauses)

In this steps, we have already featurized the logical equations into model logics or clauses.

We can then integrate the clusters obtained from the trajectory analysis into the .logic and perform chi-square statistical test to categorize logic features (clauses) into 3 major groups

• Constatnt : core regulatory features that appears across BNs in the model ensemble

• Varied : Features that may differ between individual BNs but show no statistical significant

• Marker : Key discriminatory features that statistically distinguish between different model clusters.

We can define the p-value of the chi-square test using the function pval_threshold.

model.logic.map_model_clusters(model.trajectory.cluster_dict)
model.logic.calculate_logic_statistic(pval_threshold = 0.0001)

Model clusters mapped to logic clauses

The results of the analysis can be visualized in the form of Manhattan Plot shown below.

model.logic.plot_manhattan()

Or the results can be summarized into the barplot shown here

model.logic.plot_logicstat_summary()

1.12. Step 9: Advanced Trajectory Analysis

These visualizations help identify:

• Most variable nodes: Components showing greatest differences between models

• Critical regulators: Nodes whose activity patterns distinguish model clusters

• Temporal patterns: How specific nodes behave over simulation time

In this first plot, we check what are the features that shows the highest variance in their dynamics accross simulation. We calculate the variance of node activation probabily of all BNs in the model ensemble across all timepoints and plotted using the heatmap.

model.trajectory.plot_trajectory_variance()

We identify the key node of interest (Myt1L) which shows the highest variance along the timepoints. Finally, we could visualize the dynamics of this node between two identified clusters using the lineplot.

model.trajectory.plot_node_trajectory(node = ['Myt1L', 'Tuj1'])

1.13. Step 10: Logic Feature Heatmap

This analysis typically reveals that Myt1L is the key distinguishing node between clusters:

• Cluster 0: Myt1L regulated by Olig2

• Cluster 1: Myt1L deactivated (value = 0)

model.logic.plot_node_logic_heatmap(node = ['Myt1L'],
                                     fig_size = (8, 8))

<Figure size 800x800 with 0 Axes>

1.14. Key Findings and Biological Interpretation

The AstroLogics analysis of the CNS differentiation model reveals:

1.14.1. Dynamic Properties

• Two main clusters representing different developmental pathways

• Distinct attractor landscapes corresponding to different cell fates

• Conserved transient patterns showing robust developmental trajectories

1.14.2. Logical Properties

• Myt1L as key regulator: The primary distinguishing factor between clusters

• Regulatory mechanisms: Different logical rules governing cell fate decisions

• Constant vs. variable features: Core vs. flexible regulatory elements

1.15. Applications and Extensions

1.15.1. Benchmarking Model Synthesis Methods

AstroLogics can compare models generated by different synthesis tools:

• Bonesis vs BN-sketch performance

• Constraint sensitivity analysis

• Solution space characterization

1.15.2. Complex Network Analysis

For larger networks (like the cancer invasion model with 32 nodes):

• Computational advantages: MaBoSS simulation vs. exhaustive attractor calculation

• Scalability: Handling thousands of models efficiently

• Approximation quality: Balancing accuracy with computational feasibility

1.15.3. Transient Dynamics Focus

Unlike methods focusing only on attractors, AstroLogics captures:

• Dynamic Time Warping: Comparing trajectory shapes and timing

• Intervention opportunities: Identifying critical transition points

• Pathway analysis: Understanding how systems reach their endpoints

1.16. Conclusion

This tutorial demonstrates how AstroLogics provides a comprehensive framework for Boolean network ensemble analysis. By combining dynamic simulation with logical feature analysis, it offers insights into both the “what” (final states) and “how” (pathways) of cellular decision-making processes.

The framework addresses the critical need for model evaluation and comparison in an era of increasingly sophisticated Boolean network synthesis methods, supporting the transition from single models to ensemble-based understanding of biological systems.