DOI: 10.5061/dryad.8cz8w9h3d
title: Modeling single-cell heterogeneity in signaling dynamics of macrophages reveals principles of information transmission

description: Macrophages initiate pathogen-appropriate immune responses with the
 activation dynamics of transcription factor NFκB mediating specificity.
 Live-cell imaging revealed the stimulus-response specificity (SRS) of NFκB
 dynamics among heterogeneous populations of cells. To study SRS beyond
 what is experimentally accessible, we developed mathematical model
 simulations that capture the cellular heterogeneity of stimulus-responsive
 NFκB dynamics and the SRS performance of the population. Complementing
 experimental data, extended-dose response simulations improved channel
 capacity estimates. By collapsing parameter distributions, we located
 information loss to receptor modules, while the
 negative-feedback-containing core module showed remarkable signaling
 fidelity. Further, constructing single-cell network models revealed the
 stimulus-response specificity of single cells (scSRS). We found that
 despite SRS limitations at the population level, the majority of single
 cells are capable of responding specifically to immune threats, and that
 the few instances of stimulus-pair confusion are highly uncorrelated. The
 diversity of “blindspots” enable small consortia of macrophages to achieve
 perfect stimulus distinction.
description: # Modeling single-cell heterogeneity in signaling dynamics of macrophages
 reveals principles of information transmission Dataset DOI:
 [10.5061/dryad.8cz8w9h3d](10.5061/dryad.8cz8w9h3d) ## Description of the
 data and file structure This dataset includes single-cell NFkB time
 trajectories processed from live-cell live-cell image tracking of RelA in
 BMDMs, the correpsonding mechanistic model fitted trajectories, and
 generated/sampled new single-cell trajectories, as described in **Guo et
 al. (2025)** "**Modeling single-cell heterogeneity in signaling
 dynamics of macrophages reveals principles of information
 transmission**". The live-cell live-cell image tracking of RelA in
 BMDMs were generated following the protocols of Adelaja, Taylor et al.,
 (2021). **Corresponding author information** ``` Name: Alexander Hoffmann
 ORCID: https://orcid.org/0000-0002-5607-3845 Affiliation: Institute for
 Quantitative and Computational Biosciences & Department of
 Microbiology, Immunology, and Molecular Genetics, University of California
 Los Angeles, Los Angeles, USA email: ahoffmann@ucla.edu ``` **Alternative
 contact information** ``` Name: Xiaolu Guo ORCID:
 https://orcid.org/0000-0002-5740-2428 Affiliation: Institute for
 Quantitative and Computational Biosciences & Department of
 Microbiology, Immunology, and Molecular Genetics, University of California
 Los Angeles, Los Angeles, USA email: gxll@pku.edu.cn ``` **Related
 publication** ``` Xiaolu Guo, Adewunmi Adelaja, Apeksha Singh, Roy
 Wollman, Alexander Hoffmann (ACCEPTED; Feb-2025) Modeling single-cell
 heterogeneity in signaling dynamics of macrophages reveals principles of
 information transmission. Nature Communication ``` **Funding information**
 ``` The work is supported by National Institutes of Health (R01AI173214)
 to A.H. A.S. acknowledges support from the National Institutes of Health
 (NIH), National Institute of General Medical Sciences training grants
 T32GM008185 and T32GM008042. ``` ### Files and variables #### File:
 singaling\_codon\_para\_for\_python.zip **Description:** The file folder
 for data files used for training regression model, inputs 'X' is
 the parameters, outputs 'y' is the signaling codons. (For
 supplementary notes figures) **Naming convention**: When applicable, file
 names follow the pattern `(01)_(02)_(03)_(04).csv`, where: * `(01)`
 denotes the input and output dataset and can be defined as: * `X`: input
 files, parameter values as the inputs for training the machine learning
 classifier * `y`: output files, signaling codons as the output for
 training the machine learning classifier * `(02)` denotes the dataset type
 and can be defined as: * `blank`: data generated from the simulation of
 NFkB trajectories using the mechanistic model parameters inferred from
 experimental data. * `neg_control_unidistr`: synthetic data for negative
 control generated from the uniform distribution of parameters, with the
 corresponding signaling codons. * `(03)` denotes the dataset type and can
 be defined as: * `Duration`: the file are for training machine learning
 classifier on predicting Duration signaling codon using the inferred
 paramters from single cells. * `OscVsNonOsc`: for oscillation signaling
 codon. * `Speed`: for speed signaling codon. * `TotalActivity`: for total
 activity signaling codon. * `EarlyVsLate`: for early vs late signaling
 codon. * `PeakAmplitude`: for speed signaling codon. * `(04)` denotes the
 ligand in the stimuli: * `TNF`: TNF stimulated condition. * `LPS`: LPS
 stimulated condition. * `Pam3CSK4`: Pam3CSK stimulated condition. *
 `PolyIC`: PolyIC stimulated condition. * `CpG`: CpG stimulated condition.
 * `(05)` denotes the dosage of ligand: * `Low`: low dose ligand stimulated
 condition. * `Med`: medium dose ligand stimulated condition. * `High`:
 high dose ligand stimulated condition. Examples:
 `X_Duration_Pam3CSK_Low.csv`: Inputs (parameters) for predicting signaling
 codon "Duration" for "low" dose of "Pam3CSK"
 condition. `X_neg_control_unidistr_Duration_Pam3CSK_Low.csv`: Negative
 control inputs (parameters) generated by sampling from the uniform
 distribution, for predicting signaling codon "Duration" for
 "low" dose of "Pam3CSK" condition. #### File:
 SAEM\_proj\_2023.zip **Description:** The file folder for parameter
 estimation projects to estimate parameter distribution from the various
 ligand stimulated trajectories. Should be run in Monolix software
 ([https://lixoft.com/products/monolix/](https://lixoft.com/products/monolix/)). The files includes the raw rescaled experimental data in monolix required format, and the outcome results of the fitted individual parameters. (for Figure 2) `monolix_projects_description.csv` lists the project information. `read_me.txt` explained the details of the files. **Naming convention**: When applicable, file names follow the pattern `XGESN2024(01)` is the folder for each project, where: * `(01)` denotes the condition index, which is explained in Simulation_recording.xlsx. Under each folder, the corresponding `.mlxtran` file is the project file that can be run in Monolix R2020, to start solving the corresponding NLMEs using SAEM algorithms. (Before running the file, delete the 'results' folder. After running, all the estimation results is saved in the 'results' folder.). `results` file folder saves all the results that are output/results of the Monolix project, please refer to [https://lixoft.com/products/monolix/](https://lixoft.com/products/monolix/) for a more detailed description of the files under this folder. `SAEM_data_(01)480min.txt` is the data file, where: * `(01)` denotes the ligand in the stimuli: * `TNF`: TNF stimulated condition. * `LPS`: LPS stimulated condition. * `Pam3CSK4`: Pam3CSK stimulated condition. * `PolyIC`: PolyIC stimulated condition. * `CpG`: CpG stimulated condition. `params()_params()_params()_params()_params()_params()_NFkB_cyto_init_shift.txt` is the ODE model file for monolix project, where: * `()` denotes the parameter index (please refer to Guo et al., 2025, Supplementary table S1-2, for more details). #### File: SAEM\_proj\_2024\_downsampling.zip **Description:** The file folder for parameter estimation projects to estimate parameter distribution from the downsampled NFkB trajectories, for checking different sample size impact on results. Should be run in Monolix software. including the raw rescaled experimental data in monolix required format, and the outcome results of the fitted individual parameters. (for Figure S2) `monolix_projects_description.csv` lists the project information. `read_me.txt` explained the details of the files. **Naming convention**: When applicable, file names follow the pattern `XGESN2024(01)` is the folder for each project, where: * `(01)` denotes the condition index, which is explained in Simulation_recording.xlsx. Under each folder, the corresponding `.mlxtran` file is the project file that can be run in Monolix R2020, to start solving the corresponding NLMEs using SAEM algorithms. (Before running the file, delete the 'results' folder. After running, all the estimation results is saved in the 'results' folder.). `results` file folder saves all the results that are output/results of the Monolix project, please refer to [https://lixoft.com/products/monolix/](https://lixoft.com/products/monolix/) for a more detailed description of the files under this folder. `down_samplilng_SAEM_data_(01)480min.txt` is the data file, where: * `(01)` denotes the ligand in the stimuli: * `TNF`: TNF stimulated condition. * `LPS`: LPS stimulated condition. * `Pam3CSK4`: Pam3CSK stimulated condition. * `PolyIC`: PolyIC stimulated condition. * `CpG`: CpG stimulated condition. `params52n2_params99_params101_params68_params75_NFkB_cyto_init_shift.txt` is the ODE model file for monolix project. #### File: MI\_single\_ligand.zip **Description:** The file folder of single-ligand stimulation, experimental, sampling, fitting data, in a format for MI calculation. **.mat files Naming convention**: When applicable, file names follow the pattern `mutual_info_format_single_ligand_(01).mat` is the signaling codons for single cells saved in a specific format that's used in the mutual information calculation (codes see Software, method details refer to Guo et al. 2025), where: * `(01)` denotes data types. * `Sampling`: is the data generated from a simulation based on parameters sampled from inferred parameter distributions. * `Fitting`: is the data generated from a simulation based on parameters fitted to experimental data. * `Ade`: is from the experimental data. ##### MAT files .mat files include `nfkb` struct with three struct fields. The following struct fields are included: * `sc_metrics`: struct variable saving signaling codons (struct fields: `TotalActivity`, `Speed`, `PeakAmplitude`, `OscVsNonOsc`, `Duration`, `EarlyVsLate`) for each single cell. * `id`: ligand & dose (if applicable) information * `ids`: all conditions. #### File: MI\_denoise.zip **Description:** The file folder of signaling codons for denoise simulation data format for MI calculation. corresponding to Figure 4. **.mat files Naming convention**: When applicable, file names follow the pattern `mutual_info_format_alldata_sc_(01)(02)_(03)_0331.mat `is the signaling codons for single cells saved in a specific format that's used in the mutual information calculation (codes see Software, method details refer to Guo et al. 2025), where: * `(01)` denotes the denoised modules. * `NFkB_var_red`: The variation of parameters in NF-κB module is reduced. * `no_noise`: The variation of parameters in all modules is reduced. * `rcpt_red`: The variation of parameters in receptor modules is reduced. * `TAK_noise`: The variation of parameters in modules other than adaptor module is reduced. * `TAKac_NFkB_red`: The variation of parameters in NF-κB module and adaptor module is reduced. * `TAKac_red`: The variation of parameters in adaptor module is reduced. * `wt`: The original variation of the parameters distribution inferred from experiments. * `IkBo`: The original variation of parameters distribution inferred from experiments, with reducded NFkB regulated IkBa transcription, 0.1x fold reduction. * `IkBop25`: The original variation of parameters distribution inferred from experiments, with reduced NFkB regulated IkBa transcription, 0.25x fold reduction. * `IkBo_rcpt_red`: The variation of parameters in receptor modules is reduced, with reduced NFkB regulated IkBa transcription, 0.25x fold reduction. * `NFkB_noise`: The variation of parameters in modules other than NFkB core module is reduced. * `(02)` denotes data types. * `1`,`2`,...,`10`: the 1st, 2nd, ..., 10th simulation replicate generated by independent sampling parameters.  * `(03)` denotes scaling methods. * `min_max_rescale`: all signaling codons rescaled using min–max scaling. ##### MAT files .mat files include `nfkb` struct with three struct fields. The following struct fields are included: * `sc_metrics`: struct variable saving signaling codons (struct fields: `TotalActivity`, `Speed`, `PeakAmplitude`, `OscVsNonOsc`, `Duration`, `EarlyVsLate`) for each single cell. * `id`: ligand & dose (if applicable) information * `ids`: all conditions. #### File: Sim\_unstim\_fitting\_alldose\_r2\_codon\_metric.mat **Description:** The simulated data of unstimulated conditions, used for the Mutual information calculation. For example, the 'mutual_info_format_codon_single_ligand_unstim_Sampling_20230614.mat' uses unstim condition data from this file. ##### Variables * `collect_feature_vects`: struct saving the "signaling codons" for each virtual single cell. With ligand and doses specified.  * `collect_feature_vects.Duration`, `collect_feature_vects.OscVsNonOsc`, `collect_feature_vects.Speed`, `collect_feature_vects.TotalActivity`, `collect_feature_vects.EarlyVsLate`, `collect_feature_vects.PeakAmplitude`: save corresponding signaling codons (rescaled z-scores). Different species are saved for each single cell, including 'nucNFkB', 'TNFR', 'TLR4', 'TLR2', 'TLR3', 'TLR9', 'IKK', 'TAK1', and 'IkBamRNA'. 'nucNFkB' corresponds to the NFkB activity trajectories, which are saved in `collect_feature_vects.Duration{,}(1:9:end,:)`. The orders of species of other struct fields for each single cell are the same. * `collect_feature_vects.info_ligand`: ligand information of the stimuli condition. * `collect_feature_vects.info_dose_str`: dose information of the stimuli condition. * `collect_feature_vects.info_data_type`: simulation indicates simulated dataset. * `data`: simulation data structure. data.model_sim and data.exp are identical simulation datasets. with each cell stimulation save in the data.info_ligand and data.info_dose.  * `data.model_sim`: saves the model simulated dynamic trajectories (μM) including 'nucNFkB', 'TNFR', 'TLR4', 'TLR2', 'TLR3', 'TLR9', 'IKK', 'TAK1', and 'IkBamRNA', where 'nucNFkB' corresponds to the NFkB activity trajectories and saved in `data.model_sim{,}(1:9:end,:)`. Each row is one specifies a dynamic in one cell, each column is a time point, with a time interval of 5 minutes. * `data.info_ligand`: ligand information of the stimuli condition. * `data.info_dose_str`: ligand information of the stimuli condition. * `data.info_num_cells`: cell number multiplying species numbers for each condition. * `data.order`: orders of the single-cell based on specific signaling codon condition (by default is the random order). * `data.exp`: same as `data.model_sim`. * `data.info_dose_index`: ligand information of the stimuli condition. * `metrics`: the dynamic features of all cells for each stimulated conditions. Different species are saved for each single cell, including 'nucNFkB', 'TNFR', 'TLR4', 'TLR2', 'TLR3', 'TLR9', 'IKK', 'TAK1', and 'IkBamRNA'. 'nucNFkB' are the NFkB activity trajectories (μM), which are saved in `metrics{,}.time_series(1:9:end,:)`. The orders of species of other struct fields for each single cell are the same. In`metrics{,}.time_series`, each row is one specifies a dynamic in one cell, each column is a time point, with a time interval of 5 minutes. * all above data variables, sharing the same order of the virtual cells. i.e., the first cell in `collect_feature_vects`, stimulated by 10ng/mL TNF are the same cell as in `data`, `metrics`. #### File: Sim8\_5\_signle\_ligand\_codon\_metric\_r3.mat **Description:** The simulated data for single-cell stimulus response specificity analysis, **for WT**; the data is responses of same individual cell to five different ligands. using the sampled parameters from the non-parameterized distribution for single-ligand simulation (See method "Generating new dataset of NFκB trajectories") ##### Variables * `sim_data_tbl`: the table of the predicted simulation dataset via sampling parameters. With parameters in each module (receptor & core) saved. Ligand and doses specified for each virtual cell. Simulated time series of NFkB activity is saved every 5 minutes. Notice that other varialbes are also saved, such as IKK, TAK1, which is specified in sim_data_tbl.species. Thus, every 9 rows documenting the identical cells, but just different specifies measurement. NFkB is saved in sim_data_tbl.trajectory(1:9:end,:). The following columns are included: * `parameter_module`: the module of the parameters. * `parameter_reac_num`, parameter_para_num: reaction index of the corresponding parameter. * `parameter_name`: the parameter name. * `parameter_fold_change`: fold changes of the parameters compared to the representative cell values. * `parameter_value`: parameter value (units are explained in Table S1-2 of Guo et al., 2025). * `ligand`: Which ligand is applied in the stimuli. * `dose_str`: the dosage applied in the stimuli. * `dose_val`: values of dosage applied in the stimuli. * `species`: specifies saved in trajectory. * `flag`: N/A * `type`: wild type or other genotypes. * `trajectory`: saves the model simulated dynamic trajectories of 'nucNFkB', 'TNFR', 'TLR4', 'TLR2', 'TLR3', 'TLR9', 'IKK', 'TAK1', and 'IkBamRNA', where 'nucNFkB' corresponds to the NFkB activity trajectories and is saved in `sim_data_tbl.trajectory(1:9:end,:)`. Each row is one specifies dynamic in one cell, each column is a time point, with time interval 5 minutes. * `metrics`, `collect_feature_vects`, `data` have the same structure as in "Sim_unstim_fitting_alldose_r2_codon_metric.mat" #### File: Sim5\_codon\_all5dose\_metric.mat **Description:** the simulated single-ligand (Figure S3 and supplementary notes). Note that 15 condtions are saved in this file, but only the last 5 conditions are presented in the paper.  ##### Variables * `metrics`, `collect_feature_vects`, `data` have the same structure as in "Sim_unstim_fitting_alldose_r2_codon_metric.mat" #### File: Sim2\_fitting\_alldose\_codon\_metric.mat **Description:** The simulated single-ligand stimulation data, using the sampled parameters from the non-parameterized distribution for single-ligand simulation (See method "Generating new dataset of NFκB trajectories") (Figure S3) ##### Variables * `metrics`, `collect_feature_vects`, `data` have the same structure as in "Sim_unstim_fitting_alldose_r2_codon_metric.mat" #### File: Sim3\_codon\_r1\_metric.mat **Description:** The simulated data of extended doses of single-ligand stimulation, generated via sampling parameters from the non-parameterized distribution (See method "Generating new dataset of NFκB trajectories"). (Figure 3) (Sim3_codon_r1_metric.mat, Sim3_codon_r2_metric.mat, Sim3_codon_r3_metric.mat, Sim3_codon_r4_metric.mat, Sim3_codon_r5_metric.mat, have the same structure/description but just for different ligands.) ##### Variables * `metrics`, `collect_feature_vects`, `data` have the same structure as in "Sim_unstim_fitting_alldose_r2_codon_metric.mat" #### File: Exp\_data\_Ade.mat **Description:** raw single-ligand stimulation experimental data, before rescaled. ##### Variables * `dataTbl`: the data table of the experiments. Time series of NFkB activity is measured every 5 minutes, with ligand and doses specified for each cell. The following columns are included: * `time_series`: time series of experimental single-cell NFkB (A.U.), measured every 5 minutes. * `Ligand`: ligand applied to stimulate the corresponding cell. * `Dose`: dosage of the ligand applied to stimulate the cell. * `DoseUnit`: the dose units. * Other columns are documentation details of the experiments, not used for further analysis. #### File: All\_ligand\_codon\_2023\_t33\_cv\_filtered\_TNF.mat **Description:** raw rescaled single-ligand stimulation simulation (Fitted individual cell parameters) and experimental data with signaling codons (Figure 2 and S4 heatmaps) , after removing the simulated trajectories with low CV (66% of the lower-CV trajectoreis are filtered out) and the corresponding experimental trajectories for TNF condition (See supplementary notes for more detail). The parameter values are also documented in this data file. (Figure 2 & Figure S2 & Figure S3) ##### Variables * `metrics`, `collect_feature_vects`, `data` have similar structure as in "Sim_unstim_fitting_alldose_r2_codon_metric.mat", but with the differences as described below. * `metrics`: the dynamic features for NFkB activity of all cells for each stimulated conditions. metrics{1:2:end} are experimental data, and metrics{2:2:end} are simulation data.  * `collect_feature_vects`: structure saving the "signaling codons" of  NFkB activity for each virtual single cell. {1:2:end} are experimental data, and {2:2:end} are simulation data.  * `data`: simulation data and experimental data structure. data.model_sim saves simulation, and data.exp are save the experiments, they correspond to one identical cell. With each cell stimulation save in the data.info_ligand and data.info_dose.  * all above data variables, sharing the same order of the cells. i.e., the first cell in `collect_feature_vects`, stimulated by 10ng/mL TNF are the same cell as in `data`, `metrics`. #### File: All\_ligand\_codon\_2023.mat **Description:** raw rescaled single-ligand stimulation experimental data with signaling codons. (No TNF filtered) ##### Variables * `metrics`, `collect_feature_vects`, `data` have same structure as in "All_ligand_codon_2023_t33_cv_filtered_TNF.mat". #### File: Ade\_all\_stim\_unstim\_codon.mat **Description:** raw rescaled (by 15 conditions presented in Figure 2) single-ligand stimulation experimental data with signaling codons with unstimulated condition (condition 16).  ##### Variables * `metrics`, `collect_feature_vects`, `data` have same structure as in "All_ligand_codon_2023_t33_cv_filtered_TNF.mat". #### File: Sim16\_IkBao\_matching\_5\_signle\_ligand\_codon\_metric\_p25x\_r1.mat **Description:** The simulated data for single-cell stimulus response specificity analysis, for **IkBa promoter mutant**; the data is responses of the same individual cell to five different ligands. using the sampled parameters from the non-parameterized distribution for single-ligand simulation (See method "Generating new dataset of NFκB trajectories") ##### Variables * `sim_data_tbl`, `metrics`, `collect_feature_vects`, `data` have the same structure as in "Sim8_5_signle_ligand_codon_metric_r3.mat" #### File: simulation\_denoise.zip **Description:** The file folder for the simulated data for denoise different modules in NFkB network, for WT and IkBa promoter mutant. Using the sampled parameters from the non-parameterized distribution for single-ligand simulation (See method "Generating new dataset of NFκB trajectories"), denoise is achieved by setting the corresponding module's varied parameters to one fixed value (See method "Modeling different genotype") (For Figure 4-5) **Naming convention:** When applicable, file names follow the pattern `Sim(01)_(02)_(03)_heterogeneity_codon_metric(04)(05).mat`, where: * `(01)` denotes simulation index * `(02)` denotes genotypes * `SS`, `IkBas`, `wt_IkBo`: IkBa mutant, with reduced NFkB regulated IkBa transcription. * *blank*: wild type parameters. * `(03)` denotes denoise modules: * `reduce_core`: reduced variation of parameters in NFkB core module. * `reduce_rcpt`: reduced variation of parameters in rthe eceptor module. * `reduce_TAK1ac`: reduced variation of parameters in adaptor module. * `NFkB`: reduced variation of parameters in all modules but NFkB core module. * `TAK1`: reduced variation of parameters in all modules but adaptor module. * `no`: reduced variation of parameters in all modules. * *blank*: original parameter distribution without reducing the variation. * `(04)` denotes replicates * `_p25x_`: for IkBa mutant, the NFkB regulated IkBa transcription is reduced by 0.25x fold change. * `(04)` denotes replicates * `1`, `2`, ..., `5`, or `r1`, `r2`, ...: replicate 1, 2,..., 5, generated from independent sampling. **Examples:** * Sim17_reduce_core_heterogeneity_codon_metric5.mat * Simulated NF-κB response trajectories of wild-type macrophages under five stimulation condition, with core module parameter heterogeneity reduced, replicate 5. * Sim22_TAK1_heterogeneity_codon_metric1.mat * Simulated NF-κB response trajectories of wild-type macrophages under five stimulation condition, with only TAK1 module parameter heterogeneity, replicate 1. * Sim18_wt_IkBo_codon_metric3.mat * Simulated NF-κB response trajectories of IkBa mutant macrophages under five stimulation condition, with parameter heterogeneity, replicate 3. ##### Variables in **.mat files:** * `sim_data_tbl`, `metrics`, `collect_feature_vects`, `data` have the same structure as in "Sim8_5_signle_ligand_codon_metric_r3.mat"