API Reference

Data Standardization & Cleanup

`processing.cleanup`

`process_collecttri()`

Processes the CollecTRI file to clean and filter mRNA-TF interactions. Removes complex interactions, filters by target genes, and saves the result.

`format_site(site)`

Formats a phosphorylation site string.

If the input is NaN or an empty string, returns an empty string. If the input contains an underscore ('_'), splits the string into two parts, converts the first part to uppercase, and appends the second part unchanged. Otherwise, converts the entire string to uppercase.

Parameters:

Name	Type	Description	Default
`site`	`str`	The phosphorylation site string to format.	required

Returns:

Name	Type	Description
`str`		The formatted phosphorylation site string.

`process_msgauss()`

Processes the MS Gaussian data file to generate time series data.

`process_msgauss_std()`

Processes the MS Gaussian data file to compute transformed means and standard deviations.

`process_routlimma()`

Processes the Rout Limma table to generate time series data for mRNA.

`update_gene_symbols(filename)`

Updates the GeneID column in a CSV file by mapping GeneIDs to gene/protein symbols.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The path to the CSV file to be updated. The file must contain a 'GeneID' column.	required

`move_processed_files()`

Moves or copies processed files to their respective directories.

Optimization Results Mapping

`processing.map`

`map_optimization_results(tf_file_path, kin_file_path, sheet_name='Alpha Values')`

Reads the TF-mRNA optimization results from an Excel file and maps mRNA to each TF.

Parameters:

Name	Description	Default
`tf_file_path`	Path to the Excel file containing TF-mRNA optimization results.	required
`kin_file_path`	Path to the Excel file containing Kinase-Phosphorylation optimization results.	required
`sheet_name`	The name of the sheet in the Excel file to read from. Default is 'Alpha Values'.	`'Alpha Values'`

Returns:

Type	Description
	pd.DataFrame: A DataFrame containing the mapped TF, mRNA, Psite, and Kinase information.

`create_cytoscape_table(mapping_csv_path)`

Creates a Cytoscape-compatible edge table from a mapping file.

Parameters:

Name	Type	Description	Default
`mapping_csv_path`	`str`	Path to the input CSV file with columns: TF, TF_strength, mRNA, Psite, Kinase, Kinase_strength	required

Returns:

Name	Type	Description
`table`	`DataFrame`	Edge table with columns [Source, Target, Interaction, Strength]

`add_kinetic_strength_columns(mapping_path, mapping__path, excel_path, suffix)`

Adds kinetic strength columns to the mapping files based on the provided Excel file.

Parameters:

Name	Type	Description	Default
`mapping_path`	`str`	Path to the first mapping file.	required
`mapping__path`	`str`	Path to the second mapping file.	required
`excel_path`	`str`	Path to the Excel file containing kinetic strength data.	required
`suffix`	`str`	Suffix to append to the output files.	required

`generate_nodes(edge_df)`

Infers node types and aggregates all phosphorylation sites per target node from phosphorylation edges.

Parameters:

Name	Type	Description	Default
`edge_df`	`DataFrame`	Must have columns ['Source', 'Target', 'Interaction', 'Psite']	required

Returns:

Type	Description
	pd.DataFrame: DataFrame with columns ['Node', 'Type', 'Psite']

Kinase-Phosphorylation Optimization

Evolutionary Algorithms

`kinopt.evol.config.constants`

`kinopt.evol.config.logconf`

`ColoredFormatter`

Bases: Formatter

`format(record)`

Format the log record with ANSI color codes and elapsed time.

Parameters:

Name	Type	Description	Default
`record`	`LogRecord`	The log record to format.	required

Returns: str: The formatted log message with ANSI color codes.

`remove_ansi(s)` `staticmethod`

Remove ANSI escape codes from a string.

Parameters:

Name	Type	Description	Default
`s`	`str`	The string from which to remove ANSI escape codes.	required

Returns: str: The string without ANSI escape codes.

`setup_logger(name='phoskintime', log_file=None, level=logging.DEBUG, log_dir=LOG_DIR, rotate=True, max_bytes=2 * 1024 * 1024, backup_count=5)`

Function to set up a logger with both file and console handlers.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the logger.	`'phoskintime'`
`log_file`	`str`	Path to the log file. If None, a default path is generated.	`None`
`level`	`int`	Logging level (e.g., logging.DEBUG, logging.INFO).	`DEBUG`
`log_dir`	`str`	Directory where log files are stored.	`LOG_DIR`
`rotate`	`bool`	Whether to use rotating file handler.	`True`
`max_bytes`	`int`	Maximum size of log file before rotation.	`2 * 1024 * 1024`
`backup_count`	`int`	Number of backup files to keep.	`5`

Returns:

Name	Type	Description
`logger`	`Logger`	Configured logger instance.

`kinopt.evol.exporter.plotout`

`plot_residuals_for_gene(gene, gene_data)`

Generates and saves combined residual-related plots for one gene with all psites in the legend.

Parameters:

Name	Type	Description	Default
`gene`	`str`	Gene identifier.	required
`gene_data`	`dict`	Dictionary with keys 'psites', 'observed', 'estimated', and 'residuals' containing data for all psites.	required
`TIME_POINTS`	`ndarray or list`	Time points corresponding to the series.	required

`opt_analyze_nsga(problem, result, F, pairs, approx_ideal, approx_nadir, asf_i, pseudo_i, n_evals, hv, hist, val, hist_cv_avg, k, igd, best_objectives, waterfall_df, convergence_df, alpha_values, beta_values)`

Function to generate and save various plots related to optimization results.

Parameters:

Name	Description	Default
`problem`	The optimization problem instance.	required
`result`	The result of the optimization run.	required
`F`	Objective function values.	required
`pairs`	Pairs of objectives to plot.	required
`approx_ideal`	Approximate ideal point in objective space.	required
`approx_nadir`	Approximate nadir point in objective space.	required
`asf_i`	Index of the best solution in terms of the augmented weighted sum.	required
`pseudo_i`	Index of the pseudo weights.	required
`n_evals`	Number of evaluations at each generation.	required
`hv`	Hypervolume values.	required
`hist`	History of the optimization process.	required
`val`	Values for convergence plot.	required
`hist_cv_avg`	Average constraint violation history.	required
`k`	Number of generations.	required
`igd`	Inverted generational distance values.	required
`best_objectives`	Best objectives found during the optimization process.	required
`waterfall_df`	DataFrame containing waterfall plot data.	required
`convergence_df`	DataFrame containing convergence data.	required
`alpha_values`	Dictionary containing alpha values for parameters.	required
`beta_values`	Dictionary containing beta values for parameters.	required

Returns:

Type	Description
	None

`opt_analyze_de(long_df, convergence_df, ordered_optimizer_runs, x_values, y_values, val)`

Function to generate and save various plots related to optimization results.

Parameters:

Name	Type	Description	Default
`long_df`	`DataFrame`	DataFrame containing parameter values and objective function values.	required
`convergence_df`	`DataFrame`	DataFrame containing convergence data.	required
`ordered_optimizer_runs`	`DataFrame`	DataFrame containing ordered optimizer runs.	required
`x_values`	`list`	X-axis values for the waterfall plot.	required
`y_values`	`list`	Y-axis values for the waterfall plot.	required
`val`	`list`	Values for the convergence plot.	required

Returns:

Type	Description
	None

`kinopt.evol.exporter.sheetutils`

`output_results(P_initial, P_init_dense, P_estimated, residuals, alpha_values, beta_values, result, timepoints, OUT_FILE)`

Function to output results to an Excel file.

Parameters:

Name	Type	Description	Default
`P_initial`	`dict`	Dictionary with initial parameters.	required
`P_init_dense`	`ndarray`	Dense matrix of initial parameters.	required
`P_estimated`	`ndarray`	Dense matrix of estimated parameters.	required
`residuals`	`ndarray`	Dense matrix of residuals.	required
`alpha_values`	`dict`	Dictionary with alpha values.	required
`beta_values`	`dict`	Dictionary with beta values.	required
`result`	`str`	Result string for logging.	required
`timepoints`	`list`	List of time points.	required
`OUT_FILE`	`str`	Output file path.	required

Returns:

Type	Description
	None

`kinopt.evol.objfn.minfndiffevo`

`PhosphorylationOptimizationProblem`

Bases: ElementwiseProblem

Single-objective constrained optimization problem for phosphorylation dynamics (Numba-accelerated).

Minimizes loss between observed and predicted phosphorylation levels subject to constraints that alpha and beta weights sum to 1.0 for each gene-psite and kinase group, respectively.

Objective

minimize loss (MSE, autocorrelation, Huber, or MAPE)

Constraints g(x) <= 0: - for each alpha group: |sum(alpha_group) - 1| <= eps_eq - for each kinase beta group: |sum(beta_group) - 1| <= eps_eq

Attributes:

Name	Type	Description
`P_initial`	`dict`	Dictionary mapping (gene, psite) tuples to data dictionaries.
`P_initial_array`	`ndarray`	Observed phosphorylation matrix with shape (i_max, t_max).
`K_index`	`dict`	Dictionary mapping kinase names to lists of (psite_label, row_idx) tuples.
`K_array`	`ndarray`	Kinase activity matrix with shape (n_k_rows, t_max).
`gp_offsets`	`ndarray`	Offset indices for gene-psite groups.
`gp_kinase_ids`	`ndarray`	Kinase IDs for alpha variables.
`k_offsets`	`ndarray`	Offset indices for kinase groups.
`k_psite_rows`	`ndarray`	Psite row indices for beta variables.
`num_alpha`	`int`	Total number of alpha variables.
`num_beta`	`int`	Total number of beta variables.
`eps_eq`	`float`	Tolerance for equality constraints.
`loss_id`	`int`	Loss type identifier.
`include_reg`	`bool`	Whether to include regularization.
`n_scalar`	`float`	Scalar factor for normalization.

`estimated_series(params)`

Compute estimated phosphorylation series for given parameters.

Parameters:

Name	Type	Description	Default
`params`	`array - like`	1D array of parameters [alpha_1, ..., alpha_N, beta_1, ..., beta_M].	required

Returns:

Name	Type	Description
`ndarray`		Predicted phosphorylation matrix with shape (i_max, t_max).

`residuals(params)`

Compute residuals between observed and estimated phosphorylation for given parameters.

Parameters:

Name	Type	Description	Default
`params`	`array - like`	1D array of parameters [alpha_1, ..., alpha_N, beta_1, ..., beta_M].	required

Returns:

Name	Type	Description
`ndarray`		Residual matrix (observed - estimated) with shape (i_max, t_max).

`kinopt.evol.objfn.minfnnsgaii`

`PhosphorylationOptimizationProblem`

Bases: ElementwiseProblem

Multi-objective optimization

F[0] = main loss (error) F[1] = alpha sum-to-1 violations (aggregated) F[2] = beta sum-to-1 violations (aggregated)

Parameters:

Name	Type	Description	Default
`P_initial`	`dict`	Dictionary with keys as (gene, psite) and values containing 'Kinases' and 'TimeSeries'.	required
`P_initial_array`	`ndarray`	Array of observed gene-psite data.	required
`K_index`	`dict`	Dictionary mapping each kinase to a list of (psite, time_series) tuples.	required
`K_array`	`ndarray`	Array of kinase-psite time-series data.	required
`gene_psite_counts`	`list`	List of integers indicating the number of kinases associated with each gene-psite.	required
`beta_counts`	`dict`	Dictionary indicating how many beta values correspond to each kinase-psite combination.	required

`objective_function(params)`

Computes the main objective function (loss) for the given parameters.

Parameters:

Name	Type	Description	Default
`params`	`ndarray`	Parameter vector containing alpha and beta values.	required

Returns:

Name	Type	Description
`float`		Computed loss value based on the selected loss type (base, autocorrelation, huber, or mape).

`kinopt.evol.opt.optrun`

`choose_de_pop_size(problem)`

Determine an appropriate population size for Differential Evolution (DE) algorithms.

The population size is calculated based on the number of decision variables, with bounds to ensure reasonable performance. DE algorithms benefit from population sizes that are multiples of 10.

Parameters:

Name	Type	Description	Default
`problem`		The optimization problem instance with an 'n_var' attribute indicating the number of decision variables.	required

Returns:

Name	Type	Description
`int`		The calculated population size (multiple of 10, between 100 and 600).

`choose_nsga_pop_size(problem, n_obj=3)`

Determine an appropriate population size for NSGA-based multi-objective algorithms.

The population size is scaled based on the problem dimensionality (number of decision variables) with heuristic thresholds. The size is rounded to multiples of 50 and enforced to be at least 10 times the number of objectives.

Parameters:

Name	Type	Description	Default
`problem`		The optimization problem instance with an 'n_var' attribute indicating the number of decision variables.	required
`n_obj`	`int`	Number of objectives in the problem. Defaults to 3.	`3`

Returns:

Name	Type	Description
`int`		The calculated population size (multiple of 50, at least 10*n_obj).

`binary_tournament_loss_cv(pop, P, eps_cv=1e-10, cv_mode='linf', **kwargs)`

Robust binary tournament comparator for constrained optimization.

This function performs binary tournament selection with constraint handling using either true constraint violations (CV) or pseudo-constrained objectives. It supports both single-objective and multi-objective formulations.

Works for

A) single-objective: F has length 1 - if CV exists, use constraint-domination (CV first, then F) - else compare by F only B) pseudo-constrained objectives: F = [loss, alpha_violation, beta_violation] - feasibility-first based on F[1], F[2], then loss

Parameters:

Name	Type	Description	Default
`pop`		Population of individuals with 'F' (objectives) and optionally 'CV' attributes.	required
`P`	`ndarray`	Tournament pairs array of shape (n_tournaments, 2), where each row contains indices of two competing individuals.	required
`eps_cv`	`float`	Feasibility tolerance for constraint violations. Defaults to 1e-10.	`1e-10`
`cv_mode`	`str`	Mode for aggregating constraint violations when using pseudo-constrained objectives. Options: 'linf' (max), 'l1' (sum), 'l2' (norm). Defaults to "linf".	`'linf'`
`**kwargs`		Additional keyword arguments (unused, for compatibility).	`{}`

Returns:

Type	Description
	np.ndarray: Array of winning indices for each tournament, shape (n_tournaments,).

Raises:

Type	Description
`ValueError`	If pressure is not 2 (only binary tournaments supported) or if cv_mode is not one of 'linf', 'l1', 'l2'.

`run_optimization(P_initial, P_initial_array, K_index, K_array, gene_psite_counts, beta_counts, PhosphorylationOptimizationProblem)`

Sets up and runs the multi-objective optimization problem for phosphorylation using an NSGA2 algorithm and a thread pool for parallelization.

Parameters:

Name	Type	Description	Default
`P_initial, P_initial_array, K_index, K_array, gene_psite_counts, beta_counts`		Data structures describing the problem (time-series data, kinases, etc.).	required
`PhosphorylationOptimizationProblem`	`class`	The custom problem class to be instantiated.	required

Returns:

Name	Type	Description
`result`		The pymoo result object containing the optimized population and history.
`exec_time`		Execution time for the optimization.

`pick_best_loss_with_constraints_as_objectives(result, eps_cv=1e-10, cv_mode='l1', tie_tol=1e-12, tie_break='loss_then_l2')`

Select the best solution from a population with constraints formulated as objectives.

This function assumes a specific objective structure where

F[:,0] = loss (minimize) F[:,1] = constraint violation 1 (minimize, ideally 0) F[:,2] = constraint violation 2 (minimize, ideally 0)

Selection rule

A) If any feasible solutions exist (cv1<=eps and cv2<=eps): choose minimum loss among feasible. B) Else: choose minimum aggregated CV; tie-break by loss; optional tie-break by ||X||2.

Parameters:

Name	Type	Description	Default
`result`		Pymoo result object containing the final population with 'F' and 'X' attributes.	required
`eps_cv`	`float`	Feasibility tolerance for constraint violations. Defaults to 1e-10.	`1e-10`
`cv_mode`	`str`	Mode for aggregating constraint violations. Options: 'l1' (sum), 'linf' (max), 'l2' (Euclidean norm). Defaults to "l1".	`'l1'`
`tie_tol`	`float`	Tolerance for considering values as tied. Defaults to 1e-12.	`1e-12`
`tie_break`	`str`	Tie-breaking strategy. Options: 'loss_then_l2' or 'loss_only'. Defaults to "loss_then_l2".	`'loss_then_l2'`

Returns:

Name	Type	Description
`tuple`		A tuple containing: - best_solution: The selected individual from the population. - best_index_in_pop (int): The index of the best solution in the population. - info (dict): Dictionary with selection metadata including selection case, number of feasible solutions, and best objective values.

Raises:

Type	Description
`ValueError`	If the objective array has fewer than 3 columns or if cv_mode is not one of 'l1', 'linf', 'l2'.

`post_optimization_nsga(result, weights=np.array([1.0, 1.0, 1.0]), ref_point=np.array([3, 1, 1]))`

Post-process the result of a multi-objective NSGA-based optimization run.

This function analyzes the optimization history, computes convergence metrics (hypervolume, IGD+), identifies the best solution using constraint handling, and generates CSV reports for convergence and parameter scans.

Parameters:

Name	Type	Description	Default
`result`		The final result object from the pymoo optimizer containing the final population, history, and objective values.	required
`weights`	`ndarray`	Array of length 3 for weighting the objectives in decomposition-based selection. Defaults to [1.0, 1.0, 1.0].	`array([1.0, 1.0, 1.0])`
`ref_point`	`ndarray`	Reference point for hypervolume computation. Defaults to [3, 1, 1].	`array([3, 1, 1])`

Returns:

Name	Type	Description
`tuple`		A tuple containing 23 elements: - F: Final objective values array - pairs: Objective pairs for plotting [(0,1), (0,2), (1,2)] - n_evals: Number of evaluations per generation - hist_cv: Minimum constraint violation per generation - hist_cv_avg: Average constraint violation per generation - k: Generation index when first feasible solution appeared - metric_igd: IGDPlus metric object - metric_hv: Hypervolume metric object - best_solution: The selected best individual - best_objectives: Objective vector of best solution - optimized_params: Decision variables (X) of best solution - approx_nadir: Approximate nadir point - approx_ideal: Approximate ideal point - scores: Best solution's objective scores - best_index: Index of best solution in population - hist: Full optimization history - hist_hv: Hypervolume values per generation - hist_igd: IGD+ values per generation - convergence_df: DataFrame with iteration vs best objective - waterfall_df: DataFrame with all solutions and parameters - asf_i: Index of best solution by ASF decomposition - pseudo_weights_result: Result of pseudo-weights MCDM method - pairs (duplicate): Objective pairs - val: Best objective value per generation

`post_optimization_de(result, alpha_values, beta_values)`

Post-process the result of a single-objective DE or GA optimization run.

This function extracts the final population, creates parameter labels from alpha and beta values, generates a parameter scan DataFrame sorted by objective value, and produces a convergence DataFrame showing the best objective per iteration.

Parameters:

Name	Type	Description	Default
`result`		The final result object from the pymoo optimizer (e.g., GA or DE result) containing the population, history, and objective values.	required
`alpha_values`	`dict`	Dictionary mapping (gene, psite) tuples to dictionaries of {kinase: value} for alpha parameters.	required
`beta_values`	`dict`	Dictionary mapping (kinase, psite) tuples to beta parameter values.	required

Returns:

Name	Type	Description
`tuple`		A tuple containing 6 elements: - ordered_optimizer_runs: DataFrame of all solutions sorted by objective value - convergence_df: DataFrame with iteration vs best objective value - long_df: Long-form DataFrame for parameter visualization with columns ['Individual', 'Objective Value (F)', 'Parameter', 'Parameter Value', 'Type'] - x_values: List of iteration indices selected for plotting - y_values: List of objective values corresponding to x_values - val: Best objective value per generation from history

`kinopt.evol.optcon.construct`

`pipeline(input1_path: str, input2_path: str, time_series_columns: list[str], scaling_method: str, split_point: float, segment_points: list[float], estimate_missing_kinases: bool, kinase_to_psites: dict[str, int])`

Function to run the entire pipeline for loading and processing data.

Parameters:

Name	Type	Description	Default
`input1_path`	`str`	Path to the first CSV file (HGNC data).	required
`input2_path`	`str`	Path to the second CSV file (kinase interactions).	required
`time_series_columns`	`list[str]`	List of time series columns to extract.	required
`scaling_method`	`str`	Method for scaling the data.	required
`split_point`	`float`	Split point for scaling.	required
`segment_points`	`list[float]`	Segment points for scaling.	required
`estimate_missing_kinases`	`bool`	Flag to estimate missing kinases.	required
`kinase_to_psites`	`dict[str, int]`	Dictionary mapping kinases to their respective psites.	required

Returns:

Name	Type	Description
`full_hgnc_df`	`DataFrame`	The scaled data from input1.
`interaction_df`	`DataFrame`	The subset/merged DataFrame from input2.
`observed`	`DataFrame`	Subset of full_hgnc_df merged with interaction_df.
`P_initial`	`dict`	Dictionary mapping gene-psite pairs to kinase relationships and time-series data.
`P_initial_array`	`ndarray`	Array containing observed time-series data for gene-psite pairs.
`K_array`	`ndarray`	Array containing time-series data for kinase-psite combinations.
`K_index`	`dict`	Mapping of kinases to their respective psite data.
`beta_counts`	`dict`	Mapping of kinase indices to the number of associated psites.
`gene_psite_counts`	`list`	List of counts of psites for each gene.
`n`	`int`	Number of unique gene-psite pairs.

`load_geneid_to_psites(input1_path=INPUT1)`

Function to load geneid to psite mapping from input1.csv. Args: input1_path (str): Path to the first CSV file (HGNC data). Returns: geneid_psite_map (dict): Dictionary mapping gene IDs to sets of psites.

`get_unique_kinases(input2_path=INPUT2)`

Function to extract unique kinases from input2.csv. Args: input2_path (str): Path to the second CSV file (kinase interactions). Returns: kinases (set): Set of unique kinases extracted from the input2 file.

`check_kinases()`

Function to check if kinases from input2.csv are present in input1.csv.

Returns:

Type	Description
	None

`kinopt.evol.utils.iodata`

`format_duration(seconds)`

Returns a formatted string representing the duration in seconds, minutes, or hours.

Parameters:

Name	Type	Description	Default
`seconds`	`float`	The duration in seconds.	required

Returns: str: The formatted duration string.

`load_and_scale_data(estimate_missing, scaling_method, split_point, seg_points)`

Function to load and scale data from CSV files.

Parameters:

Name	Type	Description	Default
`estimate_missing`	`bool`	If True, estimates missing values.	required
`scaling_method`	`str`	The scaling method to apply ('min_max', 'log', 'temporal', 'segmented', 'slope', 'cumulative').	required
`split_point`	`int`	Column index for temporal scaling.	required
`seg_points`	`list`	List of column indices for segmented scaling.	required

Returns:

Name	Type	Description
`full_hgnc_df`	`DataFrame`	DataFrame with scaled time-series data.
`interaction_df`	`DataFrame`	DataFrame containing interaction data.
`observed`	`DataFrame`	DataFrame containing observed data.

`apply_scaling(df, time_series_columns, method, split_point, segment_points)`

Function to apply different scaling methods to time-series data in a DataFrame.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	Input DataFrame containing time-series data.	required
`time_series_columns`	`list`	List of column names to scale.	required
`method`	`str`	Scaling method ('min_max', 'log', 'temporal', 'segmented', 'slope', 'cumulative').	required
`split_point`	`int`	Column index for temporal scaling.	required
`segment_points`	`list`	List of column indices for segmented scaling.	required

Returns:

Type	Description
	pd.DataFrame: DataFrame with scaled time-series data.

`create_report(results_dir: str, output_file: str = 'report.html')`

Creates a single global report HTML file from all gene folders inside the results directory.

Parameters:

Name	Type	Description	Default
`results_dir`	`str`	Path to the root result's directory.	required
`output_file`	`str`	Name of the generated global report file (placed inside results_dir).	`'report.html'`

Returns:

Type	Description
	None

`organize_output_files(*directories)`

Function to organize output files into protein-specific folders and a general folder.

Parameters:

Name	Type	Description	Default
`*directories`		List of directories to organize.	`()`

Returns:

Type	Description
	None

`kinopt.evol.utils.params`

`extract_parameters(P_initial, gene_psite_counts, K_index, optimized_params)`

Function to extract alpha and beta values from the optimized parameters.

Parameters:

Name	Type	Description	Default
`P_initial`	`dict`	Dictionary containing initial parameters for each gene-psite pair.	required
`gene_psite_counts`	`list`	List of counts for each gene-psite pair.	required
`K_index`	`dict`	Dictionary mapping kinases to their respective psite pairs.	required
`optimized_params`	`list`	List of optimized parameters.	required

Returns:

Name	Type	Description
`alpha_values`	`dict`	Dictionary containing alpha values for each gene-psite pair.
`beta_values`	`dict`	Dictionary containing beta values for each kinase-psite pair.

`compute_metrics(optimized_params: np.ndarray, P_initial: dict, P_initial_array: np.ndarray, K_index: dict, K_array: np.ndarray, gene_psite_counts: list, beta_counts: dict, n: int)`

Function to compute error metrics for the estimated series.

Parameters:

Name	Type	Description	Default
`optimized_params`	`list`	List of optimized parameters.	required
`P_initial`	`dict`	Dictionary containing initial parameters for each gene-psite pair.	required
`P_initial_array`	`ndarray`	Array of initial parameters.	required
`K_index`	`dict`	Dictionary mapping kinases to their respective psite pairs.	required
`K_array`	`ndarray`	Array of kinases.	required
`gene_psite_counts`	`list`	List of counts for each gene-psite pair.	required
`beta_counts`	`dict`	List of counts for each kinase-psite pair.	required
`n`	`int`	Number of samples.	required

Returns:

Name	Type	Description
`P_estimated`	`ndarray`	Estimated series.
`residuals`	`ndarray`	Residuals between initial and estimated series.
`mse`	`float`	Mean Squared Error.
`rmse`	`float`	Root Mean Squared Error.
`mae`	`float`	Mean Absolute Error.
`mape`	`float`	Mean Absolute Percentage Error.
`r_squared`	`float`	R-squared value.

Gradient-Based Algorithms

`kinopt.local.config.constants`

`parse_args()`

kinopt.local CLI. Defaults come from config.toml.

`kinopt.local.config.logconf`

`kinopt.local.exporter.plotout`

`format_timepoints(tp, tol=1e-09)`

Format timepoints with minimal decimals: - integers -> no decimal - non-integers -> one decimal

Parameters:

Name	Type	Description	Default
`tp`	`array - like`	Timepoints (list or np.ndarray)	required
`tol`	`float`	Tolerance for floating-point integer check	`1e-09`

Returns:

Type	Description
	list[str]: Formatted labels

`plot_fits_for_gene(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

Function to plot the observed and estimated phosphorylation levels for each psite of a gene.

Parameters:

Name	Type	Description	Default
`gene`	`str`	The name of the gene.	required
`gene_data`	`dict`	A dictionary containing observed and estimated data for each psite of the gene.	required
`real_timepoints`	`list`	A list of timepoints corresponding to the observed and estimated data.	required

`export_outcomes_to_csv(outcomes, csv_path)`

Export multistart optimization outcomes to CSV.

One row per start, scalar diagnostics only.

`plot_cumulative_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

Function to plot the cumulative residuals for each psite of a gene.

Parameters:

Name	Type	Description	Default
`gene`	`str`	The name of the gene.	required
`gene_data`	`dict`	A dictionary containing the residuals for each psite of the gene.	required
`real_timepoints`	`list`	A list of timepoints corresponding to the observed and estimated data.	required

`plot_autocorrelation_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

Function to plot the autocorrelation of residuals for each psite of a gene.

Parameters:

Name	Type	Description	Default
`gene`	`str`	The name of the gene.	required
`gene_data`	`dict`	A dictionary containing the residuals for each psite of the gene.	required
`real_timepoints`	`list`	A list of timepoints corresponding to the observed and estimated data.	required

`plot_histogram_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

Function to plot histograms of residuals for each psite of a gene.

Parameters:

Name	Type	Description	Default
`gene`	`str`	The name of the gene.	required
`gene_data`	`dict`	A dictionary containing the residuals for each psite of the gene.	required
`real_timepoints`	`list`	A list of timepoints corresponding to the observed and estimated data.	required

`plot_qqplot_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

Function to plot QQ plots of residuals for each psite of a gene.

Parameters:

Name	Type	Description	Default
`gene`	`str`	The name of the gene.	required
`gene_data`	`dict`	A dictionary containing the residuals for each psite of the gene.	required
`real_timepoints`	`list`	A list of timepoints corresponding to the observed and estimated data.	required

`plot_multistart_summary_runtime_overlay(summary_csv, out_path=None, figsize=(8, 8), x_col='rank', y_col='fun', c_col='runtime_s', success_col='success', cv_col='constr_violation', annotate_best=True)`

Read a multistart summary CSV and plot objective vs rank with point color = runtime.

Minimal, information-dense conventions: - x: rank (best -> worst) - y: final objective (fun) - color: runtime in seconds - optional: de-emphasize non-success / infeasible points (if columns exist)

Parameters:

Name	Type	Description	Default
`summary_csv`	`str \| Path`	Path to the multistart_summary.csv	required
`out_path`	`str \| Path \| None`	If provided, saves the figure (e.g. .png)	`None`
`figsize`	`tuple`	Figure size in inches	`(8, 8)`
`x_col, y_col, c_col`		Column names	required
`success_col, cv_col`		Optional columns for styling (used if present)	required
`annotate_best`	`bool`	Annotate the best run (rank=1 or min fun)	`True`

Returns:

Type	Description
`(fig, ax, df)`	Matplotlib figure/axis and the loaded DataFrame

`kinopt.local.exporter.sheetutils`

`format_timepoints(tp, tol=1e-09)`

Format timepoints with minimal decimals: - integers -> no decimal - non-integers -> one decimal

Parameters:

Name	Type	Description	Default
`tp`	`array - like`	Timepoints (list or np.ndarray)	required
`tol`	`float`	Tolerance for floating-point integer check	`1e-09`

Returns:

Type	Description
	list[str]: Formatted labels

`plot_fits_for_gene(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

Function to plot the observed and estimated phosphorylation levels for each psite of a gene.

Parameters:

Name	Type	Description	Default
`gene`	`str`	The name of the gene.	required
`gene_data`	`dict`	A dictionary containing observed and estimated data for each psite of the gene.	required
`real_timepoints`	`list`	A list of timepoints corresponding to the observed and estimated data.	required

`export_outcomes_to_csv(outcomes, csv_path)`

Export multistart optimization outcomes to CSV.

One row per start, scalar diagnostics only.

`plot_cumulative_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

Function to plot the cumulative residuals for each psite of a gene.

Parameters:

Name	Type	Description	Default
`gene`	`str`	The name of the gene.	required
`gene_data`	`dict`	A dictionary containing the residuals for each psite of the gene.	required
`real_timepoints`	`list`	A list of timepoints corresponding to the observed and estimated data.	required

`plot_autocorrelation_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

Function to plot the autocorrelation of residuals for each psite of a gene.

Parameters:

Name	Type	Description	Default
`gene`	`str`	The name of the gene.	required
`gene_data`	`dict`	A dictionary containing the residuals for each psite of the gene.	required
`real_timepoints`	`list`	A list of timepoints corresponding to the observed and estimated data.	required

`plot_histogram_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

Function to plot histograms of residuals for each psite of a gene.

Parameters:

Name	Type	Description	Default
`gene`	`str`	The name of the gene.	required
`gene_data`	`dict`	A dictionary containing the residuals for each psite of the gene.	required
`real_timepoints`	`list`	A list of timepoints corresponding to the observed and estimated data.	required

`plot_qqplot_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

Function to plot QQ plots of residuals for each psite of a gene.

Parameters:

Name	Type	Description	Default
`gene`	`str`	The name of the gene.	required
`gene_data`	`dict`	A dictionary containing the residuals for each psite of the gene.	required
`real_timepoints`	`list`	A list of timepoints corresponding to the observed and estimated data.	required

`plot_multistart_summary_runtime_overlay(summary_csv, out_path=None, figsize=(8, 8), x_col='rank', y_col='fun', c_col='runtime_s', success_col='success', cv_col='constr_violation', annotate_best=True)`

Read a multistart summary CSV and plot objective vs rank with point color = runtime.

Minimal, information-dense conventions: - x: rank (best -> worst) - y: final objective (fun) - color: runtime in seconds - optional: de-emphasize non-success / infeasible points (if columns exist)

Parameters:

Name	Type	Description	Default
`summary_csv`	`str \| Path`	Path to the multistart_summary.csv	required
`out_path`	`str \| Path \| None`	If provided, saves the figure (e.g. .png)	`None`
`figsize`	`tuple`	Figure size in inches	`(8, 8)`
`x_col, y_col, c_col`		Column names	required
`success_col, cv_col`		Optional columns for styling (used if present)	required
`annotate_best`	`bool`	Annotate the best run (rank=1 or min fun)	`True`

Returns:

Type	Description
`(fig, ax, df)`	Matplotlib figure/axis and the loaded DataFrame

`output_results(P_initial, P_init_dense, P_estimated, residuals, alpha_values, beta_values, result, mse, rmse, mae, mape, r_squared, filename=OUT_FILE, out_dir=OUT_DIR)`

Function to output the results of the optimization process.

Parameters:

Name	Type	Description	Default
`P_initial`	`dict`	Dictionary containing initial phosphorylation data.	required
`P_init_dense`	`ndarray`	Dense matrix of initial phosphorylation data.	required
`P_estimated`	`ndarray`	Dense matrix of estimated phosphorylation data.	required
`residuals`	`ndarray`	Dense matrix of residuals.	required
`alpha_values`	`dict`	Dictionary containing optimized alpha values.	required
`beta_values`	`dict`	Dictionary containing optimized beta values.	required
`result`	`OptimizeResult`	Result object from the optimization process.	required
`mse`	`float`	Mean Squared Error of the optimization.	required
`rmse`	`float`	Root Mean Squared Error of the optimization.	required
`mae`	`float`	Mean Absolute Error of the optimization.	required
`mape`	`float`	Mean Absolute Percentage Error of the optimization.	required
`r_squared`	`float`	R-squared value of the optimization.	required

`export_params_npz(outcomes, path)`

Export the optimized parameters to a compressed npz file.

Parameters:

Name	Type	Description	Default
`outcomes`	`list`	List of OptimizeResult objects.	required
`path`	`str`	Path to save the npz file.	required

`kinopt.local.objfn.minfn`

`kinopt.local.opt.optrun`

`StartOutcome` `dataclass`

Outcome of a single optimization start.

:param start_id: ID of the start. :param seed: Seed used for the start. :param result: Result of the optimization. :param optimized_params: Optimized parameters. :param fun: Objective function value. :param success: Whether the optimization was successful. :param constr_violation: Constraint violation. :param runtime_s: Runtime of the optimization.

`run_optimization(obj_fun, params_initial, opt_method, bounds, constraints)`

Run optimization using the specified method.

Parameters:

Name	Description	Default
`obj_fun`	Objective function to minimize.	required
`params_initial`	Initial parameters for the optimization.	required
`opt_method`	Optimization method to use (e.g., 'SLSQP', 'trust-constr').	required
`bounds`	Bounds for the parameters.	required
`constraints`	Constraints for the optimization.	required

Returns:

Name	Type	Description
`result`		Result of the optimization.
`optimized_params`		Optimized parameters.

`multistart_run_optimization(obj_fun, params_initial, opt_method, bounds, constraints, n_starts=24, n_jobs=-1, base_seed=1234, init_strategy='hybrid', jitter_scale=0.15, prefer_feasible=True, logger=None)`

Runs run_optimization multiple times in parallel and returns (best_result, best_params, outcomes).

Selection logic (sophisticated but simple): 1) If prefer_feasible: prefer (cv <= 0) or smallest constraint violation. 2) Then lowest objective. 3) Then success=True as tie-breaker. 4) Then shortest runtime as final tie-breaker.

Parameters:

Name	Description	Default
`obj_fun`	Objective function to optimize.	required
`params_initial`	Initial parameters for optimization.	required
`opt_method`	Optimization method to use (e.g., 'SLSQP', 'trust-constr').	required
`bounds`	Parameter bounds for optimization.	required
`constraints`	Constraints for optimization.	required
`n_starts`	Number of optimization starts to run (default: 24).	`24`
`n_jobs`	Number of parallel jobs to run. -1 means use all processors (default: -1).	`-1`
`base_seed`	Base seed for random number generation (default: 1234).	`1234`
`init_strategy`	Strategy for sampling initial parameters: 'jitter', 'uniform', or 'hybrid' (default: 'hybrid').	`'hybrid'`
`jitter_scale`	Scale for jittering initial parameters (default: 0.15).	`0.15`
`prefer_feasible`	If True, prefer feasible solutions over infeasible ones (default: True).	`True`
`logger`	Logger instance for logging messages (default: None).	`None`

Returns:

Name	Type	Description
`tuple`		A tuple containing: - best_result: The optimization result object with the best outcome. - best_params: The optimized parameters corresponding to the best result. - outcomes: List of StartOutcome objects for all optimization starts.

`kinopt.local.optcon.construct`

`load_geneid_to_psites(input1_path=INPUT1)`

Load the geneid to psite mapping from a CSV file.

Parameters:

Name	Type	Description	Default
`input1_path`	`str`	Path to the input CSV file containing geneid and psite information.	`INPUT1`

Returns: defaultdict: A dictionary mapping geneid to a set of psites.

`get_unique_kinases(input2_path=INPUT2)`

Extract unique kinases from the input CSV file.

Parameters:

Name	Type	Description	Default
`input2_path`	`str`	Path to the input CSV file containing kinase information.	`INPUT2`

Returns: set: A set of unique kinases.

`check_kinases()`

Check if kinases in input2.csv are present in input1.csv and log the results.

`kinopt.local.utils.iodata`

`format_duration(seconds)`

Formats a duration in seconds into a human-readable string. - If less than 60 seconds, returns in seconds. - If less than 3600 seconds, returns in minutes. - If more than 3600 seconds, returns in hours.

:param seconds: :return: Formatted string

`load_and_scale_data(estimate_missing, scaling_method, split_point, seg_points)`

Load and scale the data from the specified input files.

:param estimate_missing: :param scaling_method: :param split_point: :param seg_points: :return: Time series data, interaction data, observed data

`apply_scaling(df, cols, method, split_point, seg_points)`

Apply scaling to the specified columns of a DataFrame based on the given method. The scaling methods include: - 'min_max': Min-Max scaling - 'log': Logarithmic scaling - 'temporal': Temporal scaling (two segments) - 'segmented': Segmented scaling (multiple segments) - 'slope': Slope scaling - 'cumulative': Cumulative scaling

:param df: :param cols: :param method: :param split_point: :param seg_points: :return: df

`create_report(results_dir: str, output_file: str = 'report.html')`

Creates a single global report HTML file from all gene folders inside the results directory.

For each gene folder (e.g. "ABL2"), the report will include: - All PNG plots and interactive HTML plots displayed in a grid with three plots per row. - Each plot is confined to a fixed size of 900px by 900px. - Data tables from XLSX or CSV files in the gene folder are displayed below the plots, one per row.

Parameters:

Name	Type	Description	Default
`results_dir`	`str`	Path to the root results directory.	required
`output_file`	`str`	Name of the generated global report file (placed inside results_dir).	`'report.html'`

`organize_output_files(*directories)`

Function to organize output files into protein-specific folders. It moves files matching the pattern 'protein_name_*.{json,svg,png,html,csv,xlsx}' into a folder named after the protein (e.g., 'ABL2') and moves all other files into a 'General' folder within the same directory.

:param directories:

`kinopt.local.utils.params`

`extract_parameters(P_initial, gene_kinase_counts, total_alpha, unique_kinases, K_index, optimized_params)`

Extracts the alpha and beta parameters from the optimized parameters.

:param P_initial: :param gene_kinase_counts: :param total_alpha: :param unique_kinases: :param K_index: :param optimized_params: :return: Alpha and beta values as dictionaries

`compute_metrics(optimized_params, P_init_dense, t_max, gene_alpha_starts, gene_kinase_counts, gene_kinase_idx, total_alpha, kinase_beta_starts, kinase_beta_counts, K_data, K_indices, K_indptr)`

Computes the estimated series and various metrics based on the optimized parameters.

:param optimized_params: :param P_init_dense: :param t_max: :param gene_alpha_starts: :param gene_kinase_counts: :param gene_kinase_idx: :param total_alpha: :param kinase_beta_starts: :param kinase_beta_counts: :param K_data: :param K_indices: :param K_indptr: :return: Estimated series, residuals, MSE, RMSE, MAE, MAPE, R-squared

Fitting Analysis & Feasibility

`kinopt.fitanalysis.helpers.postfit`

`goodnessoffit(estimated, observed)`

Function to plot the goodness of fit and kullback-leibler divergence for estimated and observed values.

Parameters:

Name	Type	Description	Default
`estimated`	`DataFrame`	DataFrame containing estimated values.	required
`observed`	`DataFrame`	DataFrame containing observed values.	required

Returns:

Type	Description
	None

`reshape_alpha_beta(alpha_values, beta_values)`

Function to reshape alpha and beta values for plotting.

Parameters:

Name	Type	Description	Default
`alpha_values`	`DataFrame`	DataFrame containing alpha values.	required
`beta_values`	`DataFrame`	DataFrame containing beta values.	required

Returns: pd.DataFrame: Reshaped DataFrame containing both alpha and beta values.

`perform_pca(df)`

Function to perform PCA analysis on the given DataFrame.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	DataFrame containing the data for PCA analysis.	required

Returns:

Type	Description
	pd.DataFrame: DataFrame with PCA results and additional columns for type and gene/psite information.

`plot_pca(result_df_sorted, y_axis_column)`

Plot PCA or t-SNE results for each gene/psite. The function creates scatter plots with different markers for alpha and beta parameters, and adds labels for each point. The function also adjusts text labels to avoid overlap using the adjustText library.

:param result_df_sorted: DataFrame containing PCA or t-SNE results. :param y_axis_column: Column name for the y-axis values in the plot.

`perform_tsne(scaled_data, df)`

Perform t-SNE analysis on the given scaled data. The function returns a DataFrame with t-SNE results and additional columns for type and gene/psite information.

:param scaled_data: :param df:

:return: - pd.DataFrame: DataFrame with t-SNE results and additional columns.

`additional_plots(df, scaled_data, alpha_values, beta_values, residuals_df)`

Function to create additional plots including CDF, KDE, Boxplot, and Hierarchical Clustering.

:param df: :param scaled_data: :param alpha_values: :param beta_values: :param residuals_df:

`create_sankey_from_network(output_dir, data, title)`

Creates a Sankey diagram from the given data and saves it as an HTML file.

This function processes the input data to generate nodes and links for a Sankey diagram. It assigns colors to nodes and links based on their attributes and values, and uses Plotly to render the diagram. The resulting diagram is saved as an HTML file in the specified output directory.

:param output_dir: str The directory where the Sankey diagram HTML file will be saved. :param data: pd.DataFrame A DataFrame containing the data for the Sankey diagram. It must include the following columns: - 'Source': The source node of the link. - 'Target': The target node of the link. - 'Value': The value of the link, which determines the flow size. :param title: str The title of the Sankey diagram.

The function performs the following steps: 1. Initializes nodes and links for the Sankey diagram. 2. Maps node labels to indices and assigns colors to nodes. 3. Processes the data to create links between nodes, assigning colors based on link values. 4. Builds the Sankey diagram using Plotly. 5. Adds a color bar to explain the flow gradient. 6. Saves the Sankey diagram as an HTML file in the specified output directory.

`important_connections(output_dir, data, top_n=20)`

Extracts the top N most important connections based on their absolute values and saves them to a CSV file.

:param output_dir: str The directory where the CSV file will be saved. :param data: pd.DataFrame A DataFrame containing the connections with columns 'Source', 'Target', and 'Value'. :param top_n: int, optional The number of top connections to extract (default is 20).

The function sorts the connections by their absolute values in descending order, selects the top N connections, and saves them to a CSV file named 'top_connections.csv' in the specified output directory.

`kinopt.optimality.KKT`

`generate_latex_table(summary_dict, table_caption, table=None)`

Function to generate a LaTeX table from a summary dictionary.

Parameters:

Name	Type	Description	Default
`summary_dict`	`dict`	Dictionary containing summary data.	required
`table_caption`	`str`	Caption for the LaTeX table.	required
`table`	`str`	Optional existing LaTeX table to append to.	`None`

Returns:

Name	Type	Description
`str`		LaTeX formatted table as a string.

`print_primal_feasibility_results(primal_summary, alpha_violations, beta_violations, logger_obj=None)`

Logs the primal feasibility summary and violation details.

Parameters:

Name	Type	Description	Default
`primal_summary`	`dict`	Dictionary containing primal feasibility results.	required
`alpha_violations`	`dict`	Dictionary containing alpha constraint violations.	required
`beta_violations`	`dict`	Dictionary containing beta constraint violations.	required
`logger_obj`		Optional logger object to log the information.	`None`

`print_sensitivity_and_active_constraints(sensitivity_summary, active_constraints_summary, logger_obj=None)`

Logs the sensitivity summary and active constraints summary.

Parameters:

Name	Type	Description	Default
`sensitivity_summary`	`dict`	Dictionary containing sensitivity analysis results.	required
`active_constraints_summary`	`dict`	Dictionary containing active constraints summary.	required
`logger_obj`		Optional logger object to log the information.	`None`

`plot_constraint_violations(alpha_violations, beta_violations, out_dir)`

Function to plot constraint violations for alpha and beta values. It creates a stacked bar plot showing the violations for each protein. The top 5 proteins with the highest violations are highlighted in red.

Parameters:

Name	Type	Description	Default
`alpha_violations`	`Series`	Series containing alpha constraint violations.	required
`beta_violations`	`Series`	Series containing beta constraint violations.	required
`out_dir`	`str`	Directory to save the plot.	required

`plot_sensitivity_analysis(sensitivity_analysis, out_dir)`

Function to plot sensitivity analysis results. It creates a horizontal bar plot showing the mean, max, and min sensitivity for each protein.

Parameters:

Name	Type	Description	Default
`sensitivity_analysis`	`DataFrame`	DataFrame containing sensitivity analysis results.	required
`out_dir`	`str`	Directory to save the plot.	required

Returns:

Type	Description
	None

`process_excel_results(file_path=OUT_FILE)`

Function to process the Excel results file. It reads the alpha and beta values, estimated and observed values, validates normalization constraints, computes residuals and gradients, and generates LaTeX tables for the residuals and sensitivity summaries. It also performs sensitivity analysis and identifies high sensitivity sites. The results are returned as a dictionary.

Parameters:

Name	Type	Description	Default
`file_path`	`str`	Path to the Excel file containing results.	`OUT_FILE`

Returns: dict: Dictionary containing the processed results, including alpha and beta values, estimated and observed values, constraint violations, residuals summary, sensitivity summary, and high sensitivity sites.

`post_optimization_results()`

Function to process and visualize the results of the optimization.

Returns: dict: Dictionary containing the processed results, including alpha and beta values, estimated and observed values, constraint violations, residuals summary, sensitivity summary, and high sensitivity sites.

TF-mRNA Optimization

Evolutionary Algorithms

`tfopt.evol.config.constants`

`parse_args()`

tfopt.evol CLI: bounds, loss, optimizer selection. Defaults come from config.toml.

`tfopt.evol.config.logconf`

`tfopt.evol.exporter.plotout`

`plot_estimated_vs_observed(predictions, expression_matrix, gene_ids, time_points, regulators, tf_protein_matrix, tf_ids, num_targets, save_path=OUT_DIR)`

Plot the estimated vs observed expression levels for a set of genes.

Parameters:

Name	Type	Description	Default
`predictions`	`ndarray`	Predicted expression levels.	required
`expression_matrix`	`ndarray`	Observed expression levels.	required
`gene_ids`	`list`	List of gene identifiers.	required
`time_points`	`ndarray`	Time points for the experiments.	required
`regulators`	`ndarray`	Matrix of regulators for each gene.	required
`tf_protein_matrix`	`ndarray`	Matrix of TF protein levels.	required
`tf_ids`	`list`	List of TF identifiers.	required
`num_targets`	`int`	Number of target genes to plot.	required
`save_path`	`str`	Directory to save the plots.	`OUT_DIR`

`compute_predictions(x, regulators, protein_mat, psite_tensor, n_reg, T_use, n_mRNA, beta_start_indices, num_psites)`

Compute the predicted expression levels based on the optimization variables.

Parameters:

Name	Type	Description	Default
`x`	`ndarray`	Optimization variables.	required
`regulators`	`ndarray`	Matrix of regulators for each gene.	required
`protein_mat`	`ndarray`	Matrix of TF protein levels.	required
`psite_tensor`	`ndarray`	Tensor of phosphorylation sites.	required
`n_reg`	`int`	Number of regulators.	required
`T_use`	`int`	Number of time points to use.	required
`n_mRNA`	`int`	Number of mRNAs.	required
`beta_start_indices`	`list`	List of starting indices for beta parameters.	required
`num_psites`	`list`	List of number of phosphorylation sites for each TF.	required

`tfopt.evol.exporter.sheetutils`

`save_results_to_excel(gene_ids, tf_ids, final_alpha, final_beta, psite_labels_arr, expression_matrix, predictions, objective_value, reg_map, filename=OUT_FILE)`

Save the optimization results to an Excel file.

Parameters:

Name	Type	Description	Default
`gene_ids`	`list`	List of gene identifiers.	required
`tf_ids`	`list`	List of TF identifiers.	required
`final_alpha`	`ndarray`	Final alpha values.	required
`final_beta`	`ndarray`	Final beta values.	required
`psite_labels_arr`	`list`	List of phosphorylation site labels.	required
`expression_matrix`	`ndarray`	Observed expression levels.	required
`predictions`	`ndarray`	Predicted expression levels.	required
`objective_value`	`float`	Objective value from optimization.	required
`reg_map`	`dict`	Mapping of genes to regulators.	required
`filename`	`str`	Path to the output Excel file.	`OUT_FILE`

`tfopt.evol.objfn.minfn`

`TFOptimizationMultiObjectiveProblem`

Bases: Problem

Represents a multi-objective optimization problem specific to transcription factor (TF) and mRNA synthesis dynamics.

This class is an extension of the Problem class and is designed to model complex biological processes by incorporating various dynamic parameters like regulators, protein matrices, psite tensors, and associated configurations. It supports parallel evaluation for multi-thread usage, optimizing performance for large populations.

Attributes:

Name	Type	Description
`n_mRNA`	`int`	Number of mRNA species in the system.
`n_TF`	`int`	Number of transcription factor species in the system.
`n_reg`	`int`	Number of regulators.
`n_psite_max`	`int`	Maximum number of potential p-sites.
`n_alpha`	`int`	Number of alpha parameters used in modeling.
`T_use`	`int`	Number of time units or steps to use in the evaluation.
`mRNA_mat`	`ndarray`	A matrix representing the mRNA dynamics.
`regulators`	`ndarray`	Array of regulator IDs associated with mRNA and TF interactions.
`protein_mat`	`ndarray`	A matrix representing the protein synthesis rates or patterns.
`psite_tensor`	`ndarray`	A tensor indicating probabilistic binding sites of proteins.
`beta_start_indices`	`ndarray`	Array indicating the starting indices of beta coefficients.
`num_psites`	`ndarray`	Array indicating the number of p-sites per transcription factor.
`no_psite_tf`	`ndarray`	Boolean array indicating TFs with zero p-sites.
`loss_type`	`int`	Configurable loss function type for the optimization. Defaults to 0.
`lam1`	`float`	First regularization parameter for loss calculation. Defaults to 1e-3.
`lam2`	`float`	Second regularization parameter for loss calculation. Defaults to 1e-3.
`max_threads`	`int`	Maximum number of threads to use for evaluation. 0 indicates automatic thread selection based on system capacity.

`init(n_var: int, n_mRNA: int, n_TF: int, n_reg: int, n_psite_max: int, n_alpha: int, mRNA_mat: np.ndarray, regulators: np.ndarray, protein_mat: np.ndarray, psite_tensor: np.ndarray, T_use: int, beta_start_indices: np.ndarray, num_psites: np.ndarray, no_psite_tf: np.ndarray, xl: Optional[np.ndarray] = None, xu: Optional[np.ndarray] = None, **kwargs)`

Initializes the class with various parameters required for computational evaluation.

Parameters:

Name	Type	Description	Default
`n_var`	`int`	The number of variables.	required
`n_mRNA`	`int`	The number of mRNA molecules.	required
`n_TF`	`int`	The number of transcription factors (TFs).	required
`n_reg`	`int`	The number of regulators.	required
`n_psite_max`	`int`	The maximum number of p-sites.	required
`n_alpha`	`int`	The number of alpha coefficients.	required
`mRNA_mat`	`ndarray`	Matrix representing the mRNA data.	required
`regulators`	`ndarray`	Array representing the regulator mappings.	required
`protein_mat`	`ndarray`	Matrix representing the protein data.	required
`psite_tensor`	`ndarray`	Tensor representing the p-site data.	required
`T_use`	`int`	The time step or usage parameter.	required
`beta_start_indices`	`ndarray`	Array of start indices for beta calculations.	required
`num_psites`	`ndarray`	Array representing the number of p-sites.	required
`no_psite_tf`	`ndarray`	Boolean array indicating TFs with no associated p-sites.	required
`xl`	`Optional[ndarray]`	Optional lower-bound array for the variables.	`None`
`xu`	`Optional[ndarray]`	Optional upper-bound array for the variables.	`None`
`**kwargs`		Additional optional arguments such as "loss_type", "lam1", "lam2", and "threads".	`{}`

`tfopt.evol.opt.optrun`

`run_optimization(problem, total_dim, optimizer)`

Execute multi-objective optimization using the specified algorithm.

This function configures and runs one of three multi-objective evolutionary algorithms (UNSGA3, SMSEMOA, or AGEMOEA) on the provided optimization problem. The algorithm is configured with appropriate genetic operators (two-point crossover and polynomial mutation) and terminated after 1000 generations.

Parameters:

Name	Type	Description	Default
`problem`	`Problem`	The pymoo Problem instance defining the optimization problem, including objectives, constraints, and variable bounds.	required
`total_dim`	`int`	Total number of decision variables (dimensions) in the optimization problem. Used to determine population size and mutation probability.	required
`optimizer`	`int`	Selector for the optimization algorithm: - 0: UNSGA3 (Unified NSGA-III) - Reference direction-based algorithm - 1: SMSEMOA - S-Metric Selection Evolutionary Multi-objective Algorithm - 2: AGEMOEA - Adaptive Geometry Estimation-based Multi-objective Evolutionary Algorithm	required

Returns:

Name	Type	Description
`Result`		A pymoo Result object containing the optimization outcomes, including: - X: Decision variables of the Pareto-optimal solutions - F: Objective function values of the Pareto-optimal solutions - algorithm: The algorithm instance used - Additional statistics and convergence information

Notes

Population size is set to 2 * total_dim (or larger for UNSGA3 if needed)
Crossover probability: 0.9
Mutation probability: 1.0 / total_dim
Mutation distribution index (eta): 20
Termination: Fixed at 1000 generations
Random seed: 1 (for reproducibility)
Duplicate elimination is enabled for all algorithms
UNSGA3 automatically adjusts population size to match reference directions

`tfopt.evol.optcon.construct`

`build_fixed_arrays(mRNA_ids, mRNA_mat, TF_ids, protein_dict, psite_dict, psite_labels_dict, reg_map)`

Builds fixed-shape arrays from the input data.

Parameters:

Name	Type	Description	Default
`mRNA_ids`	`list`	List of mRNA identifiers.	required
`mRNA_mat`	`ndarray`	Matrix of mRNA expression levels.	required
`TF_ids`	`list`	List of TF identifiers.	required
`protein_dict`	`dict`	Dictionary mapping TFs to their protein levels.	required
`psite_dict`	`dict`	Dictionary mapping TFs to their phosphorylation sites.	required
`psite_labels_dict`	`dict`	Dictionary mapping TFs to their phosphorylation site labels.	required
`reg_map`	`dict`	Mapping of genes to their regulators.	required

Returns: mRNA_mat (np.ndarray): Matrix of mRNA expression levels. regulators (np.ndarray): Matrix of regulators for each mRNA. protein_mat (np.ndarray): Matrix of TF protein levels. psite_tensor (np.ndarray): Tensor of phosphorylation sites. n_reg (int): Number of regulators. n_psite_max (int): Maximum number of phosphorylation sites across all TFs. psite_labels_arr (list): List of phosphorylation site labels for each TF. num_psites (np.ndarray): Array indicating the number of phosphorylation sites for each TF.

`tfopt.evol.optcon.filter`

`load_raw_data()`

Load raw data from files.

Returns:

Name	Type	Description
`mRNA_ids`		List of mRNA gene identifiers.
`mRNA_mat`		Matrix of mRNA expression data.
`mRNA_time_cols`		Time points for mRNA data.
`TF_ids`		List of transcription factor identifiers.
`protein_dict`		Dictionary mapping TF_ids to their protein data.
`psite_dict`		Dictionary mapping TF_ids to their phosphorylation site data.
`psite_labels_dict`		Dictionary mapping TF_ids to their phosphorylation site labels.
`TF_time_cols`		Time points for TF data.
`reg_map`		Regulation map, mapping mRNA genes to their regulators.

`filter_mrna(mRNA_ids, mRNA_mat, reg_map)`

Filter mRNA genes to only those with regulators present in the regulation map.

Parameters:

Name	Type	Description	Default
`mRNA_ids`	`list`	List of mRNA gene identifiers.	required
`mRNA_mat`	`ndarray`	Matrix of mRNA expression data.	required
`reg_map`	`dict`	Regulation map, mapping mRNA genes to their regulators.	required

Returns:

Name	Type	Description
`filtered_mRNA_ids`	`list`	List of filtered mRNA gene identifiers.
`filtered_mRNA_mat`	`ndarray`	Matrix of filtered mRNA expression data.

`update_regulations(mRNA_ids, reg_map, TF_ids)`

Update the regulation map to only include relevant transcription factors.

Parameters:

Name	Type	Description	Default
`mRNA_ids`	`list`	List of mRNA gene identifiers.	required
`reg_map`	`dict`	Regulation map, mapping mRNA genes to their regulators.	required
`TF_ids`	`list`	List of transcription factor identifiers.	required

Returns:

Name	Type	Description
`relevant_TFs`	`set`	Set of relevant transcription factors.

`filter_TF(TF_ids, protein_dict, psite_dict, psite_labels_dict, relevant_TFs)`

Filter transcription factors to only those present in the relevant_TFs set.

Parameters:

Name	Type	Description	Default
`TF_ids`	`list`	List of transcription factor identifiers.	required
`protein_dict`	`dict`	Dictionary mapping TF_ids to their protein data.	required
`psite_dict`	`dict`	Dictionary mapping TF_ids to their phosphorylation site data.	required
`psite_labels_dict`	`dict`	Dictionary mapping TF_ids to their phosphorylation site labels.	required
`relevant_TFs`	`set`	Set of relevant transcription factors.	required

Returns:

Name	Type	Description
`TF_ids_filtered`	`list`	List of filtered transcription factor identifiers.
`protein_dict`	`dict`	Filtered dictionary mapping TF_ids to their protein data.
`psite_dict`	`dict`	Filtered dictionary mapping TF_ids to their phosphorylation site data.
`psite_labels_dict`	`dict`	Filtered dictionary mapping TF_ids to their phosphorylation site labels.

`determine_T_use(mRNA_mat, TF_time_cols)`

Determine the number of time points to use for the analysis.

Parameters:

Name	Type	Description	Default
`mRNA_mat`	`ndarray`	Matrix of mRNA expression data.	required
`TF_time_cols`	`list`	Time points for TF data.	required

`tfopt.evol.utils.iodata`

`load_mRNA_data(filename=INPUT3)`

Load mRNA data from a CSV file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Path to the CSV file containing mRNA data.	`INPUT3`

Returns: - mRNA_ids: List of mRNA gene identifiers (strings). - mRNA_mat: Matrix of mRNA expression data (numpy array). - time_cols: List of time columns (excluding "GeneID").

`load_TF_data(filename=INPUT1)`

Load TF data from a CSV file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Path to the CSV file containing TF data.	`INPUT1`

Returns: - TF_ids: List of TF identifiers (strings). - protein_dict: Dictionary mapping TF identifiers to their protein data (numpy array). - psite_dict: Dictionary mapping TF identifiers to their phosphorylation site data (list of numpy arrays). - psite_labels_dict: Dictionary mapping TF identifiers to their phosphorylation site labels (list of strings). - time_cols: List of time columns (excluding "GeneID" and "Psite").

`load_regulation(filename=INPUT4)`

Load regulation data from a CSV file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Path to the CSV file containing regulation data.	`INPUT4`

Returns: - reg_map: Dictionary mapping mRNA genes to their regulators (list of TF identifiers).

`create_report(results_dir: str, output_file: str = 'report.html')`

Creates a single global report HTML file from all gene folders inside the results directory.

Parameters:

Name	Type	Description	Default
`results_dir`	`str`	Path to the directory containing gene folders.	required

`organize_output_files(*directories)`

Organizes output files from multiple directories into separate folders for each protein.

Parameters:

Name	Type	Description	Default
`directories`	`str`	List of directories to organize.	`()`

`format_duration(seconds)`

Format a duration in seconds into a human-readable string.

Parameters:

Name	Type	Description	Default
`seconds`	`float`	Duration in seconds.	required

Returns: str: Formatted duration string.

`tfopt.evol.utils.params`

`create_no_psite_array(n_TF, num_psites, psite_labels_arr)`

Create an array indicating whether each TF has no phosphorylation sites.

Parameters:

Name	Type	Description	Default
`n_TF`	`int`	Number of transcription factors.	required
`num_psites`	`list`	List of number of phosphorylation sites for each TF.	required
`psite_labels_arr`	`list`	List of phosphorylation site labels for each TF.	required

Returns:

Name	Type	Description
`no_psite_tf`	`ndarray`	Array indicating whether each TF has no phosphorylation sites.

`compute_beta_indices(num_psites, n_TF)`

Compute the starting indices for the beta parameters for each TF.

Parameters:

Name	Type	Description	Default
`num_psites`	`list`	List of number of phosphorylation sites for each TF.	required
`n_TF`	`int`	Number of transcription factors.	required

Returns:

Name	Type	Description
`beta_start_indices`	`ndarray`	Array of starting indices for the beta parameters.
`cum`	`int`	Total number of beta parameters.

`create_initial_guess(n_mRNA, n_reg, n_TF, num_psites, no_psite_tf)`

Create the initial guess for the optimization variables.

Parameters:

Name	Type	Description	Default
`n_mRNA`	`int`	Number of mRNAs.	required
`n_reg`	`int`	Number of regulators.	required
`n_TF`	`int`	Number of transcription factors.	required
`num_psites`	`list`	List of number of phosphorylation sites for each TF.	required
`no_psite_tf`	`ndarray`	Array indicating whether each TF has no phosphorylation sites.	required

Returns:

Name	Type	Description
`x0`	`ndarray`	Initial guess for the optimization variables.
`n_alpha`	`int`	Number of alpha parameters.

`create_bounds(n_alpha, n_beta_total, lb, ub)`

Create the lower and upper bounds for the optimization variables.

Parameters:

Name	Type	Description	Default
`n_alpha`	`int`	Number of alpha parameters.	required
`n_beta_total`	`int`	Total number of beta parameters.	required
`lb`	`float`	Lower bound for the optimization variables.	required
`ub`	`float`	Upper bound for the optimization variables.	required

Returns:

Name	Type	Description
`xl`	`ndarray`	Lower bounds for the optimization variables.
`xu`	`ndarray`	Upper bounds for the optimization variables.

`get_parallel_runner()`

Get a parallel runner for multi-threading.

Returns:

Name	Type	Description
`runner`		Parallelization runner.
`pool`		ThreadPool instance for parallel execution.

`extract_best_solution(res, n_alpha, n_mRNA, n_reg, n_TF, num_psites, beta_start_indices)`

Extract the best solution from the optimization results.

Parameters:

Name	Type	Description	Default
`res`		Optimization results.	required
`n_alpha`	`int`	Number of alpha parameters.	required
`n_mRNA`	`int`	Number of mRNAs.	required
`n_reg`	`int`	Number of regulators.	required
`n_TF`	`int`	Number of transcription factors.	required
`num_psites`	`list`	List of number of phosphorylation sites for each TF.	required
`beta_start_indices`	`ndarray`	Array of starting indices for the beta parameters.	required

Returns:

Name	Type	Description
`final_alpha`	`ndarray`	Final alpha parameters.
`final_beta`	`ndarray`	Final beta parameters.
`best_objectives`	`ndarray`	Best objectives from the Pareto front.
`final_x`	`ndarray`	Final optimization variables.

`print_alpha_mapping(mRNA_ids, reg_map, TF_ids, final_alpha)`

Print the mapping of transcription factors (TFs) to mRNAs with their corresponding alpha values.

Parameters:

Name	Type	Description	Default
`mRNA_ids`	`list`	List of mRNA identifiers.	required
`reg_map`	`dict`	Mapping of genes to their regulators.	required
`TF_ids`	`list`	List of TF identifiers.	required
`final_alpha`	`ndarray`	Final alpha parameters (mRNA x TF).	required

`print_beta_mapping(TF_ids, final_beta, psite_labels_arr)`

Print the mapping of transcription factors (TFs) to their beta parameters.

Parameters:

Name	Type	Description	Default
`TF_ids`	`list`	List of TF identifiers.	required
`final_beta`	`ndarray`	Final beta parameters (TF x β).	required
`psite_labels_arr`	`list`	List of phosphorylation site labels for each TF.	required

Gradient-Based Algorithms

`tfopt.local.config.constants`

`parse_args()`

tfopt.local CLI: bounds and loss selection. Defaults come from config.toml.

`tfopt.local.config.logconf`

`tfopt.local.exporter.plotout`

`plot_estimated_vs_observed(predictions, expression_matrix, gene_ids, time_points, regulators, tf_protein_matrix, tf_ids, num_targets, save_path=OUT_DIR)`

Plots the estimated vs observed values for a given set of genes and their corresponding TFs.

Parameters:

Name	Type	Description	Default
`predictions`	`ndarray`	Predicted expression levels.	required
`expression_matrix`	`ndarray`	Observed expression levels.	required
`gene_ids`	`list`	List of gene identifiers.	required
`time_points`	`ndarray`	Time points for the experiments.	required
`regulators`	`ndarray`	Matrix of regulators for each gene.	required
`tf_protein_matrix`	`ndarray`	Matrix of TF protein levels.	required
`tf_ids`	`list`	List of TF identifiers.	required
`num_targets`	`int`	Number of target genes to plot.	required
`save_path`	`str`	Directory to save the plots.	`OUT_DIR`

`plot_multistart_summary_runtime_overlay(summary_csv, out_path=None, figsize=(8, 8), x_col='rank', y_col='fun', c_col='runtime_s', success_col='success', cv_col='constr_violation', annotate_best=True)`

Creates a scatter plot visualizing multi-start optimization results with runtime overlay.

This function reads a CSV summary of multiple optimization runs and generates a scatter plot showing the relationship between run rank and final objective value, with runtime (or iterations) represented as color intensity. Successful and feasible runs are emphasized while unsuccessful or infeasible runs are shown with reduced opacity.

Parameters:

Name	Type	Description	Default
`summary_csv`	`str or Path`	Path to the CSV file containing multi-start optimization results.	required
`out_path`	`str or Path`	Path to save the output figure. If None, figure is not saved. Defaults to None.	`None`
`figsize`	`tuple`	Figure size as (width, height) in inches. Defaults to (8, 8).	`(8, 8)`
`x_col`	`str`	Column name for x-axis (run rank). If missing, will be created from y_col ranking. Defaults to "rank".	`'rank'`
`y_col`	`str`	Column name for y-axis (final objective value). Defaults to "fun".	`'fun'`
`c_col`	`str`	Column name for color mapping (typically runtime). Falls back to "nit" (iterations) if not found. Defaults to "runtime_s".	`'runtime_s'`
`success_col`	`str`	Column name indicating optimization success status. Defaults to "success".	`'success'`
`cv_col`	`str`	Column name for constraint violation values. Falls back to common alternatives if not found. Defaults to "constr_violation".	`'constr_violation'`
`annotate_best`	`bool`	Whether to annotate the best (rank 1) point on the plot. Defaults to True.	`True`

Returns:

Name	Type	Description
`tuple`		A tuple containing: - fig (matplotlib.figure.Figure): The generated figure object. - ax (matplotlib.axes.Axes): The axes object of the plot. - df (pd.DataFrame): The processed DataFrame with sorted results.

Notes

Points are considered feasible if constraint violation <= 1e-8
Infeasible or unsuccessful runs are plotted with reduced opacity (0.25)
If rank column is missing, it's automatically generated from objective values
If runtime column is missing, falls back to iteration count or constant color

`tfopt.local.exporter.sheetutils`

`save_results_to_excel(gene_ids, tf_ids, final_alpha, final_beta, psite_labels_arr, expression_matrix, predictions, objective_value, reg_map, filename=OUT_FILE)`

Save the optimization results to an Excel file.

Parameters:

Name	Type	Description	Default
`gene_ids`	`list`	List of gene identifiers.	required
`tf_ids`	`list`	List of TF identifiers.	required
`final_alpha`	`ndarray`	Final alpha values.	required
`final_beta`	`ndarray`	Final beta values.	required
`psite_labels_arr`	`list`	List of phosphorylation site labels.	required
`expression_matrix`	`ndarray`	Observed expression levels.	required
`predictions`	`ndarray`	Predicted expression levels.	required
`objective_value`	`float`	Objective value from optimization.	required
`reg_map`	`dict`	Mapping of genes to regulators.	required
`filename`	`str`	Path to the output Excel file.	`OUT_FILE`

`export_multistart_results(results)`

Export multiple multistart optimization results to an Excel file.

Parameters:

Name	Type	Description	Default
`results`	`list`	List of optimization results, each containing attributes like 'start_id', 'fun', 'success', etc.	required

Returns:

Type	Description
	None

`save_multistart_solutions_npz(all_results, out_path)`

Saves multistart optimization solutions to a compressed .npz file format.

This function aggregates optimization results into a structured format and saves them in a compressed NumPy .npz file. It processes the solutions, extracting relevant attributes such as optimization variables, function values, success status, and starting IDs, before saving them for later use.

Parameters:

Name	Type	Description	Default
`all_results`		list A list of optimization result objects. Each result object must have the attributes `x` (optimization solution vector) and `fun` (objective function value). Optionally, it can have `success` (indicating whether the optimization succeeded, defaults to False if not present) and `start_id` (identifier of the starting point, defaults to -1 if not present).	required
`out_path`		str or Path The file path where the compressed .npz file will be saved. The path will be converted into a pathlib Path object if it is not already one.	required

`tfopt.local.objfn.minfn`

`objective_(x, expression_matrix, regulators, tf_protein_matrix, psite_tensor, n_reg, T_use, n_genes, beta_start_indices, num_psites, loss_type, lam1=1e-06, lam2=1e-06)`

Originally implemented by Julius Normann.

This version has been modified and optimized for consistency & speed in submodules by Abhinav Mishra.

Computes a loss value using one of several loss functions.

Parameters:

Name	Description	Default
`x`	Decision vector.	required
`expression_matrix`	(n_genes x T_use) measured gene expression values.	required
`regulators`	(n_genes x n_reg) indices of TF regulators for each gene.	required
`tf_protein_matrix`	(n_TF x T_use) TF protein time series.	required
`psite_tensor`	(n_TF x n_psite_max x T_use) matrix of PSite signals (padded with zeros).	required
`n_reg`	Maximum number of regulators per gene.	required
`T_use`	Number of time points used.	required
`n_genes, n_TF`	Number of genes and TF respectively.	required
`beta_start_indices`	Integer array giving the starting index (in the β–segment) for each TF.	required
`num_psites`	Integer array with the actual number of PSites for each TF.	required
`loss_type`	Integer indicating the loss type (0: MSE, 1: MAE, 2: soft L1, 3: Cauchy, 4: Arctan, 5: Elastic Net, 6: Tikhonov).	required

Returns:

Name	Type	Description
`loss`		The computed loss (a scalar).

`compute_predictions(x, regulators, tf_protein_matrix, psite_tensor, n_reg, T_use, n_genes, beta_start_indices, num_psites)`

Computes the predicted expression matrix based on the decision vector x.

Parameters:

Name	Description	Default
`x`	Decision vector.	required
`regulators`	(n_genes x n_reg) indices of TF regulators for each gene.	required
`tf_protein_matrix`	(n_TF x T_use) TF protein time series.	required
`psite_tensor`	(n_TF x n_psite_max x T_use) matrix of PSite signals (padded with zeros).	required
`n_reg`	Maximum number of regulators per gene.	required
`T_use`	Number of time points used.	required
`n_genes`	Number of genes.	required
`beta_start_indices`	Integer array giving the starting index (in the β–segment) for each TF.	required
`num_psites`	Integer array with the actual number of PSites for each TF.	required

Returns:

Name	Type	Description
`predictions`		(n_genes x T_use) predicted gene expression values.

`objective_wrapper(x, expression_matrix, regulators, tf_protein_matrix, psite_tensor, n_reg, T_use, n_genes, beta_start_indices, num_psites, loss_type)`

Wrapper function for the objective function.

Parameters:

Name	Description	Default
`x`	Decision vector.	required
`expression_matrix`	(n_genes x T_use) measured gene expression values.	required
`regulators`	(n_genes x n_reg) indices of TF regulators for each gene.	required
`tf_protein_matrix`	(n_TF x T_use) TF protein time series.	required
`psite_tensor`	(n_TF x n_psite_max x T_use) matrix of PSite signals (padded with zeros).	required
`n_reg`	Maximum number of regulators per gene.	required
`T_use`	Number of time points used.	required
`n_genes`	Number of genes.	required
`beta_start_indices`	Integer array giving the starting index (in the β–segment) for each TF.	required
`num_psites`	Integer array with the actual number of PSites for each TF.	required
`loss_type`	Integer indicating the loss type.	required

Returns:

Name	Type	Description
`loss`		The computed loss (a scalar).

`tfopt.local.opt.optrun`

`run_optimizer(x0, bounds, lin_cons, expression_matrix, regulators, tf_protein_matrix, psite_tensor, n_reg, T_use, n_genes, beta_start_indices, num_psites, loss_type)`

Runs the optimization algorithm to minimize the objective function.

Parameters:

Name	Description	Default
`x0`	Initial guess for the optimization variables.	required
`bounds`	Bounds for the optimization variables.	required
`lin_cons`	Linear constraints for the optimization problem.	required
`expression_matrix`	(n_genes x T_use) measured gene expression values.	required
`regulators`	(n_genes x n_reg) indices of TF regulators for each gene.	required
`tf_protein_matrix`	(n_TF x T_use) TF protein time series.	required
`psite_tensor`	(n_TF x n_psite_max x T_use) matrix of PSite signals (padded with zeros).	required
`n_reg`	Maximum number of regulators per gene.	required
`T_use`	Number of time points used.	required
`n_genes, n_TF`	Number of genes and TF respectively.	required
`beta_start_indices`	Integer array giving the starting index (in the β–segment) for each TF.	required
`num_psites`	Integer array with the actual number of PSites for each TF.	required
`loss_type`	Type of loss function to use.	required

Returns: result : Result of the optimization process, including the optimized parameters and objective value.

`generate_multistart_x0(x0: np.ndarray, bounds: Sequence[Tuple[float, float]], n_starts: int, seed: int = 0, jitter_frac: float = 0.05, p_random: float = 0.3) -> List[np.ndarray]`

Generates multiple starting points for multi-start optimization.

Builds a diverse list of starting points

mostly: jitter around baseline x0
some: fully random within bounds

jitter_frac is relative to (ub - lb). p_random is fraction of starts that are random-in-bounds.

Returns:

Type	Description
`List[ndarray]`	List[np.ndarray]: A list of starting points for optimization.

`run_optimizer_multistart(x0: np.ndarray, bounds, lin_cons, expression_matrix, regulators, tf_protein_matrix, psite_tensor, n_reg, T_use, n_genes, beta_start_indices, num_psites, loss_type, run_optimizer_func, cfg: Optional[MultiStartConfig] = None, polish: bool = True)`

Executes a multistart optimization loop with parallelization and optional polishing to find the best solution across multiple starting points. The function leverages a parallel approach for running multiple optimizations, selects the best result based on predefined sorting criteria, and optionally refines it.

Parameters:

Name	Type	Description	Default
`x0`	`ndarray`	Initial guess for the optimization variables.	required
`bounds`		Bounds for the optimization variables, typically a sequence of (min, max) pairs.	required
`lin_cons`		Linear constraints for the optimizer, defined as per specific optimizer requirements.	required
`expression_matrix`		Input gene expression data utilized in the optimization process.	required
`regulators`		Regulatory inputs or factors influencing the optimization process.	required
`tf_protein_matrix`		Matrix representing transcription factor proteins relevant to the process.	required
`psite_tensor`		Tensor containing phosphorylation site data used in the computations.	required
`n_reg`		Number of regulators involved in the optimization.	required
`T_use`		Specific configuration parameter determining time or iteration usage.	required
`n_genes`		Number of genes considered within the problem scope.	required
`beta_start_indices`		Indices indicating the start positions of beta parameters in the optimization.	required
`num_psites`		Total number of phosphorylation sites accounted for in optimization.	required
`loss_type`		Type of loss function used for evaluating optimization performance.	required
`run_optimizer_func`		Optimization function to be executed for each starting point.	required
`cfg`	`Optional[MultiStartConfig]`	Configuration object specifying multistart parameters such as number of starts, parallelization settings, and randomness.	`None`
`polish`	`bool`	Indicates whether to perform a final optimization run initialized at the best solution. Defaults to True.	`True`

Returns:

Name	Type	Description
`Tuple`		A tuple containing: - The best result as determined by sorting criteria. - A list of sorted optimization results from all starting points.

`tfopt.local.optcon.construct`

`build_fixed_arrays(gene_ids, expression_matrix, tf_ids, tf_protein, tf_psite_data, tf_psite_labels, reg_map)`

Builds fixed-shape arrays from the input data.

Parameters:

Name	Description	Default
`- gene_ids`	list of mRNA identifiers.	required
`- expression_matrix`	array of shape (n_genes, T) with mRNA expression levels.	required
`- tf_ids`	list of TF identifiers.	required
`- tf_protein`	dict mapping TFs to their protein levels.	required
`- tf_psite_data`	dict mapping TFs to their phosphorylation sites.	required
`- tf_psite_labels`	dict mapping TFs to their phosphorylation site labels.	required
`- reg_map`	mapping of genes to their regulators (TFs).	required

Returns:

Type	Description
	expression_matrix: array of shape (n_genes, T) with mRNA expression levels.
	regulators: array of shape (n_genes, n_reg) with TF indices.
	tf_protein_matrix: array of shape (n_TF, T) with TF protein levels.
	psite_tensor: array of shape (n_TF, n_psite_max, T) with phosphorylation sites.
	n_reg: number of regulators.
	n_psite_max: maximum number of phosphorylation sites across all TFs.
	psite_labels_arr: list of labels for each TF's phosphorylation sites.
	num_psites: array indicating the number of phosphorylation sites for each TF.

`constraint_alpha_func(x, n_genes, n_reg)`

For each gene, the sum of its alpha parameters must equal 1.

Parameters:

Name	Type	Description	Default
`x`	`ndarray`	Decision vector.	required
`n_genes`	`int`	Number of genes.	required
`n_reg`	`int`	Number of regulators.	required

Returns:

Type	Description
	np.ndarray: Array of constraints.

`constraint_beta_func(x, n_alpha, n_TF, beta_start_indices, num_psites, no_psite_tf)`

For each TF, the sum of its beta parameters must equal 1.

Parameters:

Name	Type	Description	Default
`x`	`ndarray`	Decision vector.	required
`n_alpha`	`int`	Number of alpha parameters.	required
`n_TF`	`int`	Number of transcription factors.	required
`beta_start_indices`	`list`	List of starting indices for beta parameters.	required
`num_psites`	`list`	List of number of phosphorylation sites for each TF.	required
`no_psite_tf`	`list`	List indicating if a TF has no phosphorylation site.	required

Returns:

Type	Description
	np.ndarray: Array of constraints.

`build_linear_constraints(n_genes, n_TF, n_reg, n_alpha, beta_start_indices, num_psites, no_psite_tf)`

Build linear constraints for the transcription factor optimization problem.

Parameters:

Name	Type	Description	Default
`n_genes`	`int`	Number of genes.	required
`n_TF`	`int`	Number of transcription factors.	required
`n_reg`	`int`	Number of regulators.	required
`n_alpha`	`int`	Number of alpha parameters.	required
`beta_start_indices`	`list`	List of starting indices for beta parameters.	required
`num_psites`	`list`	List of number of phosphorylation sites for each TF.	required
`no_psite_tf`	`list`	List indicating if a TF has no phosphorylation site.	required

Returns:

Name	Type	Description
`list`		List of linear constraints.

`tfopt.local.optcon.filter`

`load_and_filter_data()`

Load and filter data for the optimization problem.

Returns:

Type	Description
	gene_ids (list): List of gene IDs.
	expr_matrix (np.ndarray): Gene expression matrix.
	expr_time_cols (list): Time columns for expression data.
	tf_ids (list): List of transcription factor IDs.
	tf_protein (dict): Dictionary mapping TF IDs to their protein data.
	tf_psite_data (dict): Dictionary mapping TF IDs to their phosphorylation site data.
	tf_psite_labels (dict): Dictionary mapping TF IDs to their phosphorylation site labels.
	tf_time_cols (list): Time columns for TF data.
	reg_map (dict): Regulation map, mapping gene IDs to their regulators.

`prepare_data(gene_ids, expr_matrix, tf_ids, tf_protein, tf_psite_data, tf_psite_labels, tf_time_cols, reg_map)`

Prepares the data for optimization by filtering the expression matrix to match the number of time points and building fixed arrays.

Parameters:

Name	Type	Description	Default
`gene_ids`	`list`	List of gene IDs.	required
`expr_matrix`	`ndarray`	Gene expression matrix.	required
`tf_ids`	`list`	List of transcription factor IDs.	required
`tf_protein`	`dict`	Dictionary mapping TF IDs to their protein data.	required
`tf_psite_data`	`dict`	Dictionary mapping TF IDs to their phosphorylation site data.	required
`tf_psite_labels`	`dict`	Dictionary mapping TF IDs to their phosphorylation site labels.	required
`tf_time_cols`	`list`	Time columns for TF data.	required
`reg_map`	`dict`	Regulation map, mapping gene IDs to their regulators.	required

Returns: fixed_arrays (tuple): Tuple containing the fixed arrays: - expression_matrix: array of shape (n_genes, T) - regulators: array of shape (n_genes, n_reg) with indices into tf_ids. - tf_protein_matrix: array of shape (n_TF, T) - psite_tensor: array of shape (n_TF, n_psite_max, T), padded with zeros. - n_reg: maximum number of regulators per gene. - n_psite_max: maximum number of PSites among TFs. - psite_labels_arr: list (length n_TF) of lists of PSite names (padded with empty strings). - num_psites: array of length n_TF with the actual number of PSites for each TF. T_use (int): Number of time points used in the expression matrix.

`tfopt.local.utils.iodata`

`min_max_normalize(df, custom_max=None)`

Row-wise (per-sample) min-max normalize time-series columns starting with 'x'.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	Input DataFrame with time-series columns (x1-xN).	required
`custom_max`	`float`	If given, used as max for all rows.	`None`

Returns:

Type	Description
	pd.DataFrame: Normalized DataFrame with same shape.

`load_expression_data(filename=INPUT3)`

Loads gene expression (mRNA) data.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Path to the CSV file containing mRNA data.	`INPUT3`

Returns:

Type	Description
	gene_ids: List of gene identifiers (strings).
	expression_matrix: Matrix of gene expression data (numpy array).
	time_cols: List of time columns (excluding "GeneID").

`load_tf_protein_data(filename=INPUT1)`

Loads TF protein data along with PSite information.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Path to the CSV file containing TF protein data.	`INPUT1`

Returns: - tf_ids: List of TF identifiers (strings). - tf_protein: Dictionary mapping TF identifiers to their protein data (numpy array). - tf_psite_data: Dictionary mapping TF identifiers to their phosphorylation site data (list of numpy arrays). - tf_psite_labels: Dictionary mapping TF identifiers to their phosphorylation site labels (list of strings). - time_cols: List of time columns (excluding "GeneID" and "Psite").

`load_regulation(filename=INPUT4)`

Returns a mapping from gene (source) to a list of TFs (targets).

Parameters:

Name	Type	Description	Default
`filename`	`str`	Path to the CSV file containing regulation data.	`INPUT4`

Returns: - reg_map: Dictionary mapping gene identifiers to lists of TF identifiers.

`summarize_stats(input3=INPUT3, input1=INPUT1, input4=INPUT4)`

Summarizes statistics for the expression data (input3) and TF protein data (input1).

Parameters:

Name	Type	Description	Default
`input3`	`str`	Path to the expression data CSV file.	`INPUT3`
`input1`	`str`	Path to the TF protein data CSV file.	`INPUT1`
`input4`	`str`	Path to the mapping file CSV.	`INPUT4`

`create_report(results_dir: str, output_file: str = 'report.html')`

Creates a single global report HTML file from all gene folders inside the results directory.

Parameters:

Name	Type	Description	Default
`results_dir`	`str`	Path to the root results directory.	required
`output_file`	`str`	Name of the generated global report file (placed inside results_dir).	`'report.html'`

`organize_output_files(*directories)`

Function to organize output files into protein-specific folders.

Parameters:

Name	Type	Description	Default
`directories`	`str`	List of directories to organize.	`()`

`tfopt.local.utils.params`

`get_optimization_parameters(expression_matrix, tf_protein_matrix, n_reg, T_use, psite_labels_arr, num_psites, lb, ub)`

Prepare the optimization parameters for the optimization problem.

Parameters:

Name	Type	Description	Default
`expression_matrix`	`ndarray`	Gene expression matrix.	required
`tf_protein_matrix`	`ndarray`	TF protein matrix.	required
`n_reg`	`int`	Number of regulators.	required
`T_use`	`int`	Number of time points to use.	required
`psite_labels_arr`	`list`	List of phosphorylation site labels for each TF.	required
`num_psites`	`ndarray`	Array containing the number of phosphorylation sites for each TF.	required
`lb`	`float`	Lower bound for beta parameters.	required
`ub`	`float`	Upper bound for beta parameters.	required

Returns: x0 (np.ndarray): Initial guess for the optimization variables. n_alpha (int): Number of alpha parameters. beta_start_indices (np.ndarray): Starting indices for beta parameters. bounds (list): List of bounds for the optimization variables. no_psite_tf (np.ndarray): Array indicating whether each TF has no phosphorylation sites. n_genes (int): Number of genes. n_TF (int): Number of transcription factors.

`postprocess_results(result, n_alpha, n_genes, n_reg, beta_start_indices, num_psites, reg_map, gene_ids, tf_ids, psite_labels_arr)`

Post-process the optimization results to extract the final alpha and beta parameters.

Parameters:

Name	Type	Description	Default
`result`	`OptimizeResult`	The result of the optimization.	required
`n_alpha`	`int`	Number of alpha parameters.	required
`n_genes`	`int`	Number of genes.	required
`n_reg`	`int`	Number of regulators.	required
`beta_start_indices`	`ndarray`	Starting indices for beta parameters.	required
`num_psites`	`ndarray`	Array containing the number of phosphorylation sites for each TF.	required
`reg_map`	`dict`	Regulation map, mapping gene IDs to their regulators.	required
`gene_ids`	`list`	List of gene IDs.	required
`tf_ids`	`list`	List of transcription factor IDs.	required
`psite_labels_arr`	`list`	List of lists containing phosphorylation site labels.	required

Returns:

Name	Type	Description
`final_x`	`ndarray`	Final optimization result.
`final_alpha`	`ndarray`	Final alpha parameters reshaped into a matrix.
`final_beta`	`ndarray`	Final beta parameters reshaped into a matrix.

Fitting Analysis

`tfopt.fitanalysis.helper`

`Plotter`

A class to plot various analysis results from an Excel file.

`init(filepath, savepath)`

Initializes the Plotter instance by loading data from the Excel file. Args: filepath (str): Path to the Excel file containing analysis results. savepath (str): Directory where the plots will be saved.

`load_data()`

Loads data from the specified Excel file. Args: filepath (str): Path to the Excel file. savepath (str): Directory where the plots will be saved.

`plot_alpha_distribution()`

Plots the distribution of alpha parameter values grouped by transcription factors (TFs) using a strip plot.

`plot_beta_barplots()`

Processes the beta values DataFrame and creates a separate bar plot for each unique transcription factor (TF).

`plot_heatmap_abs_residuals()`

Plots a heatmap of the absolute values of the residuals.

`plot_goodness_of_fit()`

Creates a scatter plot comparing observed vs. estimated values, fits a linear regression model, plots the 95% confidence interval, and labels points outside the confidence interval.

`plot_kld()`

Plots the Kullback-Leibler Divergence (KLD) for each mRNA. The KLD is calculated between the observed and estimated distributions of the mRNA expression levels.

`plot_pca()`

Plots a PCA (Principal Component Analysis) of the observed and estimated values.

`plot_boxplot_alpha()`

Plots a boxplot of the alpha values.

`plot_boxplot_beta()`

Plots a boxplot of the beta values.

`plot_cdf_alpha()`

Plots the cumulative distribution function (CDF) of the alpha values.

`plot_cdf_beta()`

Plots the cumulative distribution function (CDF) of the beta values.

`plot_time_wise_residuals()`

Plots the residuals over time for each mRNA.

ODE Modelling & Parameter Estimation

Configuration

`config.cli`

Command‑line entry point for the phoskintime pipeline.

Usage

Come one level up from the package root, it should be the working directory

(where you can see the project directory).

run everything with the default (local) solver

python phoskintime all

run only preprocessing

python phoskintime prep

run tfopt with local flavour

python phoskintime tfopt --mode local

run tfopt with evol flavour

python phoskintime tfopt --mode evol

run kinopt with local flavour

python phoskintime kinopt --mode local

run kinopt with evol flavour

python phoskintime kinopt --mode evol

run the model

python phoskintime model

run the integrated Global Model

python phoskintime networkmodel

`prep()`

Preprocess data (processing.cleanup).

`tfopt(mode: str = typer.Option('local', help='local | evol'), outdir: Path | None = typer.Option(None, '--outdir', '--output-dir', file_okay=False, dir_okay=True, help='Directory for workflow outputs.'), conf: Path | None = typer.Option(None, '--conf', file_okay=True, dir_okay=False, writable=False, help='Path to TOML/YAML config. Uses defaults if omitted.'))`

Transcription-Factor-mRNA Optimisation.

Parameters:

Name	Type	Description	Default
`mode`	`str`	local \| evol	`Option('local', help='local \| evol')`
`conf`	`Path \| None`	Path to TOML/YAML config. Uses defaults if omitted.	`Option(None, '--conf', file_okay=True, dir_okay=False, writable=False, help='Path to TOML/YAML config. Uses defaults if omitted.')`

Returns: None

`kinopt(mode: str = typer.Option('local', help='local | evol'), outdir: Path | None = typer.Option(None, '--outdir', '--output-dir', file_okay=False, dir_okay=True, help='Directory for workflow outputs.'), conf: Path | None = typer.Option(None, '--conf', file_okay=True, dir_okay=False, writable=False, help='Path to TOML/YAML config. Uses defaults if omitted.'))`

Kinase-Phosphorylation Optimization.

Parameters:

Name	Type	Description	Default
`mode`	`str`	local \| evol	`Option('local', help='local \| evol')`
`conf`	`Path \| None`	Path to TOML/YAML config. Uses defaults if omitted.	`Option(None, '--conf', file_okay=True, dir_okay=False, writable=False, help='Path to TOML/YAML config. Uses defaults if omitted.')`

Returns: None

`model(outdir: Path | None = typer.Option(None, '--outdir', '--output-dir', file_okay=False, dir_okay=True, help='Directory for workflow outputs.'), conf: Path | None = typer.Option(None, '--conf', file_okay=True, dir_okay=False, writable=False, help='Path to model config file. Uses defaults if omitted.'))`

Run the model (runner.main).

Parameters:

Name	Type	Description	Default
`conf`	`Path \| None`	Path to model config file. Uses defaults if omitted.	`Option(None, '--conf', file_okay=True, dir_okay=False, writable=False, help='Path to model config file. Uses defaults if omitted.')`

Returns: None

`networkmodel(outdir: Path | None = typer.Option(None, '--outdir', '--output-dir', file_okay=False, dir_okay=True, help='Directory for workflow outputs.'), conf: Path | None = typer.Option('config.toml', '--conf', file_okay=True, dir_okay=False, writable=False, help='Path to global model config file. Uses config.toml by default.'))`

Run the integrated Global Model (networkmodel.runner).

This runs the unified optimization pipeline defined in the [networkmodel] section of your configuration.

`clean()`

Remove all pycache, .pyc, .nbc, and build artifacts recursively.

all(tf_mode: str = typer.Option('local', help='tfopt mode: local | evol'), kin_mode: str = typer.Option('local', help='kinopt mode: local | evol'), tf_conf: Path | None = typer.Option(None, help='tfopt config file'), kin_conf: Path | None = typer.Option(None, help='kinopt config file'), model_conf: Path | None = typer.Option(None, help='model config file'), outdir: Path | None = typer.Option(None, '--outdir', '--output-dir', file_okay=False, dir_okay=True, help='Base directory for workflow outputs.'))

Run every stage in sequence. Preprocessing -> TF optimisation -> Kinase optimisation -> Model.

Note: This command does NOT run the global network simulation (networkmodel). To run the global model, use the separate entry point phoskintime-global (or python -m networkmodel.runner) after this command completes.

Parameters:

Name	Type	Description	Default
`tf_mode`	`str`	tfopt mode: local \| evol	`Option('local', help='tfopt mode: local \| evol')`
`kin_mode`	`str`	kinopt mode: local \| evol	`Option('local', help='kinopt mode: local \| evol')`
`tf_conf`	`Path \| None`	Path to TOML/YAML config. Uses defaults if omitted.	`Option(None, help='tfopt config file')`
`kin_conf`	`Path \| None`	Path to TOML/YAML config. Uses defaults if omitted.	`Option(None, help='kinopt config file')`
`model_conf`	`Path \| None`	Path to model config file. Uses defaults if omitted.	`Option(None, help='model config file')`

Returns: None

`config.config`

`parse_bound_pair(val)`

Parse a string representing a pair of bounds (lower, upper) into a tuple of floats. The upper bound can be 'inf' or 'infinity' to represent infinity. Raises ValueError if the input is not in the correct format. Args: val (str): The string to parse, e.g., "0,3" or "0,infinity". Returns: tuple: A tuple containing the lower and upper bounds as floats.

`parse_fix_value(val)`

Parse a fixed value or a list of fixed values from a string. If the input is a single value, it returns that value as a float. If the input is a comma-separated list, it returns a list of floats. Raises ValueError if the input is not in the correct format. Args: val (str): The string to parse, e.g., "1.0" or "1.0,2.0". Returns: float or list: The parsed fixed value(s) as a float or a list of floats.

`ensure_output_directory(directory)`

Parameters:

Name	Type	Description	Default
`directory`	`str`	The path to the directory to create.	required

Returns: None

`log_config(logger, bounds, args)`

Log the configuration settings for the PhosKinTime script. This function logs the parameter bounds bootstrapping iterations. It uses the provided logger to output the information.

Parameters:

Name	Type	Description	Default
`logger`	`Logger`	The logger to use for logging.	required
`bounds`	`dict`	The parameter bounds.	required
`args`	`Namespace`	The command-line arguments.	required

Returns: None

`extract_config(args, loaded_config: dict[str, Any] | None = None)`

Extract effective ProtWise runtime settings after config and CLI precedence have been resolved. CLI values override values loaded from --conf/default config.

`score_fit(params, target, prediction, alpha=ALPHA_WEIGHT, beta=BETA_WEIGHT, gamma=GAMMA_WEIGHT, delta=DELTA_WEIGHT, mu=MU_WEIGHT)`

Calculate the score for the fit of a model to target data. The score is a weighted combination of various metrics including mean squared error (MSE), root mean squared error (RMSE), mean absolute error (MAE), variance, and regularization penalty. The weights for each metric can be adjusted using the parameters alpha, beta, gamma, and delta. The regularization penalty is controlled by the reg_penalty parameter. The function returns the calculated score. Args: params (np.ndarray): The model parameters. target (np.ndarray): The target data. prediction (np.ndarray): The predicted data. alpha (float): Weight for RMSE. beta (float): Weight for MAE. gamma (float): Weight for variance. delta (float): Weight for MSE. mu (float): Regularization penalty weight. Returns: float: The calculated score.

`future_times(n_new: int, ratio: Optional[float] = None, tp: np.ndarray = TIME_POINTS) -> np.ndarray`

Extend ttime points by n_new points, each spaced by multiplying the previous interval by ratio. If ratio is None, it is inferred from the last two points.

Parameters:

Name	Type	Description	Default
`n_new`	`int`	Number of new time points to generate.	required
`ratio`	`float`	Ratio to multiply the previous interval. Defaults to None.	`None`
`tp`	`ndarray`	Existing time points. Defaults to TIME_POINTS.	`TIME_POINTS`

Returns: np.ndarray: Extended time points.

`config.constants`

`generate_randmod_subsets(num_psites: int) -> tuple[tuple[int, ...], ...]`

Canonical randmod subset order: singletons, then pairs, then triples.

The order matches randmod labels/parameters, e.g. for three sites: (1,), (2,), (3,), (1, 2), (1, 3), (2, 3), (1, 2, 3).

`randmod_subset_masks(num_psites: int) -> tuple[int, ...]`

Return canonical randmod subsets as 1-based-site bitmasks.

`get_param_names_rand(num_psites: int) -> list`

Generate parameter names for the random model. Format: ['A', 'B', 'C', 'D'] + ['S1', 'S2', ..., 'S'] + [parameter names for all combinations of dephosphorylation sites].

Parameters:

Name	Type	Description	Default
`num_psites`	`int`	Number of phosphorylation sites.	required

Returns: list: List of parameter names.

`get_param_names_ds(num_psites: int) -> list`

Generate parameter names for distributive or successive models. Format: ['A', 'B', 'C', 'D'] + ['S1', 'S2', ..., 'S'] + ['D1', 'D2', ..., 'D'].

Parameters:

Name	Type	Description	Default
`num_psites`	`int`	Number of phosphorylation sites.	required

Returns: list: List of parameter names.

`generate_labels_rand(num_psites: int) -> list`

Generates labels for the states based on the number of phosphorylation sites for the random model. Returns a list with the base labels "R" and "P", followed by labels for all combinations of phosphorylated sites.

Parameters:

Name	Type	Description	Default
`num_psites`	`int`	Number of phosphorylation sites.	required

Returns: list: List of state labels.

`generate_labels_ds(num_psites: int) -> list`

Generates labels for the states based on the number of phosphorylation sites for the distributive or successive models. Returns a list with the base labels "R" and "P", followed by labels for each individual phosphorylated state.

Parameters:

Name	Type	Description	Default
`num_psites`	`int`	Number of phosphorylation sites.	required

Returns: list: List of state labels.

`location(path: str, label: str = None) -> str`

Returns a clickable hyperlink string for supported terminals using ANSI escape sequences.

Parameters:

Name	Type	Description	Default
`path`	`str`	The file path or URL.	required
`label`	`str`	The display text for the link. Defaults to the path if not provided.	`None`

Returns:

Name	Type	Description
`str`	`str`	A string that, when printed, shows a clickable link in terminals that support ANSI hyperlinks.

`get_number_of_params_rand(num_psites)`

Calculate the number of parameters required for the ODE system based on the number of phosphorylation sites.

Parameters:

Name	Type	Description	Default
`num_psites`	`int`	Number of phosphorylation sites (1 to 4).	required

Returns:

Name	Type	Description
`int`		Total number of parameters.

`get_bounds_rand(num_psites, ub=0, lower=0)`

Generate bounds for the ODE parameters based on the number of phosphorylation sites.

Parameters:

Name	Type	Description	Default
`num_psites`	`int`	Number of phosphorylation sites.	required
`lower`	`float`	Lower bound for parameters.	`0`
`upper`	`float`	Upper bound for parameters.	required

Returns:

Name	Type	Description
`list`		List of bounds as [lower, upper] for each parameter.

`validate_ode_inputs(config: dict | None = None, require_existing: bool = False) -> dict[str, Path]`

Validate required ODE input paths for an actual ProtWise/ODE run.

`get_num_params(model_name: str | None, num_psites: int) -> int`

Return the number of kinetic parameters for a local ODE model.

`get_param_names(num_psites: int, model_name: str | None = None) -> list[str]`

Return parameter labels whose length matches get_num_params().

`config.logconf`

`ColoredFormatter`

Bases: Formatter

Custom formatter to add colors to log messages and elapsed time. This formatter uses ANSI escape codes to colorize the log messages based on their severity level. It also includes a right-aligned clock that shows the elapsed time since the logger was initialized. The elapsed time is displayed in a human-readable format (e.g., "1h 23m 45s"). The formatter is designed to be used with a logger that has a console handler. The elapsed time is calculated from the time the logger was initialized and is displayed in a right-aligned format. The formatter also ensures that the log messages are padded to a specified width, which can be adjusted using the width parameter. The remove_ansi method is used to strip ANSI escape codes from the log message for accurate padding calculation. The format method is overridden to customize the log message format, including the timestamp, logger name, log level, and message. The setup_logger function is used to configure the logger with a file handler and a stream handler. The file handler writes log messages to a specified log file, while the stream handler outputs log messages to the console. The logger is set to the specified logging level, and the log file is created in the specified directory. The log file is rotated based on size, and old log files are backed up.

`format(record)`

Format the log record with colors and elapsed time. This method overrides the default format method to customize the log message format. It includes the timestamp, logger name, log level, and message.

`remove_ansi(s)` `staticmethod`

Remove ANSI escape codes from a string.

`setup_logger(name=None, log_file=None, level=logging.DEBUG, log_dir=LOG_DIR, rotate=True, max_bytes=2 * 1024 * 1024, backup_count=5, mp_file_logging='main_only')`

Setup a logger with colored output and file logging. This function creates a logger with colored output for console messages :param name: :param log_file: :param level: :param log_dir: :param rotate: :param max_bytes: :param backup_count: :param mp_file_logging: - "off": disable file logging - "main_only": file logging only in main process - "per_process": file logging in each process :return: logger

Core Functions

`protwise.paramest.normest`

JAXopt/Diffrax single-objective parameter estimation for protwise models.

`to_opt_space(params_phys, model_name: str | None = None)`

Map physical kinetic parameters to optimizer coordinates.

ProjectedGradient already enforces box constraints, so the optimizer space is intentionally identical to physical space. This avoids the old mixed softplus/log/bounds parameterization where bounds were specified in physical units but optimization happened in a transformed space for only some models.

`from_opt_space(theta_opt, model_name: str | None = None)`

Map optimizer coordinates to physical kinetic parameters.

`aggregate_randmod_phospho(sol, num_psites)`

Aggregate randmod subset states into site-level phospho predictions.

Observations are site-level, while randmod states are subset-level. For example, site 1 signal is P1 + P12 + P13 + P123, so multi-site states must contribute to every site they contain.

`normest(gene, pr_data, p_data, r_data, init_cond, num_psites, time_points, bounds, bootstraps=0)`

Estimate local-model parameters with a deterministic JAXopt projected-gradient path.

`protwise.paramest.toggle`

`estimate_parameters(gene, pr_data, p_data, r_data, init_cond, num_psites, time_points, bounds, bootstraps)`

Wrapper around the normal estimation workflow in paramest/normest.py.

This function delegates parameter estimation to :func:paramest.normest.normest. There is currently only one estimation mode (normal). A sequential estimation mode does not exist; paramest/seqest.py is not part of this package.

Parameters:

Name	Type	Description	Default
`gene`	`str`	Gene name.	required
`pr_data`	`array`	Array of protein data.	required
`p_data`	`array`	Array of protein-phospho data.	required
`r_data`	`array`	Array of RNA data.	required
`init_cond`	`array`	Initial conditions for the model.	required
`num_psites`	`int`	Number of phosphorylation sites.	required
`time_points`	`array`	Time points for the data.	required
`bounds`	`tuple`	Bounds for the parameter estimation.	required
`bootstraps`	`int`	Number of bootstrap samples.	required

Returns:

Name	Type	Description
`model_fits`	`list`	List of model fits.
`estimated_params`	`array`	Estimated parameters.
`seq_model_fit`	`array`	Model fit array of shape (num_psites, len(time_points)).
`errors`	`array`	Errors in the estimation.
`reg_term`	`float`	Regularization term.

Weights for Curve Fitting

`protwise.models.weights`

`early_emphasis(pr_data, p_data, time_points, num_psites)`

Function that calculates custom weights for early time points in a dataset.

Parameters:

Name	Description	Default
`pr_data`	2D numpy array of shape (num_psites, n_times)	required
`p_data`	2D numpy array of shape (num_psites, n_times)	required
`time_points`	1D numpy array of time points	required
`num_psites`	Number of phosphorylation sites	required

Returns:

Name	Type	Description
`custom_weights`		1D numpy array of weights for early time points

`get_protein_weights(gene, input1_path=Path(file).resolve().parent.parent / 'processing' / 'input1_wstd.csv', input2_path=Path(file).resolve().parent.parent / 'data' / 'input2.csv')`

Function to extract weights for a specific gene from the input files.

Parameters:

Name	Type	Description	Default
`gene`	`str`	Gene ID to filter the weights.	required
`input1_path`	`Path`	Path to the input1_wstd.csv file.	`parent / 'processing' / 'input1_wstd.csv'`
`input2_path`	`Path`	Path to the input2.csv file.	`parent / 'data' / 'input2.csv'`

Returns:

Name	Type	Description
`weights`	`ndarray`	Extracted weights for the specified gene.

`full_weight(p_data_weight, use_regularization, reg_len)`

Function to create a full weight array for parameter estimation.

Parameters:

Name	Type	Description	Default
`p_data_weight`	`ndarray`	The weight data to be processed.	required
`use_regularization`	`bool`	Flag to indicate if regularization is used.	required
`reg_len`	`int`	Length of the regularization term.	required

Returns:

Type	Description
	numpy.ndarray: The full weight array.

`get_weight_options(target, t_target, num_psites, use_regularization, reg_len, early_weights, ms_gauss_weights)`

Function to calculate weights for parameter estimation based on the target data and time points.

Parameters:

Name	Type	Description	Default
`target`	`ndarray`	The target data for which weights are calculated.	required
`t_target`	`ndarray`	The time points corresponding to the target data.	required
`num_psites`	`int`	Number of phosphorylation sites.	required
`use_regularization`	`bool`	Flag to indicate if regularization is used.	required
`reg_len`	`int`	Length of the regularization term.	required
`early_weights`	`ndarray`	Weights for early time points.	required
`ms_gauss_weights`	`ndarray`	Weights based on Gaussian distribution.	required

Returns:

Name	Type	Description
`dict`		A dictionary containing different weight options.

Parameter Estimation

`protwise.paramest.core`

`process_gene(gene, protein_data, kinase_data, mrna_data, time_points, bounds, bootstraps=0, out_dir=OUT_DIR)`

Process a single gene by estimating its parameters and generating plots.

Parameters:

Name	Type	Description	Default
`gene`	`str`	Gene name.	required
`protein_data`	`DataFrame`	DataFrame containing protein-only data.	required
`kinase_data`	`DataFrame`	DataFrame containing kinase data.	required
`mrna_data`	`DataFrame`	DataFrame containing mRNA data.	required
`time_points`	`list`	List of time points for the experiment.	required
`bounds`	`tuple`	Bounds for parameter estimation.	required
`bootstraps`	`int`	Number of bootstrap iterations. Defaults to 0.	`0`
`out_dir`	`str`	Output directory for saving results. Defaults to OUT_DIR.	`OUT_DIR`

Returns:

Type	Description
	gene: The gene being processed.
	estimated_params: Estimated parameters for the gene.
	model_fits: Model fits for the gene.
	seq_model_fit: Sequential model fit for the gene.
	errors: Error metrics (MSE, MAE).
	final_params: Final estimated parameters.
	param_df: DataFrame of estimated parameters.
	gene_psite_data: Dictionary of gene-specific data.
	psite_labels: Labels for phosphorylation sites.
	pca_result: PCA result for the gene.
	ev: Explained variance for PCA.
	tsne_result: t-SNE result for the gene.
	perturbation_analysis: Sensitivity analysis results.
	perturbation_curves_params: Trajectories with parameters for sensitivity analysis.
	knockout_results: Dictionary of knockout results.
	regularization: Regularization value used in parameter estimation.

`process_gene_wrapper(gene, protein_data, kinase_data, mrna_data, time_points, bounds, bootstraps, out_dir=OUT_DIR)`

Wrapper function to process a gene.

Parameters:

Name	Type	Description	Default
`gene`	`str`	Gene name.	required
`protein_data`	`DataFrame`	DataFrame containing protein-only data.	required
`kinase_data`	`DataFrame`	DataFrame containing kinase data.	required
`mrna_data`	`DataFrame`	DataFrame containing mRNA data.	required
`time_points`	`list`	List of time points for the experiment.	required
`bounds`	`tuple`	Bounds for parameter estimation.	required
`bootstraps`	`int`	Number of bootstrap iterations. Defaults to 0.	required
`out_dir`	`str`	Output directory for saving results. Defaults to OUT_DIR.	`OUT_DIR`

Returns:

Name	Type	Description
`dict`		A dictionary containing the results of the gene processing.

Confidence Intervals using Linearization

`protwise.paramest.identifiability.ci`

`confidence_intervals(gene, popt, pcov, target, model, alpha_val=0.05)`

Computes the confidence intervals for parameter estimates using Wald Intervals approach.

Parameters:

Name	Type	Description	Default
`gene`	`str`	Gene name.	required
`popt`	`ndarray`	Optimized parameter estimates.	required
`pcov`	`ndarray`	Covariance matrix of the optimized parameters.	required
`target`	`ndarray`	Target data.	required
`model`	`ndarray`	Model predictions.	required
`alpha_val`	`float`	Significance level for confidence intervals. Defaults to 0.05.	`0.05`

Returns:

Name	Type	Description
`dict`		A dictionary containing the confidence intervals and other statistics.

Knockout Analysis

`protwise.knockout.helper`

Perturbation & Parameter Sensitivity Analysis

`protwise.sensitivity.analysis`

`compute_bound(value, perturbation: float = PERTURBATIONS_VALUE)`

Compute lower and upper bounds for a parameter value for sensitivity analysis.

For near-zero values, uses a small positive fallback interval [0, 0.1].

`define_sensitivity_problem_rand(num_psites, values)`

Define the Morris sensitivity problem for the random (randmod) model.

Parameters are taken from get_num_params/get_param_names for 'randmod'.

`define_sensitivity_problem_ds(num_psites, values)`

Define the Morris sensitivity problem for the current ODE_MODEL (dynamic-site, etc.).

Model Diagram

`protwise.models.diagram.helpers`

`powerset(iterable)`

Return the list of all subsets (as frozensets) of the given iterable.

Parameters:

Name	Type	Description	Default
`iterable`		An iterable (e.g., list, set) to generate subsets from.	required

Returns: A list of frozensets representing all subsets of the input iterable.

`state_label(state)`

Convert a set of phosphorylation sites into a node label.

Parameters:

Name	Type	Description	Default
`state`		A frozenset representing the phosphorylation state.	required

Returns: A string representing the label for the node.

`create_random_diagram(x, num_sites, output_filename)`

Create a random phosphorylation diagram.

Parameters:

Name	Description	Default
`x`	Placeholder parameter, not used in this function.	required
`num_sites`	The number of phosphorylation sites.	required
`output_filename`	The name of the output file for the diagram.	required

`create_distributive_diagram(x, num_sites, output_filename)`

Create a distributive phosphorylation diagram.

Parameters:

Name	Description	Default
`x`	Placeholder parameter, not used in this function.	required
`num_sites`	The number of phosphorylation sites.	required
`output_filename`	The name of the output file for the diagram.	required

`create_successive_model(x, num_sites, output_filename)`

Create a successive phosphorylation diagram.

Parameters:

Name	Description	Default
`x`	Placeholder parameter, not used in this function.	required
`num_sites`	The number of phosphorylation sites.	required
`output_filename`	The name of the output file for the diagram.	required

Protein Wise Model Types

`protwise.models.distmod`

`ode_core(y, t, A, B, C, D, S_rates, D_rates)`

The core ODE system for the distributive phosphorylation model.

Parameters:

Name	Description	Default
`y`	array of concentrations	required
`t`	time	required
`A`	mRNA production rate	required
`B`	mRNA degradation rate	required
`C`	protein production rate	required
`D`	protein degradation rate	required
`S_rates`	phosphorylation rates for each site	required
`D_rates`	dephosphorylation rates for each site	required

Returns:

Name	Type	Description
`dydt`		array of derivatives

`unpack_params(params, num_psites)`

Function to unpack the parameters for the distributive ODE system.

Parameters:

Name	Type	Description	Default
`params`	`array`	Parameter vector containing A, B, C, D, S_1.S_n, Ddeg_1.Ddeg_m.	required
`num_psites`	`int`	Number of phosphorylation sites.	required

Returns:

Name	Type	Description
`A`	`float`	mRNA production rate.
`B`	`float`	mRNA degradation rate.
`C`	`float`	protein production rate.
`D`	`float`	protein degradation rate.
`S_rates`	`array`	Phosphorylation rates for each site.
`D_rates`	`array`	Dephosphorylation rates for each site.

`solve_ode(params, init_cond, num_psites, t, **kwargs)`

Solve this mechanism with the centralized Diffrax Kvaerno backend.

`protwise.models.randmod`

`unpack_params(params, num_sites)`

Unpack parameters for the Random model.

Parameters:

Name	Type	Description	Default
`params`	`array`	Parameter vector containing A, B, C, D, S_1.S_n, Ddeg_1.Ddeg_m.	required
`num_sites`	`int`	Number of phosphorylation sites.	required

Returns:

Name	Type	Description
`A`	`float`	mRNA production rate.
`B`	`float`	mRNA degradation rate.
`C`	`float`	protein production rate.
`D`	`float`	protein degradation rate.
`S`	`array`	Phosphorylation rates for each site.
`Ddeg`	`array`	Degradation rates for phosphorylated states.

`ode_system(y, t, A, B, C, D, num_sites, S, Ddeg, mono_idx, forward, drop, fcounts, dcounts)`

Compute the time derivatives of a random phosphorylation ODE system.

This function supports a large number of phosphorylation states by using precomputed transition indices to optimize speed.

Parameters:

Name	Type	Description	Default
`y`	`array`	Current state vector [R, P, X_1, ..., X_m].	required
`t`	`float`	Time (unused; present for compatibility with ODE solvers).	required
`A`	`float`	mRNA production rate.	required
`B`	`float`	mRNA degradation rate.	required
`C`	`float`	protein production rate.	required
`D`	`float`	protein degradation rate.	required
`num_sites`	`int`	Number of phosphorylation sites.	required
`S`	`array`	Phosphorylation rates for each site.	required
`Ddeg`	`array`	Degradation rates for phosphorylated states.	required
`mono_idx`	`array`	Precomputed indices for mono-phosphorylated states.	required
`forward`	`array`	Forward phosphorylation target states.	required
`drop`	`array`	Dephosphorylation target states.	required
`fcounts`	`array`	Number of valid forward transitions for each state.	required
`dcounts`	`array`	Number of valid dephosphorylation transitions for each state.	required

Returns:

Name	Type	Description
`out`	`array`	Derivatives [dR, dP, dX_1, ..., dX_m].

`solve_ode(params, init_cond, num_psites, t, **kwargs)`

Solve this mechanism with the centralized Diffrax Kvaerno backend.

`protwise.models.succmod`

`ode_core(y, t, A, B, C, D, S_rates, D_rates)`

The core of the ODE system for the successive ODE model.

Parameters:

Name	Type	Description	Default
`y`	`array`	The current state of the system.	required
`t`	`float`	The current time.	required
`A`	`float`	The mRNA production rate.	required
`B`	`float`	The mRNA degradation rate.	required
`C`	`float`	The protein production rate.	required
`D`	`float`	The protein degradation rate.	required
`S_rates`	`array`	The phosphorylation rates for each site.	required
`D_rates`	`array`	The dephosphorylation rates for each site.	required

Returns: dydt (np.array): The derivatives of the state variables.

`unpack_params(params, num_psites)`

Function to unpack the parameters for the ODE system. The parameters are expected to be in the following order: A, B, C, D, S_rates, D_rates where S_rates and D_rates are arrays of length num_psites. The function returns the unpacked parameters as separate variables. :param params: array of parameters :param num_psites: number of phosphorylation sites :return: A, B, C, D, S_rates, D_rates

`solve_ode(params, init_cond, num_psites, t, **kwargs)`

Solve this mechanism with the centralized Diffrax Kvaerno backend.

Steady-State Calculation

`protwise.steady.initdist`

`initial_condition(num_psites: int) -> list`

Analytical positive steady-state initial condition for distributive model.

`protwise.steady.initrand`

`initial_condition(num_psites: int) -> list`

Positive normalized initial condition for random phosphorylation states.

`protwise.steady.initsucc`

`initial_condition(num_psites: int) -> list`

Analytical positive steady-state initial condition for successive model.

Plotting

`protwise.plotting.plotting`

`Plotter`

A class to encapsulate plotting functionalities for ODE model analysis.

Attributes:

Name	Type	Description
`gene`	`str`	The gene or experiment name.
`out_dir`	`str`	The directory where plots will be saved.
`color_palette`	`list`	List of color codes used for plotting.

`plot_parallel(solution: np.ndarray, labels: list)`

Plots a parallel coordinates plot for the given solution.

Parameters:

Name	Type	Description	Default
`solution`	`ndarray`	2D numpy array of shape (samples, features) representing the data.	required
`labels`	`list`	List of labels for the features in the solution.	required

`pca_components(solution: np.ndarray, target_variance: float = 0.99)`

Plots a scree plot showing the explained variance ratio for PCA components.

Parameters:

Name	Type	Description	Default
`solution`	`ndarray`	2D numpy array of shape (samples, features) representing the data.	required
`target_variance`	`float`	The target variance to explain. Defaults to 0.99.	`0.99`

`plot_pca(solution: np.ndarray, components: int = 3)`

Plots the PCA results for the given solution.

Parameters:

Name	Type	Description	Default
`solution`	`ndarray`	2D numpy array of shape (samples, features) representing the data.	required
`components`	`int`	Number of PCA components to plot. Defaults to 3.	`3`

Returns:

Name	Type	Description
`tuple`		PCA result and explained variance ratio.

`plot_tsne(solution: np.ndarray, perplexity: int = 30)`

Plots a t-SNE visualization of the given solution.

Parameters:

Name	Type	Description	Default
`solution`	`ndarray`	2D numpy array of shape (samples, features) representing the data.	required
`perplexity`	`int`	The perplexity parameter for t-SNE. Defaults to 30.	`30`

Returns:

Type	Description
	np.ndarray: The t-SNE result.

`plot_param_series(estimated_params: list, param_names: list, time_points: np.ndarray)`

Plots the time series of estimated parameters over the given time points.

Parameters:

Name	Type	Description	Default
`estimated_params`	`list`	List of estimated parameters.	required
`param_names`	`list`	List of parameter names.	required
`time_points`	`ndarray`	Array of time points.	required

`plot_profiles(data: pd.DataFrame)`

Plots the profiles of estimated parameters over time.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	DataFrame containing the time series data.	required

`plot_model_fit(model_fit: np.ndarray, Pr_data: np.ndarray, P_data: np.ndarray, R_data: np.ndarray, sol: np.ndarray, num_psites: int, psite_labels: list, time_points: np.ndarray)`

Plots the model fit for mRNA, protein, and phosphorylated species across time.

Parameters:

Name	Type	Description	Default
`model_fit`	`ndarray`	Flattened model fit data (length = 9 + 14 + 14*num_psites).	required
`Pr_data`	`ndarray`	Protein data (14,).	required
`P_data`	`ndarray`	Phosphorylation data (num_psites + 2, 14).	required
`R_data`	`ndarray`	mRNA data (9,).	required
`sol`	`ndarray`	ODE solution array.	required
`num_psites`	`int`	Number of phosphorylation sites.	required
`psite_labels`	`list`	Labels for phosphorylation sites.	required
`time_points`	`ndarray`	Time points (14,).	required

`plot_param_scatter(est_arr: np.ndarray, num_psites: int, time_vals: np.ndarray)`

Plots scatter and density plots for parameters.

Parameters:

Name	Type	Description	Default
`est_arr`	`ndarray`	2D numpy array of estimated parameters.	required
`num_psites`	`int`	Number of phosphorylation sites.	required
`time_vals`	`ndarray`	Array of time values.	required

`plot_heatmap(param_value_df: pd.DataFrame)`

Parameters:

Name	Type	Description	Default
`param_value_df`	`DataFrame`	DataFrame containing parameter values with 'Protein' as one of the columns.	required

`plot_error_distribution(error_df: pd.DataFrame)`

Parameters:

Name	Type	Description	Default
`error_df`	`DataFrame`	DataFrame containing errors with 'MAE' as one of the columns.	required

`plot_gof(merged_data: pd.DataFrame)`

Plot the goodness of fit for the model.

Parameters:

Name	Type	Description	Default
`merged_data`	`DataFrame`	Dataframe containing merged data.	required

`plot_kld(merged_data: pd.DataFrame)`

Plots the Kullback-Divergence for the model.

Parameters:

Name	Type	Description	Default
`merged_data`	`DataFrame`	Dataframe containing merged data.	required

`plot_params_bar(ci_results: dict, param_labels: list = None)`

Plots bar plot for estimated parameter with 95% Confidence Interval.

Parameters:

Name	Type	Description	Default
`ci_results`	`dict`	Dictionary containing the results of the confidence intervals.	required
`param_labels`	`list`	List of parameter labels. Defaults to None.	`None`

`plot_knockouts(results_dict: dict, num_psites: int, psite_labels: list)`

Plot wild-type and knockout simulation results for comparison.

Parameters:

Name	Type	Description	Default
`results_dict`	`dict`	Dictionary containing simulation results.	required
`num_psites`	`int`	Number of phosphorylation sites.	required
`psite_labels`	`list`	List of phosphorylation site labels.	required

`plot_top_param_pairs(excel_path: str)`

For each gene's '_perturbations' sheet in the Excel file, plot scatter plots for the parameter pairs with correlation.

Parameters:

Name	Type	Description	Default
`excel_path`	`str`	Path to the Excel file.	required

`plot_model_perturbations(problem: dict, Si: dict, cutoff_idx: int, time_points: np.ndarray, n_sites: int, best_model_psite_solutions: np.ndarray, best_mrna_solutions: np.ndarray, best_protein_solutions: np.ndarray, psite_labels: list[str], protein_data_ref: np.ndarray, psite_data_ref: np.ndarray, rna_ref: np.ndarray, model_fit_sol: np.ndarray) -> None`

Plot the best model perturbations for the given data.

Parameters:

Name	Type	Description	Default
`problem`	`dict`	The optimization problem.	required
`Si`	`dict`	The simulation index.	required
`cutoff_idx`	`int`	The cutoff index for the time points.	required
`time_points`	`ndarray`	The time points for the data.	required
`n_sites`	`int`	The number of phosphorylation sites.	required
`best_model_psite_solutions`	`ndarray`	The best model phosphorylation site solutions.	required
`best_mrna_solutions`	`ndarray`	The best model mRNA solutions.	required
`best_protein_solutions`	`ndarray`	The best model protein solutions.	required
`protein_ref`		The reference data for the protein.	required
`psite_labels`	`list[str]`	The labels for the phosphorylation sites.	required
`psite_data_ref`	`ndarray`	The reference data for the phosphorylation sites.	required
`rna_ref`	`ndarray`	The reference data for mRNA.	required

`plot_time_state_grid(samples: np.ndarray, time_points: np.ndarray, state_names: list)`

Grid of strip plots per state showing variability across time.

Parameters:

Name	Type	Description	Default
`samples`	`ndarray`	shape (n_samples, n_timepoints, n_states)	required
`time_points`	`ndarray`	array of time points	required
`state_names`	`list`	list of state names	required

`plot_phase_space(samples: np.ndarray, state_names: list)`

Phase space plots: one state vs another for each simulation.

Parameters:

Name	Type	Description	Default
`samples`	`ndarray`	Shape (n_samples, n_timepoints, n_states)	required
`state_names`	`list`	List of state names (length = num_states)	required

`plot_future_fit(P_data: np.ndarray, R_data: np.ndarray, sol: np.ndarray, num_psites: int, psite_labels: list, time_points: np.ndarray)`

Plots the model fit for the future time points.

Parameters:

Name	Type	Description	Default
`P_data`	`ndarray`	Data for phosphorylation sites.	required
`R_data`	`ndarray`	Data for mRNA.	required
`sol`	`ndarray`	Model solution.	required
`num_psites`	`int`	Number of phosphorylation sites.	required
`psite_labels`	`list`	Labels for phosphorylation sites.	required
`time_points`	`ndarray`	Time points for the data.	required

`plot_regularization(excel_path: str)`

Read every '_params' sheet in the Excel file, pull the Regularization value, and plot a horizontal bar chart of regularization vs. gene.

Parameters:

Name	Type	Description	Default
`excel_path`	`str`	Path to the Excel file.	required

`plot_model_error(excel_path: str)`

Read every '_params' sheet in the Excel file, pull the RMSE value, and plot a horizontal bar chart of RMSE vs. gene.

Parameters:

Name	Type	Description	Default
`excel_path`	`str`	Path to the Excel file.	required

Utility Functions

`common.utils.display`

`ensure_output_directory(directory)`

Ensure the output directory exists. If it doesn't, create it.

Parameters:

Name	Type	Description	Default
`directory`	`str`	Path to the output directory.	required

`load_data(excel_file, sheet='Estimated Values')`

Load data from an Excel file. The default sheet is "Estimated Values".

Parameters:

Name	Type	Description	Default
`excel_file`	`str`	Path to the Excel file.	required
`sheet`	`str`	Name of the sheet to load. Default is "Estimated Values".	`'Estimated Values'`

Returns:

Type	Description
	pd.DataFrame: DataFrame containing the data from the specified sheet.

`format_duration(seconds)`

Format a duration in seconds into a human-readable string.

Parameters:

Name	Type	Description	Default
`seconds`	`float`	Duration in seconds.	required

Returns: str: Formatted duration string.

`merge_obs_est(filename)`

Function to merge observed and estimated data from an Excel file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Path to the Excel file containing observed and estimated data.	required

Returns:

Type	Description
	pd.DataFrame: Merged DataFrame containing observed and estimated values for each gene and Psite.

`save_result(results, excel_filename)`

Function to save results to an Excel file.

Parameters:

Name	Type	Description	Default
`results`	`list`	List of dictionaries containing results for each gene.	required
`excel_filename`	`str`	Path to the output Excel file.	required

`create_report(results_dir: str, output_file: str = f'{model_type}_report.html')`

Creates a single global report HTML file from all gene folders inside the results directory.

Parameters:

Name	Type	Description	Default
`results_dir`	`str`	Path to the root result's directory.	required
`output_file`	`str`	Name of the generated global report file (placed inside results_dir).	`f'{model_type}_report.html'`

`organize_output_files(directories: Iterable[Union[str, Path]])`

Organize output files into protein-specific folders and a general folder.

Parameters:

Name	Type	Description	Default
`directories`	`Iterable[Union[str, Path]]`	List of directories to organize.	required

`common.utils.tables`

`generate_tables(xlsx_file_path)`

Generate hierarchical tables from the XLSX file containing alpha and beta values.

Parameters:

Name	Type	Description	Default
`xlsx_file_path`	`str`	Path to the XLSX file containing alpha and beta values.	required

Returns:

Name	Type	Description
`tuple`		containing protein, psite, and the corresponding table.

`save_tables(tables, output_dir)`

Save the generated tables as LaTeX and CSV files.

Parameters:

Name	Type	Description	Default
`tables`	`list`	List of tuples containing protein, psite, and the corresponding table.	required
`output_dir`	`str`	Directory to save the LaTeX and CSV files.	required

`save_master_table(folder='latex', output_file='latex/all_tables.tex')`

Save a master LaTeX file that includes all individual LaTeX files from the specified folder.

Parameters:

Name	Type	Description	Default
`folder`	`str`	The folder containing the individual LaTeX files.	`'latex'`
`output_file`	`str`	The name of the master LaTeX file to be created.	`'latex/all_tables.tex'`

`common.utils.latexit`

`generate_latex_table(df, sheet_name)`

Generate LaTeX code for a table from a DataFrame. Args: df (pd.DataFrame): DataFrame to convert to LaTeX. sheet_name (str): Name of the sheet for caption and label. Returns: str: LaTeX code for the table.

`generate_latex_image(image_filename)`

Generate LaTeX code for an image.

Parameters:

Name	Type	Description	Default
`image_filename`	`str`	Path to the image file.	required

Returns: str: LaTeX code for the image.

`main(input_dir)`

Main function to process Excel and PNG files in the input directory and generate LaTeX code.

Parameters:

Name	Type	Description	Default
`input_dir`	`str`	Directory containing Excel and PNG files.	required

Global ODE Model

Core Data Structures & Topology

`networkmodel.network`

Build index maps, kinase inputs, and mutable system objects for networkmodel ODE evaluation; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.buildmat, networkmodel.config, networkmodel.models, networkmodel.steadystate.

`Index`

Map proteins, sites, kinases, and state-vector offsets

`init(interactions: pd.DataFrame, tf_interactions: pd.DataFrame = None, kin_beta_map: dict = None, tf_beta_map: dict = None)`

Initialize Index

Parameters:

Name	Type	Description	Default
`interactions`	`DataFrame`	Input value used by this routine.	required
`tf_interactions`	`DataFrame`	Input value used by this routine.	`None`
`kin_beta_map`	`dict`	Input value used by this routine.	`None`
`tf_beta_map`	`dict`	Input value used by this routine.	`None`

`block(i: int) -> slice`

Return the state-vector block for a protein index

Parameters:

Name	Type	Description	Default
`i`	`int`	Input value used by this routine.	required

Returns:

Type	Description
`slice`	Computed result from this routine.

`KinaseInput`

Interpolate kinase fold-change inputs over time

`init(kinases, df_fc)`

Initialize KinaseInput

Parameters:

Name	Type	Description	Default
`kinases`		Input value used by this routine.	required
`df_fc`		Input value used by this routine.	required

`eval(t)`

Evaluate kinase inputs at a requested time

Parameters:

Name	Type	Description	Default
`t`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`System`

Store topology, parameters, and state for networkmodel ODE evaluation

`init(idx, W_global, tf_mat, kin_input, defaults, tf_deg)`

Initialize System

Parameters:

Name	Description	Default
`idx`	Input value used by this routine.	required
`W_global`	Input value used by this routine.	required
`tf_mat`	Input value used by this routine.	required
`kin_input`	Input value used by this routine.	required
`defaults`	Input value used by this routine.	required
`tf_deg`	Input value used by this routine.	required

`update(c_k, A_i, B_i, C_i, D_i, Dp_i, E_i, tf_scale)`

Update fitted system parameters

Parameters:

Name	Description	Default
`c_k`	Input value used by this routine.	required
`A_i`	Input value used by this routine.	required
`B_i`	Input value used by this routine.	required
`C_i`	Input value used by this routine.	required
`D_i`	Input value used by this routine.	required
`Dp_i`	Input value used by this routine.	required
`E_i`	Input value used by this routine.	required
`tf_scale`	Input value used by this routine.	required

`attach_initial_condition_data(df_prot, df_rna, df_pho)`

Attach optional initial-condition data frames

Parameters:

Name	Description	Default
`df_prot`	Input value used by this routine.	required
`df_rna`	Input value used by this routine.	required
`df_pho`	Input value used by this routine.	required

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.
`RuntimeError`	When optimization or simulation fails.

`set_initial_conditions()`

Set the system initial state vector

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.
`RuntimeError`	When optimization or simulation fails.

`rhs(t, y)`

Evaluate the active ODE right-hand side

Parameters:

Name	Type	Description	Default
`t`		Input value used by this routine.	required
`y`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`y0() -> np.ndarray`

Return a copy of the initial state vector

Returns:

Type	Description
`ndarray`	Computed result from this routine.

`odeint_args(S_cache=None)`

Return legacy ODE argument tuple for helper kernels

Parameters:

Name	Type	Description	Default
`S_cache`		Input value used by this routine.	`None`

Returns:

Type	Description
	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`networkmodel.BuildMatrix`

Build transcription-factor and kinase-to-site matrices from interaction tables and index maps; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.config.

`site_key(site: str) -> int`

Normalize a phosphorylation site label

Parameters:

Name	Type	Description	Default
`site`	`str`	Input value used by this routine.	required

Returns:

Type	Description
`int`	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`build_W_parallel(interactions: pd.DataFrame, idx, n_cores=4) -> sparse.csr_matrix`

Build kinase-to-site weight matrices in parallel

Parameters:

Name	Type	Description	Default
`interactions`	`DataFrame`	Input value used by this routine.	required
`idx`		Input value used by this routine.	required
`n_cores`		Input value used by this routine.	`4`

Returns:

Type	Description
`csr_matrix`	Computed result from this routine.

`build_tf_matrix(tf_net, idx, tf_beta_map=None, kin_beta_map=None)`

Build the transcription-factor regulatory matrix

Parameters:

Name	Description	Default
`tf_net`	Input value used by this routine.	required
`idx`	Input value used by this routine.	required
`tf_beta_map`	Input value used by this routine.	`None`
`kin_beta_map`	Input value used by this routine.	`None`

Returns:

Type	Description
	Computed result from this routine.

`networkmodel.params`

Create raw parameter vectors and unpack optimized vectors into named kinetic parameter arrays; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.config, networkmodel.utils.

`init_raw_params(defaults, custom_bounds=None)`

Initialize raw optimizer parameters, slices, bounds, and defaults

Parameters:

Name	Type	Description	Default
`defaults`		Input value used by this routine.	required
`custom_bounds`		Input value used by this routine.	`None`

Returns:

Type	Description
	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`unpack_params(theta, slices)`

Unpack a raw optimizer vector into physical parameter arrays

Parameters:

Name	Type	Description	Default
`theta`		Input value used by this routine.	required
`slices`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

Configuration & Data Loading

`networkmodel.config`

Load networkmodel settings from config.toml and expose typed module constants for paths, time grids, model selection, solver controls, optimization controls, regularization weights, inference options, sensitivity options, and metadata; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on no other networkmodel modules.

`networkmodel.io`

Load network, protein, RNA, and phospho input tables from configured paths; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.config, networkmodel.utils.

`load_data(args)`

Load configured networkmodel input tables

Parameters:

Name	Type	Description	Default
`args`		Positional arguments forwarded to the runner.	required

Returns:

Type	Description
	Computed result from this routine.

Physics Kernels (JIT)

`networkmodel.models`

Define NumPy right-hand-side kernels for supported phosphorylation topologies; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on no other networkmodel modules.

`calculate_synthesis_rate(Ai, tf_scale, u_raw)`

Calculate saturating transcriptional synthesis rate

Parameters:

Name	Description	Default
`Ai`	Input value used by this routine.	required
`tf_scale`	Input value used by this routine.	required
`u_raw`	Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`saturating_rhs(y, dy, A_i, B_i, C_i, D_i, Dp_i, E_i, tf_scale, TF_inputs, S_all, offset_y, offset_s, n_sites)`

Evaluate the saturating topology right-hand side

Parameters:

Name	Description	Default
`y`	Input value used by this routine.	required
`dy`	Input value used by this routine.	required
`A_i`	Input value used by this routine.	required
`B_i`	Input value used by this routine.	required
`C_i`	Input value used by this routine.	required
`D_i`	Input value used by this routine.	required
`Dp_i`	Input value used by this routine.	required
`E_i`	Input value used by this routine.	required
`tf_scale`	Input value used by this routine.	required
`TF_inputs`	Input value used by this routine.	required
`S_all`	Input value used by this routine.	required
`offset_y`	Input value used by this routine.	required
`offset_s`	Input value used by this routine.	required
`n_sites`	Input value used by this routine.	required

`distributive_rhs(y, dy, A_i, B_i, C_i, D_i, Dp_i, E_i, tf_scale, TF_inputs, S_all, offset_y, offset_s, n_sites)`

Evaluate the distributive topology right-hand side

Parameters:

Name	Description	Default
`y`	Input value used by this routine.	required
`dy`	Input value used by this routine.	required
`A_i`	Input value used by this routine.	required
`B_i`	Input value used by this routine.	required
`C_i`	Input value used by this routine.	required
`D_i`	Input value used by this routine.	required
`Dp_i`	Input value used by this routine.	required
`E_i`	Input value used by this routine.	required
`tf_scale`	Input value used by this routine.	required
`TF_inputs`	Input value used by this routine.	required
`S_all`	Input value used by this routine.	required
`offset_y`	Input value used by this routine.	required
`offset_s`	Input value used by this routine.	required
`n_sites`	Input value used by this routine.	required

`sequential_rhs(y, dy, A_i, B_i, C_i, D_i, Dp_i, E_i, tf_scale, TF_inputs, S_all, offset_y, offset_s, n_sites)`

Evaluate the sequential topology right-hand side

Parameters:

Name	Description	Default
`y`	Input value used by this routine.	required
`dy`	Input value used by this routine.	required
`A_i`	Input value used by this routine.	required
`B_i`	Input value used by this routine.	required
`C_i`	Input value used by this routine.	required
`D_i`	Input value used by this routine.	required
`Dp_i`	Input value used by this routine.	required
`E_i`	Input value used by this routine.	required
`tf_scale`	Input value used by this routine.	required
`TF_inputs`	Input value used by this routine.	required
`S_all`	Input value used by this routine.	required
`offset_y`	Input value used by this routine.	required
`offset_s`	Input value used by this routine.	required
`n_sites`	Input value used by this routine.	required

`combinatorial_rhs(y, dy, A_i, B_i, C_i, D_i, Dp_i, E_i, tf_scale, TF_inputs, S_rates, offset_y, offset_s, n_sites, n_states)`

Evaluate the combinatorial topology right-hand side

Parameters:

Name	Description	Default
`y`	Input value used by this routine.	required
`dy`	Input value used by this routine.	required
`A_i`	Input value used by this routine.	required
`B_i`	Input value used by this routine.	required
`C_i`	Input value used by this routine.	required
`D_i`	Input value used by this routine.	required
`Dp_i`	Input value used by this routine.	required
`E_i`	Input value used by this routine.	required
`tf_scale`	Input value used by this routine.	required
`TF_inputs`	Input value used by this routine.	required
`S_rates`	Current per-site kinase signal vector.	required
`offset_y`	Input value used by this routine.	required
`offset_s`	Input value used by this routine.	required
`n_sites`	Input value used by this routine.	required
`n_states`	Input value used by this routine.	required

`iter_random_transitions_for_sites(n_sites)`

Yield combinatorial forward transitions for one protein lazily.

The order is identical to the historical dense implementation: state mask first, then site index, yielding only unset-bit phosphorylation edges.

`count_random_transitions_for_sites(n_sites)`

Return the number of combinatorial forward transitions for n sites.

`build_random_transitions(idx, *, dense_threshold_sites=4)`

Build small dense transition arrays for compatibility.

Large proteins are represented by metadata only; callers that need all transitions should use :func:iter_random_transitions_for_sites instead.

`networkmodel.TimeBucket`

Provide small NumPy-compatible helper kernels for phosphorylation-rate cache evaluation; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on no other networkmodel modules.

`build_S_cache_into(S_out, W_indptr, W_indices, W_data, kin_Kmat, c_k)`

Fill a phosphorylation-rate cache array

Parameters:

Name	Description	Default
`S_out`	Input value used by this routine.	required
`W_indptr`	Input value used by this routine.	required
`W_indices`	Input value used by this routine.	required
`W_data`	Input value used by this routine.	required
`kin_Kmat`	Input value used by this routine.	required
`c_k`	Input value used by this routine.	required

`kin_eval_step(t, grid, Kmat)`

Evaluate kinase inputs at a time point

Parameters:

Name	Description	Default
`t`	Input value used by this routine.	required
`grid`	Input value used by this routine.	required
`Kmat`	Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

Numerical Integration & Solvers

`networkmodel.simulate`

Simulate a System with Diffrax and extract protein, RNA, and phospho measurement tables; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.config, networkmodel.jax_backend.

`combinatorial_site_signals_streaming(states, n_sites)`

Return per-site combinatorial signals without building an ns x n_sites bit matrix.

`simulate_diffrax(sys, t_eval, rtol=None, atol=None, max_steps=None, solver_name='Kvaerno4')`

Simulate a System over requested time points with Diffrax

Parameters:

Name	Description	Default
`sys`	Input value used by this routine.	required
`t_eval`	Input value used by this routine.	required
`rtol`	Input value used by this routine.	`None`
`atol`	Input value used by this routine.	`None`
`max_steps`	Input value used by this routine.	`None`
`solver_name`	Input value used by this routine.	`'Kvaerno4'`

Returns:

Type	Description
	Computed result from this routine.

`simulate_and_measure(sys, idx, t_points_p, t_points_r, t_points_pho)`

Simulate a System and return measured output tables

Parameters:

Name	Description	Default
`sys`	Input value used by this routine.	required
`idx`	Input value used by this routine.	required
`t_points_p`	Input value used by this routine.	required
`t_points_r`	Input value used by this routine.	required
`t_points_pho`	Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`networkmodel.backend`

Provide JAX, Diffrax, and JAXopt utilities for scalar networkmodel simulation, multimodal loss evaluation, parameter projection, and ProjectedGradient optimization; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.config.

`DataMode` `dataclass`

Describe which data layers contribute to the scalar loss

`active_loss_terms: tuple[str, ...]` `property`

Return names of active loss terms

Returns:

Type	Description
`tuple[str, ...]`	Computed result from this routine.

`skipped_loss_terms: tuple[str, ...]` `property`

Return names of skipped loss terms

Returns:

Type	Description
`tuple[str, ...]`	Computed result from this routine.

`DiffraxSolverConfig` `dataclass`

Store Diffrax implicit-solver configuration values

`solver()`

Create the configured Diffrax implicit solver

Returns:

Type	Description
	Computed result from this routine.

`JaxoptResult` `dataclass`

Store scalar JAXopt optimization outputs

`ensure_jax_float64() -> bool`

Enable JAX float64 mode

Returns:

Type	Description
`bool`	Computed result from this routine.

`detect_data_mode(*, mrna=None, protein=None, phospho=None, loss_data: Mapping | None = None, logger_obj=None) -> DataMode`

Detect which observed data layers are available

Parameters:

Name	Type	Description	Default
`mrna`		Input value used by this routine.	`None`
`protein`		Input value used by this routine.	`None`
`phospho`		Input value used by this routine.	`None`
`loss_data`	`Mapping \| None`	Input value used by this routine.	`None`
`logger_obj`		Input value used by this routine.	`None`

Returns:

Type	Description
`DataMode`	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`validate_loss_data(loss_data: Mapping, mode: DataMode) -> None`

Validate loss-array presence, shape, and finiteness

Parameters:

Name	Type	Description	Default
`loss_data`	`Mapping`	Input value used by this routine.	required
`mode`	`DataMode`	Input value used by this routine.	required

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`make_networkmodel_rhs(sys, slices=None)`

Build a JAX right-hand side for the current System topology

Parameters:

Name	Type	Description	Default
`sys`		Input value used by this routine.	required
`slices`		Input value used by this routine.	`None`

Returns:

Type	Description
	Computed result from this routine.

`solve_diffrax(y0, t_eval, params=None, rhs=None, config: DiffraxSolverConfig | None = None)`

Solve an ODE trajectory with Diffrax

Parameters:

Name	Type	Description	Default
`y0`		Input value used by this routine.	required
`t_eval`		Input value used by this routine.	required
`params`		Input value used by this routine.	`None`
`rhs`		Input value used by this routine.	`None`
`config`	`DiffraxSolverConfig \| None`	Input value used by this routine.	`None`

Returns:

Type	Description
	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.
`RuntimeError`	When optimization or simulation fails.

`multimodal_loss_from_trajectory(Y, loss_data: Mapping, mode: DataMode, weights: Mapping[str, float] | None = None, *, networkmodel_layout: bool = False)`

Compute weighted multimodal loss from a trajectory

Parameters:

Name	Type	Description	Default
`Y`		Input value used by this routine.	required
`loss_data`	`Mapping`	Input value used by this routine.	required
`mode`	`DataMode`	Input value used by this routine.	required
`weights`	`Mapping[str, float] \| None`	Input value used by this routine.	`None`
`networkmodel_layout`	`bool`	Input value used by this routine.	`False`

Returns:

Type	Description
	Computed result from this routine.

`project_simplex(x)`

Project a vector onto the probability simplex

Parameters:

Name	Type	Description	Default
`x`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`project_alpha_blocks(alpha, block_ids)`

Project alpha blocks onto per-block simplexes

Parameters:

Name	Type	Description	Default
`alpha`		Input value used by this routine.	required
`block_ids`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`project_beta_blocks(beta, block_ids, lower=-4.0, upper=4.0)`

Project beta blocks onto bounded per-block simplexes

Parameters:

Name	Description	Default
`beta`	Input value used by this routine.	required
`block_ids`	Input value used by this routine.	required
`lower`	Input value used by this routine.	`-4.0`
`upper`	Input value used by this routine.	`4.0`

Returns:

Type	Description
	Computed result from this routine.

`project_bounds(theta, lower, upper, fixed_mask=None, fixed_values=None)`

Project parameters onto bounds and fixed values

Parameters:

Name	Description	Default
`theta`	Input value used by this routine.	required
`lower`	Input value used by this routine.	required
`upper`	Input value used by this routine.	required
`fixed_mask`	Input value used by this routine.	`None`
`fixed_values`	Input value used by this routine.	`None`

Returns:

Type	Description
	Computed result from this routine.

`optimize_scalar_objective(objective_fun, theta0, lower, upper, *, maxiter=20000, tol=1e-06, fixed_mask=None, fixed_values=None, logger_obj=None, verbose=1)`

Optimize a scalar objective with jaxopt.ProjectedGradient

Parameters:

Name	Description	Default
`objective_fun`	Input value used by this routine.	required
`theta0`	Input value used by this routine.	required
`lower`	Input value used by this routine.	required
`upper`	Input value used by this routine.	required
`maxiter`	Input value used by this routine.	`20000`
`tol`	Input value used by this routine.	`1e-06`
`fixed_mask`	Input value used by this routine.	`None`
`fixed_values`	Input value used by this routine.	`None`
`logger_obj`	Input value used by this routine.	`None`
`verbose`	Input value used by this routine.	`1`

Returns:

Type	Description
	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.
`RuntimeError`	When optimization or simulation fails.

`make_simple_objective(loss_data: Mapping, mode: DataMode, time_grid: Sequence[float], weights=None, defaults=None, prior_weight=0.0, *, networkmodel_layout: bool = False, return_breakdown: bool = False, y0=None, sys=None, slices=None)`

Create the scalar trajectory objective

Parameters:

Name	Type	Description	Default
`loss_data`	`Mapping`	Input value used by this routine.	required
`mode`	`DataMode`	Input value used by this routine.	required
`time_grid`	`Sequence[float]`	Input value used by this routine.	required
`weights`		Input value used by this routine.	`None`
`defaults`		Input value used by this routine.	`None`
`prior_weight`		Input value used by this routine.	`0.0`
`networkmodel_layout`	`bool`	Input value used by this routine.	`False`
`return_breakdown`	`bool`	Input value used by this routine.	`False`
`y0`		Input value used by this routine.	`None`
`sys`		Input value used by this routine.	`None`
`slices`		Input value used by this routine.	`None`

Returns:

Type	Description
	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`warn_deprecated_backend_options(options: Mapping | object | None, logger_obj=None)`

Warn about accepted-but-ignored backend options

Parameters:

Name	Type	Description	Default
`options`	`Mapping \| object \| None`	Input value used by this routine.	required
`logger_obj`		Input value used by this routine.	`None`

`networkmodel.SteadyStateAnalysis`

Simulate a system to a long time horizon and write steady-state diagnostic plots; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.config, networkmodel.simulate.

`simulate_until_steady(sys, t_max=1440.0, n_points=1000)`

Simulate the system toward steady state

Parameters:

Name	Description	Default
`sys`	Input value used by this routine.	required
`t_max`	Input value used by this routine.	`1440.0`
`n_points`	Input value used by this routine.	`1000`

Returns:

Type	Description
	Computed result from this routine.

`plot_steady_state_all(t, Y, sys, idx, output_dir)`

Write steady-state diagnostic plots and tables

Parameters:

Name	Description	Default
`t`	Input value used by this routine.	required
`Y`	Input value used by this routine.	required
`sys`	Input value used by this routine.	required
`idx`	Input value used by this routine.	required
`output_dir`	Input value used by this routine.	required

`networkmodel.InitialConditions`

Build initial state vectors from optional observed baseline data; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.config.

`build_y0_from_data(idx, df_prot, df_rna, df_pho, *, t_init=0.0, t0_pho=0.0, eps=1e-09, time_tol=1e-08, max_pho_frac=0.3)`

Build an initial state vector from observed baseline data

Parameters:

Name	Description	Default
`idx`	Input value used by this routine.	required
`df_prot`	Input value used by this routine.	required
`df_rna`	Input value used by this routine.	required
`df_pho`	Input value used by this routine.	required
`t_init`	Input value used by this routine.	`0.0`
`t0_pho`	Input value used by this routine.	`0.0`
`eps`	Input value used by this routine.	`1e-09`
`time_tol`	Input value used by this routine.	`1e-08`
`max_pho_frac`	Input value used by this routine.	`0.3`

Returns:

Type	Description
	Computed result from this routine.

Optimization & Loss Functions

`networkmodel.OptimizationProblem`

Wrap the scalar JAX objective and optimizer used by the runner; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.jax_backend.

`GlobalODEScalarObjective`

Evaluate and solve the scalar global ODE objective

`init(sys, slices, loss_data, defaults, lambdas, time_grid, xl, xu, fail_value=1000000000000.0, data_mode: DataMode | None = None, **_)`

Initialize GlobalODEScalarObjective

Parameters:

Name	Type	Description	Default
`sys`		Input value used by this routine.	required
`slices`		Input value used by this routine.	required
`loss_data`		Input value used by this routine.	required
`defaults`		Input value used by this routine.	required
`lambdas`		Input value used by this routine.	required
`time_grid`		Input value used by this routine.	required
`xl`		Input value used by this routine.	required
`xu`		Input value used by this routine.	required
`fail_value`		Input value used by this routine.	`1000000000000.0`
`data_mode`	`DataMode \| None`	Input value used by this routine.	`None`
`_`		Input value used by this routine.	`{}`

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`objective(x)`

Evaluate the scalar objective

Parameters:

Name	Type	Description	Default
`x`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`evaluate(x) -> float`

Evaluate the scalar objective for compatibility callers

Parameters:

Name	Type	Description	Default
`x`		Input value used by this routine.	required

Returns:

Type	Description
`float`	Computed result from this routine.

`solve(theta0, maxiter=50, tol=1e-06)`

Run scalar ProjectedGradient optimization

Parameters:

Name	Description	Default
`theta0`	Input value used by this routine.	required
`maxiter`	Input value used by this routine.	`50`
`tol`	Input value used by this routine.	`1e-06`

Returns:

Type	Description
	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`GlobalODE_MOO`

Bases: GlobalODEScalarObjective

Reject removed multi-objective optimization usage

`init(*args, **kwargs)`

Initialize GlobalODE_MOO

Parameters:

Name	Type	Description	Default
`args`		Positional arguments forwarded to the runner.	`()`
`kwargs`		Keyword arguments forwarded to the runner.	`{}`

`build_weight_functions(method_protein='uniform', method_rna='uniform', time_grid=None)`

Build placeholder weight functions for scalar optimization

Parameters:

Name	Description	Default
`method_protein`	Input value used by this routine.	`'uniform'`
`method_rna`	Input value used by this routine.	`'uniform'`
`time_grid`	Input value used by this routine.	`None`

Returns:

Type	Description
	Computed result from this routine.

`networkmodel.LossFunction`

Compute scalar loss values for protein, RNA, and phospho observations from simulated trajectories; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.config.

`sq(diff)`

Compute squared loss

Parameters:

Name	Type	Description	Default
`diff`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`huber(diff, delta=1.0)`

Compute Huber loss

Parameters:

Name	Type	Description	Default
`diff`		Input value used by this routine.	required
`delta`		Input value used by this routine.	`1.0`

Returns:

Type	Description
	Computed result from this routine.

`pseudo_huber(diff, delta=1.0)`

Compute pseudo-Huber loss

Parameters:

Name	Type	Description	Default
`diff`		Input value used by this routine.	required
`delta`		Input value used by this routine.	`1.0`

Returns:

Type	Description
	Computed result from this routine.

`charbonnier(diff, eps=0.001)`

Compute Charbonnier loss

Parameters:

Name	Type	Description	Default
`diff`		Input value used by this routine.	required
`eps`		Input value used by this routine.	`0.001`

Returns:

Type	Description
	Computed result from this routine.

`log_cosh(diff)`

Compute log-cosh loss

Parameters:

Name	Type	Description	Default
`diff`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`cauchy_loss(diff, c=1.0)`

Compute Cauchy loss

Parameters:

Name	Type	Description	Default
`diff`		Input value used by this routine.	required
`c`		Input value used by this routine.	`1.0`

Returns:

Type	Description
	Computed result from this routine.

`poisson_scaled_mse(diff, pred_val, eps=1e-06)`

Compute Poisson-scaled mean squared error

Parameters:

Name	Description	Default
`diff`	Input value used by this routine.	required
`pred_val`	Input value used by this routine.	required
`eps`	Input value used by this routine.	`1e-06`

Returns:

Type	Description
	Computed result from this routine.

`geman_mcclure(diff, delta=1.0)`

Compute Geman-McClure loss

Parameters:

Name	Type	Description	Default
`diff`		Input value used by this routine.	required
`delta`		Input value used by this routine.	`1.0`

Returns:

Type	Description
	Computed result from this routine.

`loss_function_noncomb(Y, p_prot, t_prot, obs_prot, w_prot, p_rna, t_rna, obs_rna, w_rna, p_pho, s_pho, t_pho, obs_pho, w_pho, prot_map, prot_base_idx, rna_base_idx, pho_base_idx)`

Compute multimodal loss for non-combinatorial state layouts

Parameters:

Name	Description	Default
`Y`	Input value used by this routine.	required
`p_prot`	Input value used by this routine.	required
`t_prot`	Input value used by this routine.	required
`obs_prot`	Input value used by this routine.	required
`w_prot`	Input value used by this routine.	required
`p_rna`	Input value used by this routine.	required
`t_rna`	Input value used by this routine.	required
`obs_rna`	Input value used by this routine.	required
`w_rna`	Input value used by this routine.	required
`p_pho`	Input value used by this routine.	required
`s_pho`	Input value used by this routine.	required
`t_pho`	Input value used by this routine.	required
`obs_pho`	Input value used by this routine.	required
`w_pho`	Input value used by this routine.	required
`prot_map`	Input value used by this routine.	required
`prot_base_idx`	Input value used by this routine.	required
`rna_base_idx`	Input value used by this routine.	required
`pho_base_idx`	Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`loss_function_comb(Y, p_prot, t_prot, obs_prot, w_prot, p_rna, t_rna, obs_rna, w_rna, p_pho, s_pho, t_pho, obs_pho, w_pho, prot_map, prot_base_idx, rna_base_idx, pho_base_idx)`

Compute multimodal loss for combinatorial state layouts

Parameters:

Name	Description	Default
`Y`	Input value used by this routine.	required
`p_prot`	Input value used by this routine.	required
`t_prot`	Input value used by this routine.	required
`obs_prot`	Input value used by this routine.	required
`w_prot`	Input value used by this routine.	required
`p_rna`	Input value used by this routine.	required
`t_rna`	Input value used by this routine.	required
`obs_rna`	Input value used by this routine.	required
`w_rna`	Input value used by this routine.	required
`p_pho`	Input value used by this routine.	required
`s_pho`	Input value used by this routine.	required
`t_pho`	Input value used by this routine.	required
`obs_pho`	Input value used by this routine.	required
`w_pho`	Input value used by this routine.	required
`prot_map`	Input value used by this routine.	required
`prot_base_idx`	Input value used by this routine.	required
`rna_base_idx`	Input value used by this routine.	required
`pho_base_idx`	Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`networkmodel.BayesianInference`

Inference utilities for PhosKinTime scalar JAXopt/Diffrax models.

The functions here operate on a caller-provided scalar JAX objective and numeric parameter vectors. They are shared by networkmodel and protwise wrappers and keep pandas/matplotlib work outside differentiated functions.

`InferenceContext` `dataclass`

`build_worker_kwargs(start_id: int, seed: int, theta_start: np.ndarray) -> dict`

Create an immutable per-worker copy of numeric residual/loss metadata.

`configure_numpyro_parallel_chains(num_chains: int, *, cpu_threads_per_chain: int = 1, logger_obj=None) -> dict`

Configure JAX CPU devices for parallel NumPyro NUTS chains.

Must run before JAX is imported for XLA device-count changes to fully apply.

`configure_jax_parallelism(max_workers: int | None = None, logger_obj=None) -> dict`

Set conservative thread env defaults before JAX work and report strategy.

`run_profile_likelihood_standalone_processes(*, run_config_path: str | Path, output_dir: str | Path, parameter_indices: Sequence[int], grid_size: int = 5, max_workers: int = 1, timeout_seconds: int | None = None) -> dict`

Run profile likelihood in standalone subprocesses.

Each subprocess profiles one parameter over the requested grid and then exits, releasing JAX/XLA/LLVM memory back to the OS.

`run_numpyro_posterior_standalone_processes(*, run_config_path: str | Path, output_dir: str | Path, num_warmup: int = 20, num_samples: int = 30, seed: int = 0, num_processes: int = 4, timeout_seconds: int | None = None) -> dict`

Run independent posterior chains as clean Python subprocesses.

This avoids passing a live JAX/Diffrax objective through multiprocessing. Each subprocess rebuilds the objective from disk and runs one sequential NUTS chain.

`networkmodel.PosteriorObjective`

Rebuild networkmodel posterior objective from saved run artifacts.

This module exists so posterior chains can be launched as independent Python processes without pickling a live JAX/Diffrax objective.

`build_networkmodel_posterior_context(run_config_path: str | Path, chain_output_dir: str | Path) -> InferenceContext`

Rebuild an InferenceContext from saved posterior run config.

This function intentionally reconstructs the objective in a fresh process.

`write_posterior_payload(*, ctx: InferenceContext, runner_args, lambdas: dict, output_dir: str | Path) -> Path`

Write posterior payload needed by standalone posterior worker.

`networkmodel.PosteriorWorker`

Standalone posterior worker for one NumPyro NUTS chain.

Run as

python -m networkmodel.posterior_worker --run-config ... --chain-id 0

`networkmodel.ProfileWorker`

Standalone profile-likelihood worker for one parameter.

Run as

python -m networkmodel.ProfileWorker --run-config results/.../posterior_payload/posterior_run_config.json --parameter-index 88 --grid-size 7

`networkmodel.runner`

Run the command-line networkmodel workflow that loads data, builds topology, optimizes parameters, and writes outputs; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.analysis, networkmodel.buildmat, networkmodel.cache, networkmodel.config, networkmodel.dashboard_bundle, networkmodel.export, networkmodel.BayesianInference, networkmodel.io, networkmodel.jax_backend, networkmodel.mode_outputs, networkmodel.network, networkmodel.optproblem, networkmodel.params, networkmodel.scan, networkmodel.sensitivity, networkmodel.simulate, networkmodel.steadystate, networkmodel.utils.

`parse_config_path(argv: list[str] | None = None) -> Path | None`

Parse only --conf so selected config is known before defaults are resolved.

`load_networkmodel_config(conf_path: Path | None)`

Load selected networkmodel config and expose it to networkmodel.config importers.

`build_parser(config_defaults: dict[str, Any]) -> argparse.ArgumentParser`

Build the full parser after config-backed defaults are known.

`resolve_runtime_config(args: argparse.Namespace, config_defaults: dict[str, Any]) -> argparse.Namespace`

Attach selected-config metadata and config-only defaults to parsed args.

`parse_runtime_args(argv: list[str] | None = None) -> tuple[argparse.Namespace, dict[str, Any]]`

Parse --conf first, load that config, then parse all args with selected defaults.

`initialize_run_contract(args: argparse.Namespace) -> argparse.Namespace`

Create output/provenance files after config and CLI precedence are resolved.

`main()`

Run the networkmodel entry point

Returns:

Type	Description
	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`networkmodel.scan`

Expose a compatibility hyperparameter-scan entry point for the scalar JAXopt path; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on no other networkmodel modules.

`run_hyperparameter_scan(args, sys, loss_data, defaults, solver_times, runner, slices, xl, xu)`

Run the scalar compatibility hyperparameter scan

Parameters:

Name	Description	Default
`args`	Positional arguments forwarded to the runner.	required
`sys`	Input value used by this routine.	required
`loss_data`	Input value used by this routine.	required
`defaults`	Input value used by this routine.	required
`solver_times`	Input value used by this routine.	required
`runner`	Input value used by this routine.	required
`slices`	Input value used by this routine.	required
`xl`	Input value used by this routine.	required
`xu`	Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

Analysis & Visualization

`networkmodel.sensitivity`

Run perturbation-based sensitivity analysis and write sensitivity diagnostics.

This module runs Morris perturbation-based sensitivity analysis on fitted PhosKinTime/networkmodel parameters. It perturbs fitted parameters, simulates the model, reduces each simulated trajectory to a scalar response metric, computes Morris indices, and writes diagnostic plots/tables.

Important behavior: - c_k is allowed to be negative. - Rate/scale parameters are constrained non-negative. - The default sensitivity target is l2_norm, not raw total signal. - Failed simulations abort the Morris analysis because dropping arbitrary rows invalidates the Morris design.

`compute_bounds(params_dict, perturbation=SENSITIVITY_PERTURBATION)`

Compute Morris perturbation bounds for fitted parameters.

Parameters with biological non-negativity constraints are clipped at zero. Signed parameters such as c_k are allowed to cross below zero.

`run_sensitivity_analysis(sys, idx, fitted_params, output_dir, metric='l2_norm')`

Run Morris perturbation sensitivity analysis.

Returns:

Type	Description
	DataFrame with Morris sensitivity indices sorted by mu_star.

`networkmodel.export`

Write scalar optimization outputs, diagnostic plots, residuals, parameter summaries, and fitted activity tables; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.config, networkmodel.jacspeedup, networkmodel.params, networkmodel.simulate.

`build_site_meta(idx)`

Build phosphosite metadata rows from an index map

Parameters:

Name	Type	Description	Default
`idx`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`export_pareto_front_to_excel(res, sys, idx, slices, output_path, weights=(1.0, 1.0, 1.0), top_k_trajectories=None, t_points_p=None, t_points_r=None, t_points_ph=None, rtol=1e-05, atol=1e-07, mxstep=5000)`

Export scalar optimization trajectories and summaries to Excel

Parameters:

Name	Description	Default
`res`	Input value used by this routine.	required
`sys`	Input value used by this routine.	required
`idx`	Input value used by this routine.	required
`slices`	Input value used by this routine.	required
`output_path`	Input value used by this routine.	required
`weights`	Input value used by this routine.	`(1.0, 1.0, 1.0)`
`top_k_trajectories`	Input value used by this routine.	`None`
`t_points_p`	Input value used by this routine.	`None`
`t_points_r`	Input value used by this routine.	`None`
`t_points_ph`	Input value used by this routine.	`None`
`rtol`	Input value used by this routine.	`1e-05`
`atol`	Input value used by this routine.	`1e-07`
`mxstep`	Input value used by this routine.	`5000`

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`plot_goodness_of_fit(df_prot_obs, df_prot_pred, df_rna_obs, df_rna_pred, df_phos_obs, df_phos_pred, output_dir, file_prefix='')`

Plot observed-versus-predicted goodness of fit

Parameters:

Name	Description	Default
`df_prot_obs`	Input value used by this routine.	required
`df_prot_pred`	Input value used by this routine.	required
`df_rna_obs`	Input value used by this routine.	required
`df_rna_pred`	Input value used by this routine.	required
`df_phos_obs`	Input value used by this routine.	required
`df_phos_pred`	Input value used by this routine.	required
`output_dir`	Input value used by this routine.	required
`file_prefix`	Input value used by this routine.	`''`

Returns:

Type	Description
	Computed result from this routine.

`plot_gof_from_pareto_excel(excel_path: str, output_dir: str, plot_goodness_of_fit_func, df_prot_obs_all: pd.DataFrame, df_rna_obs_all: pd.DataFrame, df_phos_obs_all: pd.DataFrame, traj_protein_sheet: str = 'traj_protein', traj_rna_sheet: str = 'traj_rna', traj_phospho_sheet: str = 'traj_phospho', summary_sheet: str = 'summary', top_k: int = None, only_solutions=None, score_col: str = 'scalar_score')`

Plot goodness of fit from an exported Excel workbook

Parameters:

Name	Type	Description	Default
`excel_path`	`str`	Input value used by this routine.	required
`output_dir`	`str`	Input value used by this routine.	required
`plot_goodness_of_fit_func`		Input value used by this routine.	required
`df_prot_obs_all`	`DataFrame`	Input value used by this routine.	required
`df_rna_obs_all`	`DataFrame`	Input value used by this routine.	required
`df_phos_obs_all`	`DataFrame`	Input value used by this routine.	required
`traj_protein_sheet`	`str`	Input value used by this routine.	`'traj_protein'`
`traj_rna_sheet`	`str`	Input value used by this routine.	`'traj_rna'`
`traj_phospho_sheet`	`str`	Input value used by this routine.	`'traj_phospho'`
`summary_sheet`	`str`	Input value used by this routine.	`'summary'`
`top_k`	`int`	Input value used by this routine.	`None`
`only_solutions`		Input value used by this routine.	`None`
`score_col`	`str`	Input value used by this routine.	`'scalar_score'`

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`export_results(sys, idx, df_prot_obs, df_rna_obs, df_phos_obs, df_pred_p, df_pred_r, df_pred_ph, output_dir)`

Export fitted trajectories and summary outputs

Parameters:

Name	Description	Default
`sys`	Input value used by this routine.	required
`idx`	Input value used by this routine.	required
`df_prot_obs`	Input value used by this routine.	required
`df_rna_obs`	Input value used by this routine.	required
`df_phos_obs`	Input value used by this routine.	required
`df_pred_p`	Input value used by this routine.	required
`df_pred_r`	Input value used by this routine.	required
`df_pred_ph`	Input value used by this routine.	required
`output_dir`	Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`save_gene_timeseries_plots(gene: str, df_prot_obs: pd.DataFrame, df_prot_pred: pd.DataFrame, df_rna_obs: pd.DataFrame, df_rna_pred: pd.DataFrame, df_phos_obs: pd.DataFrame, df_phos_pred: pd.DataFrame, output_dir: str, prot_times: np.ndarray = None, rna_times: np.ndarray = None, phos_times: np.ndarray = None, filename_prefix: str = 'ts', dpi: int = 300, phos_mode: str = 'per_psite', max_psites: int = None)`

Save per-gene observed and predicted time-series plots

Parameters:

Name	Type	Description	Default
`gene`	`str`	Input value used by this routine.	required
`df_prot_obs`	`DataFrame`	Input value used by this routine.	required
`df_prot_pred`	`DataFrame`	Input value used by this routine.	required
`df_rna_obs`	`DataFrame`	Input value used by this routine.	required
`df_rna_pred`	`DataFrame`	Input value used by this routine.	required
`df_phos_obs`	`DataFrame`	Input value used by this routine.	required
`df_phos_pred`	`DataFrame`	Input value used by this routine.	required
`output_dir`	`str`	Input value used by this routine.	required
`prot_times`	`ndarray`	Input value used by this routine.	`None`
`rna_times`	`ndarray`	Input value used by this routine.	`None`
`phos_times`	`ndarray`	Input value used by this routine.	`None`
`filename_prefix`	`str`	Input value used by this routine.	`'ts'`
`dpi`	`int`	Input value used by this routine.	`300`
`phos_mode`	`str`	Input value used by this routine.	`'per_psite'`
`max_psites`	`int`	Input value used by this routine.	`None`

Returns:

Type	Description
	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`export_S_rates(sys, idx, output_dir, filename='S_rates_picked.csv', long=True)`

Export phosphorylation-rate trajectories

Parameters:

Name	Description	Default
`sys`	Input value used by this routine.	required
`idx`	Input value used by this routine.	required
`output_dir`	Input value used by this routine.	required
`filename`	Input value used by this routine.	`'S_rates_picked.csv'`
`long`	Input value used by this routine.	`True`

Returns:

Type	Description
	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.
`RuntimeError`	When optimization or simulation fails.

`plot_s_rates_report(csv_path: str | Path, out_pdf: str | Path = 'S_rates_report.pdf', *, time_col: str = 'time', value_col: str = 'S', protein_col: str = 'protein', psite_col: str = 'psite', log_x: bool = True, top_k_sites_per_protein: int | None = 24, max_sites_per_page: int = 12, ncols: int = 3, normalize_per_site: bool = False, heatmap_per_protein: bool = True, heatmap_cap_sites: int = 80, agg_duplicates: str = 'mean', dpi: int = 300) -> Path`

Plot phosphorylation-rate reports from CSV data

Parameters:

Name	Type	Description	Default
`csv_path`	`str \| Path`	Input value used by this routine.	required
`out_pdf`	`str \| Path`	Input value used by this routine.	`'S_rates_report.pdf'`
`time_col`	`str`	Input value used by this routine.	`'time'`
`value_col`	`str`	Input value used by this routine.	`'S'`
`protein_col`	`str`	Input value used by this routine.	`'protein'`
`psite_col`	`str`	Input value used by this routine.	`'psite'`
`log_x`	`bool`	Input value used by this routine.	`True`
`top_k_sites_per_protein`	`int \| None`	Input value used by this routine.	`24`
`max_sites_per_page`	`int`	Input value used by this routine.	`12`
`ncols`	`int`	Input value used by this routine.	`3`
`normalize_per_site`	`bool`	Input value used by this routine.	`False`
`heatmap_per_protein`	`bool`	Input value used by this routine.	`True`
`heatmap_cap_sites`	`int`	Input value used by this routine.	`80`
`agg_duplicates`	`str`	Input value used by this routine.	`'mean'`
`dpi`	`int`	Input value used by this routine.	`300`

Returns:

Type	Description
`Path`	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`process_convergence_history(res, output_dir)`

Export convergence-history tables and plots

Parameters:

Name	Type	Description	Default
`res`		Input value used by this routine.	required
`output_dir`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`export_kinase_activities(sys, idx, output_dir, t_max=120, n_points=121)`

Export kinase activity trajectories

Parameters:

Name	Description	Default
`sys`	Input value used by this routine.	required
`idx`	Input value used by this routine.	required
`output_dir`	Input value used by this routine.	required
`t_max`	Input value used by this routine.	`120`
`n_points`	Input value used by this routine.	`121`

`export_param_correlations(res, slices, idx, output_dir, best_idx=None)`

Export parameter-correlation diagnostics

Parameters:

Name	Description	Default
`res`	Input value used by this routine.	required
`slices`	Input value used by this routine.	required
`idx`	Input value used by this routine.	required
`output_dir`	Input value used by this routine.	required
`best_idx`	Input value used by this routine.	`None`

`export_residuals(sys, idx, df_prot, df_rna, df_phos, output_dir)`

Export residual tables for fitted observations

Parameters:

Name	Description	Default
`sys`	Input value used by this routine.	required
`idx`	Input value used by this routine.	required
`df_prot`	Input value used by this routine.	required
`df_rna`	Input value used by this routine.	required
`df_phos`	Input value used by this routine.	required
`output_dir`	Input value used by this routine.	required

`export_parameter_distributions(res, slices, idx, output_dir)`

Export optimized parameter distribution plots

Parameters:

Name	Description	Default
`res`	Input value used by this routine.	required
`slices`	Input value used by this routine.	required
`idx`	Input value used by this routine.	required
`output_dir`	Input value used by this routine.	required

`networkmodel.dashboard_app`

Render saved networkmodel outputs in a Streamlit dashboard; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.dashboard_bundle.

`main()`

Run the networkmodel entry point

`networkmodel.dashboard_bundle`

Save and load compact dashboard payloads for scalar optimization runs; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on no other networkmodel modules.

`save_dashboard_bundle(output_dir: str | Path, *, args: Any, res: Any, slices: Any, xl: Any, xu: Any, defaults: dict, lambdas: dict, solver_times, df_prot, df_rna, df_pho, frechet_scores=None, picked_index: int | None = None) -> Path`

Save dashboard input data to disk

Parameters:

Name	Type	Description	Default
`output_dir`	`str \| Path`	Input value used by this routine.	required
`args`	`Any`	Positional arguments forwarded to the runner.	required
`res`	`Any`	Input value used by this routine.	required
`slices`	`Any`	Input value used by this routine.	required
`xl`	`Any`	Input value used by this routine.	required
`xu`	`Any`	Input value used by this routine.	required
`defaults`	`dict`	Input value used by this routine.	required
`lambdas`	`dict`	Input value used by this routine.	required
`solver_times`		Input value used by this routine.	required
`df_prot`		Input value used by this routine.	required
`df_rna`		Input value used by this routine.	required
`df_pho`		Input value used by this routine.	required
`frechet_scores`		Input value used by this routine.	`None`
`picked_index`	`int \| None`	Input value used by this routine.	`None`

Returns:

Type	Description
`Path`	Computed result from this routine.

`load_dashboard_bundle(output_dir: str | Path) -> dict`

Load dashboard input data from disk

Parameters:

Name	Type	Description	Default
`output_dir`	`str \| Path`	Input value used by this routine.	required

Returns:

Type	Description
`dict`	Computed result from this routine.

`networkmodel.mode_outputs`

Write mode-aware metadata, result tables, and simple scalar-run plots; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.jax_backend.

`write_mode_metadata(output_dir: str | Path, mode: DataMode, *, objective_value: float | None = None) -> Path`

Write scalar-run mode metadata

Parameters:

Name	Type	Description	Default
`output_dir`	`str \| Path`	Input value used by this routine.	required
`mode`	`DataMode`	Input value used by this routine.	required
`objective_value`	`float \| None`	Input value used by this routine.	`None`

Returns:

Type	Description
`Path`	Computed result from this routine.

`write_scalar_result_tables(output_dir: str | Path, mode: DataMode, objective_values) -> dict[str, Path]`

Write scalar objective result tables

Parameters:

Name	Type	Description	Default
`output_dir`	`str \| Path`	Input value used by this routine.	required
`mode`	`DataMode`	Input value used by this routine.	required
`objective_values`		Input value used by this routine.	required

Returns:

Type	Description
`dict[str, Path]`	Computed result from this routine.

`save_mode_plots(output_dir: str | Path, mode: DataMode, predictions: Mapping[str, pd.DataFrame]) -> dict[str, Path]`

Save scalar-run mode plots

Parameters:

Name	Type	Description	Default
`output_dir`	`str \| Path`	Input value used by this routine.	required
`mode`	`DataMode`	Input value used by this routine.	required
`predictions`	`Mapping[str, DataFrame]`	Input value used by this routine.	required

Returns:

Type	Description
`dict[str, Path]`	Computed result from this routine.

Utilities

`networkmodel.utils`

Normalize input data, transform positive parameters, load TOML configuration, and compute optimization bounds; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.config.

`PhosKinConfig` `dataclass`

Store networkmodel TOML configuration values

`normcols(df)`

Normalize column labels

Parameters:

Name	Type	Description	Default
`df`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`find_col(df, cands)`

Find the first matching column name

Parameters:

Name	Type	Description	Default
`df`		Input value used by this routine.	required
`cands`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`slen(s: slice) -> int`

Return the length of a sequence-like value

Parameters:

Name	Type	Description	Default
`s`	`slice`	Input value used by this routine.	required

Returns:

Type	Description
`int`	Computed result from this routine.

`normalize_fc_to_t0(df)`

Normalize fold-change values to the baseline time

Parameters:

Name	Type	Description	Default
`df`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`process_and_scale_raw_data(df, time_points, id_cols, scale_method='fc_start', epsilon=0.001)`

Convert wide raw data into scaled tidy time-series data

Parameters:

Name	Description	Default
`df`	Input value used by this routine.	required
`time_points`	Input value used by this routine.	required
`id_cols`	Input value used by this routine.	required
`scale_method`	Input value used by this routine.	`'fc_start'`
`epsilon`	Input value used by this routine.	`0.001`

Returns:

Type	Description
	Computed result from this routine.

`time_bucket(t, grid)`

Map a time value to the nearest grid index

Parameters:

Name	Type	Description	Default
`t`		Input value used by this routine.	required
`grid`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`softplus(x)`

Apply a numerically stable softplus transform

Parameters:

Name	Type	Description	Default
`x`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`inv_softplus(y)`

Apply the inverse softplus transform

Parameters:

Name	Type	Description	Default
`y`		Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`load_config_toml(path: str | Path) -> PhosKinConfig`

Load networkmodel configuration from TOML

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Input value used by this routine.	required

Returns:

Type	Description
`PhosKinConfig`	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`calculate_bio_bounds(idx, df_prot, df_rna, tf_mat, kin_in)`

Calculate biologically constrained optimizer bounds

Parameters:

Name	Description	Default
`idx`	Input value used by this routine.	required
`df_prot`	Input value used by this routine.	required
`df_rna`	Input value used by this routine.	required
`tf_mat`	Input value used by this routine.	required
`kin_in`	Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

`get_optimized_sets(idx, slices, xl, xu, eps=1e-14)`

Report which parameter groups are optimized

Parameters:

Name	Description	Default
`idx`	Input value used by this routine.	required
`slices`	Input value used by this routine.	required
`xl`	Input value used by this routine.	required
`xu`	Input value used by this routine.	required
`eps`	Input value used by this routine.	`1e-14`

Returns:

Type	Description
	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

`networkmodel.cache`

Convert observation data frames into compact numeric arrays for fast loss evaluation; it does not describe planned backends or execute unrelated optimization workflows on import, and it depends on networkmodel.config.

`prepare_fast_loss_data(idx, df_prot, df_rna, df_pho, time_grid)`

Prepare numeric loss arrays from observation data frames

Parameters:

Name	Description	Default
`idx`	Input value used by this routine.	required
`df_prot`	Input value used by this routine.	required
`df_rna`	Input value used by this routine.	required
`df_pho`	Input value used by this routine.	required
`time_grid`	Input value used by this routine.	required

Returns:

Type	Description
	Computed result from this routine.

Raises:

Type	Description
`ValueError`	When inputs are inconsistent or unsupported.

API Reference

Data Standardization & Cleanup

processing.cleanup

process_collecttri()

format_site(site)

process_msgauss()

process_msgauss_std()

process_routlimma()

update_gene_symbols(filename)

move_processed_files()

Optimization Results Mapping

processing.map

map_optimization_results(tf_file_path, kin_file_path, sheet_name='Alpha Values')

create_cytoscape_table(mapping_csv_path)

add_kinetic_strength_columns(mapping_path, mapping__path, excel_path, suffix)

generate_nodes(edge_df)

Kinase-Phosphorylation Optimization

Evolutionary Algorithms

kinopt.evol.config.constants

kinopt.evol.config.logconf

ColoredFormatter

format(record)

remove_ansi(s) staticmethod

setup_logger(name='phoskintime', log_file=None, level=logging.DEBUG, log_dir=LOG_DIR, rotate=True, max_bytes=2 * 1024 * 1024, backup_count=5)

kinopt.evol.exporter.plotout

plot_residuals_for_gene(gene, gene_data)

opt_analyze_nsga(problem, result, F, pairs, approx_ideal, approx_nadir, asf_i, pseudo_i, n_evals, hv, hist, val, hist_cv_avg, k, igd, best_objectives, waterfall_df, convergence_df, alpha_values, beta_values)

opt_analyze_de(long_df, convergence_df, ordered_optimizer_runs, x_values, y_values, val)

kinopt.evol.exporter.sheetutils

output_results(P_initial, P_init_dense, P_estimated, residuals, alpha_values, beta_values, result, timepoints, OUT_FILE)

kinopt.evol.objfn.minfndiffevo

PhosphorylationOptimizationProblem

estimated_series(params)

residuals(params)

kinopt.evol.objfn.minfnnsgaii

PhosphorylationOptimizationProblem

objective_function(params)

kinopt.evol.opt.optrun

choose_de_pop_size(problem)

choose_nsga_pop_size(problem, n_obj=3)

binary_tournament_loss_cv(pop, P, eps_cv=1e-10, cv_mode='linf', **kwargs)

run_optimization(P_initial, P_initial_array, K_index, K_array, gene_psite_counts, beta_counts, PhosphorylationOptimizationProblem)

pick_best_loss_with_constraints_as_objectives(result, eps_cv=1e-10, cv_mode='l1', tie_tol=1e-12, tie_break='loss_then_l2')

post_optimization_nsga(result, weights=np.array([1.0, 1.0, 1.0]), ref_point=np.array([3, 1, 1]))

post_optimization_de(result, alpha_values, beta_values)

kinopt.evol.optcon.construct

pipeline(input1_path: str, input2_path: str, time_series_columns: list[str], scaling_method: str, split_point: float, segment_points: list[float], estimate_missing_kinases: bool, kinase_to_psites: dict[str, int])

load_geneid_to_psites(input1_path=INPUT1)

get_unique_kinases(input2_path=INPUT2)

check_kinases()

kinopt.evol.utils.iodata

format_duration(seconds)

load_and_scale_data(estimate_missing, scaling_method, split_point, seg_points)

apply_scaling(df, time_series_columns, method, split_point, segment_points)

create_report(results_dir: str, output_file: str = 'report.html')

organize_output_files(*directories)

kinopt.evol.utils.params

extract_parameters(P_initial, gene_psite_counts, K_index, optimized_params)

compute_metrics(optimized_params: np.ndarray, P_initial: dict, P_initial_array: np.ndarray, K_index: dict, K_array: np.ndarray, gene_psite_counts: list, beta_counts: dict, n: int)

Gradient-Based Algorithms

kinopt.local.config.constants

parse_args()

kinopt.local.config.logconf

kinopt.local.exporter.plotout

format_timepoints(tp, tol=1e-09)

plot_fits_for_gene(gene, gene_data, real_timepoints, out_dir=OUT_DIR)

export_outcomes_to_csv(outcomes, csv_path)

plot_cumulative_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)

plot_autocorrelation_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)

plot_histogram_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)

plot_qqplot_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)

plot_multistart_summary_runtime_overlay(summary_csv, out_path=None, figsize=(8, 8), x_col='rank', y_col='fun', c_col='runtime_s', success_col='success', cv_col='constr_violation', annotate_best=True)

kinopt.local.exporter.sheetutils

format_timepoints(tp, tol=1e-09)

plot_fits_for_gene(gene, gene_data, real_timepoints, out_dir=OUT_DIR)

export_outcomes_to_csv(outcomes, csv_path)

plot_cumulative_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)

plot_autocorrelation_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)

plot_histogram_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)

plot_qqplot_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)

`processing.cleanup`

`process_collecttri()`

`format_site(site)`

`process_msgauss()`

`process_msgauss_std()`

`process_routlimma()`

`update_gene_symbols(filename)`

`move_processed_files()`

`processing.map`

`map_optimization_results(tf_file_path, kin_file_path, sheet_name='Alpha Values')`

`create_cytoscape_table(mapping_csv_path)`

`add_kinetic_strength_columns(mapping_path, mapping__path, excel_path, suffix)`

`generate_nodes(edge_df)`

`kinopt.evol.config.constants`

`kinopt.evol.config.logconf`

`ColoredFormatter`

`format(record)`

`remove_ansi(s)` `staticmethod`

`setup_logger(name='phoskintime', log_file=None, level=logging.DEBUG, log_dir=LOG_DIR, rotate=True, max_bytes=2 * 1024 * 1024, backup_count=5)`

`kinopt.evol.exporter.plotout`

`plot_residuals_for_gene(gene, gene_data)`

`opt_analyze_nsga(problem, result, F, pairs, approx_ideal, approx_nadir, asf_i, pseudo_i, n_evals, hv, hist, val, hist_cv_avg, k, igd, best_objectives, waterfall_df, convergence_df, alpha_values, beta_values)`

`opt_analyze_de(long_df, convergence_df, ordered_optimizer_runs, x_values, y_values, val)`

`kinopt.evol.exporter.sheetutils`

`output_results(P_initial, P_init_dense, P_estimated, residuals, alpha_values, beta_values, result, timepoints, OUT_FILE)`

`kinopt.evol.objfn.minfndiffevo`

`PhosphorylationOptimizationProblem`

`estimated_series(params)`

`residuals(params)`

`kinopt.evol.objfn.minfnnsgaii`

`PhosphorylationOptimizationProblem`

`objective_function(params)`

`kinopt.evol.opt.optrun`

`choose_de_pop_size(problem)`

`choose_nsga_pop_size(problem, n_obj=3)`

`binary_tournament_loss_cv(pop, P, eps_cv=1e-10, cv_mode='linf', **kwargs)`

`run_optimization(P_initial, P_initial_array, K_index, K_array, gene_psite_counts, beta_counts, PhosphorylationOptimizationProblem)`

`pick_best_loss_with_constraints_as_objectives(result, eps_cv=1e-10, cv_mode='l1', tie_tol=1e-12, tie_break='loss_then_l2')`

`post_optimization_nsga(result, weights=np.array([1.0, 1.0, 1.0]), ref_point=np.array([3, 1, 1]))`

`post_optimization_de(result, alpha_values, beta_values)`

`kinopt.evol.optcon.construct`

`pipeline(input1_path: str, input2_path: str, time_series_columns: list[str], scaling_method: str, split_point: float, segment_points: list[float], estimate_missing_kinases: bool, kinase_to_psites: dict[str, int])`

`load_geneid_to_psites(input1_path=INPUT1)`

`get_unique_kinases(input2_path=INPUT2)`

`check_kinases()`

`kinopt.evol.utils.iodata`

`format_duration(seconds)`

`load_and_scale_data(estimate_missing, scaling_method, split_point, seg_points)`

`apply_scaling(df, time_series_columns, method, split_point, segment_points)`

`create_report(results_dir: str, output_file: str = 'report.html')`

`organize_output_files(*directories)`

`kinopt.evol.utils.params`

`extract_parameters(P_initial, gene_psite_counts, K_index, optimized_params)`

`compute_metrics(optimized_params: np.ndarray, P_initial: dict, P_initial_array: np.ndarray, K_index: dict, K_array: np.ndarray, gene_psite_counts: list, beta_counts: dict, n: int)`

`kinopt.local.config.constants`

`parse_args()`

`kinopt.local.config.logconf`

`kinopt.local.exporter.plotout`

`format_timepoints(tp, tol=1e-09)`

`plot_fits_for_gene(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

`export_outcomes_to_csv(outcomes, csv_path)`

`plot_cumulative_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

`plot_autocorrelation_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

`plot_histogram_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

`plot_qqplot_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

`plot_multistart_summary_runtime_overlay(summary_csv, out_path=None, figsize=(8, 8), x_col='rank', y_col='fun', c_col='runtime_s', success_col='success', cv_col='constr_violation', annotate_best=True)`

`kinopt.local.exporter.sheetutils`

`format_timepoints(tp, tol=1e-09)`

`plot_fits_for_gene(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

`export_outcomes_to_csv(outcomes, csv_path)`

`plot_cumulative_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

`plot_autocorrelation_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

`plot_histogram_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

`plot_qqplot_residuals(gene, gene_data, real_timepoints, out_dir=OUT_DIR)`

`plot_multistart_summary_runtime_overlay(summary_csv, out_path=None, figsize=(8, 8), x_col='rank', y_col='fun', c_col='runtime_s', success_col='success', cv_col='constr_violation', annotate_best=True)`

`output_results(P_initial, P_init_dense, P_estimated, residuals, alpha_values, beta_values, result, mse, rmse, mae, mape, r_squared, filename=OUT_FILE, out_dir=OUT_DIR)`

`export_params_npz(outcomes, path)`

`kinopt.local.objfn.minfn`

`kinopt.local.opt.optrun`

`StartOutcome` `dataclass`