Feature request: Table function (TFUN) support in BNGL functions block

[wshlavacek]

Feature Request: Table Function (TFUN) Support in BNGL

Summary

Add support for table functions (tfun) in the BNGL functions block, enabling users to define piecewise-linear interpolation functions from tabular data files. This would allow empirical data (e.g., time-series measurements, dose-response curves) to be incorporated directly into model functions and rate expressions, and allow simulation results to be compared to data in plots generated from GDAT and SCAN files.

Motivation

Several common modeling scenarios require injecting empirical data into simulations:

1. Epidemiological modeling: Cumulative case count data
2. Pharmacology: Drug dosing schedules as time-dependent drivers of dynamics
3. Dose-response fitting: Experimental dose-response curves for parameter scan comparisons

Currently, users must manually encode tabular data as piecewise if() expressions in the functions block, which is error-prone and impractical for large datasets. NFsim already has partial TFUN support (via XML type="TFUN" attributes), but there is no corresponding BNGL-level syntax and no .net file emission.

Proposed BNGL Syntax

begin functions
    # Time-indexed table function (default index = time)
    cumNcases() = tfun('case_data.tfun')
    
    # Explicit time index
    drug_dose() = tfun('dosing_schedule.tfun', time)
    
    # Parameter-indexed table function (for dose-response / parameter scans)
    response() = tfun('dose_response.tfun', drug_conc)
end functions

The second argument (index) specifies which quantity provides the lookup key:

• time (or t) — simulation time (default if omitted)
• A parameter name — the current value of that parameter (useful for parameter_scan actions)
• An observable or function name — the current evaluated value

File Format (.tfun)

GDAT-style two-column plain text with a #-prefixed header:

# time  cumNcases
0  0
1  0
2  1
3  1
4  2
5  5
6  12
7  22

Validation rules:

• First line must be a #-prefixed header with two column names
• Column 1 header must match the index name (time/t/time()/t() for time-indexed, or the parameter/observable name)
• Column 2 header must match the function name being defined
• Column 1 values must be monotonically increasing
• At least 2 data rows required

Interpolation: Piecewise-linear between data points, constant extrapolation beyond endpoints (hold first/last value).

Requested BNG2.pl Changes

1. BNGL parser: Recognize tfun('filename') and tfun('filename', index_name) syntax in the functions block

2. NET file emission: Pass through the tfun(...) definition to the .net functions block:

   begin functions
       1 cumNcases() tfun('case_data.tfun')
       2 response()  tfun('dose_response.tfun', drug_conc)
   end functions
   

3. XML emission (for NFsim): Generate the existing NFsim TFUN XML format:

   <Function id="cumNcases" type="TFUN" file="case_data.tfun" ctrName="time">
     <Expression>__TFUN__VAL__</Expression>
     <ListOfReferences>
       <Reference name="time" type="Observable"/>
     </ListOfReferences>
   </Function>

[jrfaeder]

This seems like a reasonable spec and I am looking further into implementation. One drawback is that it introduces dependencies in both the .bngl and .net files on the additional .tfun files. This could potentially be avoided by allowing for a new block, possibly named tfun, in which function data could be placed.

[wshlavacek]

That’s an interesting idea! For small data, a tfun block makes sense. Get Outlook for iOS<https://aka.ms/o0ukef>

…

________________________________ From: Jim Faeder ***@***.***> Sent: Friday, February 20, 2026 8:57:46 AM To: RuleWorld/bionetgen ***@***.***> Cc: Hlavacek, William Scott ***@***.***>; Author ***@***.***> Subject: [EXTERNAL] Re: [RuleWorld/bionetgen] Feature request: Table function (TFUN) support in BNGL functions block (Issue #278) [https://avatars.githubusercontent.com/u/8277248?s=20&v=4]jrfaeder left a comment (RuleWorld/bionetgen#278)<https://urldefense.com/v3/__https://github.com/RuleWorld/bionetgen/issues/278*issuecomment-3935731652__;Iw!!Bt8fGhp8LhKGRg!FAvvWxgia-YSb7cEE_TEsjCc-LT_5bITBQjxKhf2uGYnmcEG5B9cj9PmHC3KwLM7mxdYCG7cvZbX9XUGCVbF0Wt31g$> This seems like a reasonable spec and I am looking further into implementation. One drawback is that it introduces dependencies in both the .bngl and .net files on the additional .tfun files. This could potentially be avoided by allowing for a new block, possibly named tfun, in which function data could be placed. — Reply to this email directly, view it on GitHub<https://urldefense.com/v3/__https://github.com/RuleWorld/bionetgen/issues/278*issuecomment-3935731652__;Iw!!Bt8fGhp8LhKGRg!FAvvWxgia-YSb7cEE_TEsjCc-LT_5bITBQjxKhf2uGYnmcEG5B9cj9PmHC3KwLM7mxdYCG7cvZbX9XUGCVbF0Wt31g$>, or unsubscribe<https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AETOR57KGJ2QW4P7ULSHAIT4M4VHVAVCNFSM6AAAAACVLFTWRWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTSMZVG4ZTCNRVGI__;!!Bt8fGhp8LhKGRg!FAvvWxgia-YSb7cEE_TEsjCc-LT_5bITBQjxKhf2uGYnmcEG5B9cj9PmHC3KwLM7mxdYCG7cvZbX9XUGCVZYNK3CZQ$>. You are receiving this because you authored the thread.Message ID: ***@***.***>

[jrfaeder]

Updated Implementation Proposal

Based on further investigation of the current TFUN implementation in NFsim and lack of existing usage, I propose the following updates to the specification:

Key Changes from Original Proposal

1. Default to piecewise linear interpolation (instead of step function)

   • Current NFsim implementation uses step function, but appears undocumented/untested
   • Linear interpolation is more accurate and matches user expectations
   • Provides extensibility via optional method keyword

2. Explicit SSA time-indexing restriction

   • Time-indexed TFUN not supported for SSA (would violate Gillespie algorithm assumptions)
   • Observable-indexed and parameter-indexed work correctly
   • Clear error message guides users to correct approach

3. Conservative extrapolation

   • Return first/last value instead of 0 outside data range
   • More physically reasonable for most scenarios

Proposed Syntax

begin functions
    # Default: piecewise linear interpolation, time-indexed
    cumNcases() = tfun('case_data.tfun')
    
    # Explicit index variable
    drug_dose() = tfun('dosing.tfun', time)
    
    # Parameter-indexed (for parameter scans)
    response() = tfun('dose_response.tfun', drug_conc)
    
    # Observable-indexed (safe for SSA)
    k_decay() = tfun('decay_data.tfun', substrate_count)
    
    # Optional interpolation methods
    step_dose() = tfun('dosing.tfun', time, method=>"step")
    smooth_response() = tfun('data.tfun', x, method=>"spline")  # future
end functions

Interpolation Methods

Default: linear (Piecewise Linear)

• Linear interpolation between adjacent points
• Formula: y = y₁ + (y₂-y₁)*(x-x₁)/(x₂-x₁)
• Standard method, matches most user expectations

Optional: step (Step Function)

• Matches current NFsim behavior
• Returns y[i] for x[i] <= x < x[i+1]
• Use case: discrete dosing events, binned data

Future: spline (Cubic Spline)

• Smooth interpolation with continuous derivatives
• Avoids ODE integration issues from discontinuities

Simulator Support Matrix

Simulator	Time-indexed	Observable-indexed	Parameter-indexed
ODE (run_network)	✅ Supported*	✅ Supported	✅ Supported
SSA (run_network)	❌ Error**	✅ Supported	✅ Supported
NFsim	❌ Not supported	✅ Supported	✅ Supported

* Warning issued for discontinuities (step interpolation or non-smooth data)
** Standard Gillespie SSA invalid for time-dependent propensities

Extrapolation Behavior

• Before first point: Return first value (constant extrapolation)
• After last point: Return last value (constant extrapolation)

More conservative than returning 0; user can add explicit boundary points if needed.

Implementation Notes

Analysis of NFsim source code reveals:

1. Current TFUN uses step function interpolation (not piecewise linear)
2. Returns 0 before first point, last value after last point
3. No test examples or documentation found in NFsim repo
4. Time-indexing code exists but is commented out (would break SSA)

Given the apparent lack of existing usage, switching to linear interpolation as the default is low-risk and provides better accuracy.

Backward Compatibility

• Maintain uppercase TFUN() syntax for existing test files
• Support both binary .dat (NFsim) and text .tfun (proposed) formats
• Can emit NFsim XML with type="TFUN" attribute
• Migration path available for any existing models

Thoughts on this updated approach?

[jrfaeder]

For the record, that last comment was authored by Claude with input from Jim.

[jrfaeder]

Claude and I have not discussed yet a tfun block or other inline entry. One drawback of the block method is that it requires cross-referencing between blocks, which would involve more code changes to check for errors.

[jrfaeder]

Additional Proposal: Inline Data Specification

In addition to file-based TFUN, I propose supporting inline data for small datasets and self-contained models:

Syntax

begin functions
    # File-based (for large datasets)
    response() = tfun('dose_response.tfun', drug_conc)
    
    # Inline - pair of arrays (for small datasets)
    dosing() = tfun([0, 8, 16, 24], [0, 100, 50, 0], time)
    
    # With optional method
    step_switch() = tfun([0, 10], [0, 1], time, method=>"step")
end functions

Parser logic:

• If first argument is string → file-based mode
• If first argument is array → inline mode with two arrays: [x_values], [y_values]

Use Cases

Inline (convenient for):

• Small datasets (<50 points)
• Rapid prototyping without creating files
• Self-contained models with no external dependencies
• Educational examples
• Simple dosing schedules or step functions

File-based (better for):

• Large datasets (>50 points)
• Experimental data imported from measurements
• Data shared across multiple models
• Separating data from model for version control

Example: Complete Model

begin model

begin parameters
    k_on 0.1
    k_off 0.01
end parameters

begin molecule types
    Drug()
    Receptor(d)
end molecule types

begin seed species
    Drug() 0
    Receptor(d~off) 100
end seed species

begin observables
    Molecules BoundReceptor Receptor(d~on)
end observables

begin functions
    # Inline dosing schedule: 3 doses over 24 hours
    drug_conc() = tfun([0, 8, 16, 24], [0, 100, 50, 0], time)
    
    # Effective on-rate modulated by drug concentration
    k_on_eff() = k_on * drug_conc()
end functions

begin reaction rules
    Drug() + Receptor(d~off) -> Receptor(d~on) k_on_eff()
    Receptor(d~on) -> Receptor(d~off) + Drug() k_off
end reaction rules

end model

generate_network({overwrite=>1})
simulate({method=>"ode", t_end=>48, n_steps=>200})

Implementation Details

Validation:

# Check array lengths match
if (scalar(@x_vals) != scalar(@y_vals)) {
    die "tfun() arrays must have same length";
}

# Check monotonicity
for (my $i=0; $i<$#x_vals; $i++) {
    if ($x_vals[$i] >= $x_vals[$i+1]) {
        die "tfun() x values must be strictly increasing";
    }
}

NET file emission (embed data):

begin functions
    1 dosing() tfun([0,8,16,24],[0,100,50,0],time)
end functions

Size recommendation:

• Inline data >100 points → warning suggesting file-based approach
• Keeps model files readable and maintainable

Benefits

1. No file path issues - everything in one .bngl file
2. Easy sharing - complete models in single file
3. Quick prototyping - test ideas immediately
4. Self-documenting - data visible in model
5. Version control friendly - all changes in one file

This would complement the file-based approach and make TFUN much more convenient for common use cases like simple dosing schedules or switches.

[wshlavacek]

I looked at the tfun-dev branch and PyBioNetFit will align with the new features. Thank you for the fast turnaround. Note: for the XML emission of inline tfun data, we would like to know the finalized format (marked mode="inline" with no inline data in the XML body). Thanks again!