updated parameter processing

[murrayrm]

This PR provides a number of improvements and updates to parameter (and parameter file) processing, along with updates to unit processing and various changes to mechanisms and mixtures related to the parameter processing updates.

Parameters:

• Parameter files are now stripped of lines starting with '#', allowing parameter files to contain comments. Parameter files that are distributed with the package now contain comments explaining their contents.

• Components now check to see if parameter defaults are given by the mechanism that is calling the component, allowing mechanisms to define default parameter values. Default parameter files are provided for the following mechanisms: binding.py, enzyme.py, transport.py, txtl.py. Default parameters are in the matching '_parameters.tsv' files. These parameter values are overridden at the component or mixture level, so all previous behavior is preserved.

  This change allows simplified descriptions of basic circuits without specifying any parameters. For example, the following code will generate a simulatable model with no additional specification of parameter values:

   # Components
   TetR = bcp.Protein('TetR')
   aTc = bcp.Species('aTc')
   TetR_inactive=bcp.ChemicalComplex([TetR.species, aTc])
   ptet = bcp.RegulatedPromoter('ptet', TetR)
   dna_GFP = bcp.DNAassembly(
       'GFP', promoter=ptet, rbs='RBS', protein='GFP')
   
   # Mixture
   mixture = bcp.BasicPURE(
       'default', components=[dna_GFP, TetR_inactive])
   crn = mixture.compile_crn()
  
   timepoints = np.linspace(0, 100)
   results = crn.simulate_with_bioscrape_via_sbml(
       timepoints, initial_condition_dict={'dna_GFP': 1})
  

• Parameter lookup within a component now allows the use of a "part type" in addition to the part ID. This was motivated by the 'binding' mechanisms, which get called for different purposes (eg, binding of two chemicals versus binding of protein to DNA). This functionality is implemented by allowing the part_id for a parameter lookup to be a list, with checking done in the order of elements in the list. A bit more detail below in the description of the changes to the default 'binding' parameters.

Units:

• Put in units for all parameter files that are distributed with the package and added unit definitions for a variety of unit name variations:

  • 'hour': 'hrs', 'hr', 'hours'
  • 'minute': 'min', 'mins', 'minutes'
  • 'second': 's', 'sec', 'secs', 'seconds'

  Note: unit conversions in parameter files are not yet supported. All parameters should use units of 'uM', 'uL', and 'sec' (this is noted in the user documentation).

• Defined a set of standard units to allow easier specifications and conversions:

  • Volume: 'nL', 'uL', 'mL', 'L'
  • Concentration: 'nM', 'uM', 'mM', 'M'
  • Time: 'sec', 'min', 'hrs'
    With these definitions, you can do the following:

   from biocrnpyler.utils.units import (
       nM, uM, mM, M, nL, uL, mL, L, sec, min, hrs
   )
   initial_conditions = {'dna_GFP': 1 * nM}
   plt.plot(results['time']/min, results['protein_GFP' / uM])
  

Mechanisms

• The 'binding' mechanisms (in binding.py) now have default parameter values for two part types in mechanisms/binding_parameters.py: 'chemical_complex' and 'dna_protein'. This allows different uses of binding to have different default parameter values. (This uses the added functionality of allowing parameter lookups with a list of part_id's.)

• Found and fixed a bug where the Energy_Translation_MM mechanism was missing a reverse reaction.

Mixtures

• Default parameter values for all mixtures are now loaded by default (by giving a default value to parameter_file).

• Default parameter values for extracts and PURE are set to values that are somewhat plausible (though they definitely need some work in some future PR).

• Changed EnergyTxTlExtract to track ATP usage explicitly, rather than lumping it in with other nTPs. What was being done before was the NTP was being treated as an "energy" molecule. Given that we are likely to have other mechanisms that use ATP (but not other NTPs), it made sense to make it a separate molecule. (It comes up in this PR because I was adjusting the parameter values and noticed that there wasn't a separate description of ATP.)

Documentation, examples, and unit tests

• Added an example examples/gfp_expression.py that shows comparisons between various extract mixtures (a PURE).
• Changed documentation and code to use 'RNAse' rather than different versions of capitalization or spelling ('RNase', 'RNAase', etc).
• Changed documentation and docstrings to use 'BioCRNpyler' as the consistent capitalized version of the package name (though it is still imported as 'biocrnpyler').
• Updated the user documentation to give a description of these changes.
• Fixed the issue that was generating warnings about multiple TOC trees in newer version of Sphinx (including the one used by ReadTheDocs).
• Examples and unit tests have been updated to reflect the new defaults. The only remaining parameter file in the examples/ directory is 'default_parameters.txt', which has a lot of (undocumented) parameters for various constructs.
• Added unit tests to make sure everything is working as expected.

[murrayrm]

I'm planning to merge this PR in the coming few days since I have another PR that builds on this. I don't think there is anything controversial in this one; it extends functionality and is backward compatible with all current code.

[WilliamIX]

Conceptually I really like allowing Mechanisms to have default parameters! The implementation and other improvements also all look like sensible to me.

[ayush9pandey]

Thank you for all the changes. I agree that these are all useful. A couple of comments:

• on the new example gfp_expression.py: would it be better to include the new example as a notebook so it is consistent with the other set of examples already in the package.
• on the new unit assignments: are these units correctly passed through to sbmlutil and added to the generated SBML file? I think this should be the case, just want to make sure.

[zjuradoq]

I was curious if these updates will necessitate a new version release of BioCRNpyler, specifically whether we anticipate any backward compatibility issues with existing code?

Additionally, I noticed a few things regarding the membrane-associated components. Some of these are for the future, but there is one quick fix that would be great to include in this PR:

Quick fix for this PR:

• membrane.py naming bug: In (https://github.com/murrayrm/BioCRNPyler/blob/parameter_update-22Nov2025/biocrnpyler/components/membrane.py ), if we could please change direction = 'Exporter' to a list: direction = ['Exporter']. Currently, if passed as a string, it gets split into individual characters when forming the name (e.g., Msba_E_x_p_o_r_t_e_r).

Inconsistency to review:

• Degradation vs. Dilution: I noticed that Dilution is used in the Cell-like Mixtures and in the readthedocs, it reads as if 'rna_degradation' is the mechanism type.

rna_degradation’ : Dilution - Separate RNA degradation mechanism (mRNA --> 0) applied to all RNA species to model endonuclease activity

There is a separate Degradation_mRNA_MM mechanism, and I thought there was a non-MM version but not sure if this was phased out.

Future upgrades (likely for a separate PR):

• Allow products to be explicitly defined in membrane components.
• Ensure the material type of the substrate/product is retained (I've found that it currently gets lost).
• Allow Species objects to be used as substrates in membrane components.

[ayush9pandey]

@zjuradoq

I was curious if these updates will necessitate a new version release of BioCRNpyler, specifically whether we anticipate any backward compatibility issues with existing code?

Yes, a new version will be published when we run the pypi release github action.

Additionally, I noticed a few things regarding the membrane-associated components. Some of these are for the future, but there is one quick fix that would be great to include in this PR:

Quick fix for this PR:

• membrane.py naming bug: In (https://github.com/murrayrm/BioCRNPyler/blob/parameter_update-22Nov2025/biocrnpyler/components/membrane.py ), if we could please change direction = 'Exporter' to a list: direction = ['Exporter']. Currently, if passed as a string, it gets split into individual characters when forming the name (e.g., Msba_E_x_p_o_r_t_e_r).

Would you please point out the line number where this is happening? Or a minimal example of the error so we can fix it.

From my quick check, the following code works fine without the split character names:

MsbA_monomer = IntegralMembraneProtein('MsbA_monomer',
                                       product='MsbA_pump', size=2,
                                       direction='Exporter')

#Mechanisms
mech_int = Membrane_Protein_Integration() #cant be 0
int_mechanisms = {mech_int.mechanism_type:mech_int}

#Create mixture
M1= Mixture("Default Param Pathway", components = [MsbA_monomer],
            parameter_file = "mechanisms/transport_parameters.tsv", 
            mechanisms = int_mechanisms)

#Compile the CRN with Mixture.compile_crn
CRN1 = M1.compile_crn()
CRN1.write_sbml_file('MsbA_pump_model.xml')
print(CRN1.pretty_print(show_rates = True, show_attributes = True,
                        show_materials = True, show_keys = False)) 

However, in debugging this issue, I did notice that the latest parameter changes added the ATP values to "600" (and similar other high values) in uM, so the 7. Transport_Models.ipynb needed to be fixed with reasonable parameter values.

Inconsistency to review:

• Degradation vs. Dilution: I noticed that Dilution is used in the Cell-like Mixtures and in the readthedocs, it reads as if 'rna_degradation' is the mechanism type.

rna_degradation’ : Dilution - Separate RNA degradation mechanism (mRNA --> 0) applied to all RNA species to model endonuclease activity

There is a separate Degradation_mRNA_MM mechanism, and I thought there was a non-MM version but not sure if this was phased out.

I'm not sure if I understood this comment: Degradation_mRNA_MM is a global mechanism, which has the mechanism type rna_degradation. In cell mixtures, this mechanism type is being used by sub-classing the Dilution mechanism in the Simple... mixture while the MM version is used in the TxTl... mixture (the slightly more complex mixture).

Future upgrades (likely for a separate PR):

• Allow products to be explicitly defined in membrane components.
• Ensure the material type of the substrate/product is retained (I've found that it currently gets lost).
• Allow Species objects to be used as substrates in membrane components.

[ayush9pandey]

Thank you for all the changes. I agree that these are all useful. A couple of comments:

• on the new example gfp_expression.py: would it be better to include the new example as a notebook so it is consistent with the other set of examples already in the package.
• on the new unit assignments: are these units correctly passed through to sbmlutil and added to the generated SBML file? I think this should be the case, just want to make sure.

The changes above are addressed here: murrayrm#2
Would you please review @murrayrm when you get a chance and then we can merge this PR!

[murrayrm]

@ayush9pandey: I was able to cherry pick the commits and get things to work, except for the updated transport models, which created pytest errors (see error message here). Presumably this is because of some changes that were in pure_update rather than parameter_update, so I will worry about this in the next PR.

I'm going to go ahead and merge this so that I can submit the next PR, which has a lot of additional changes for PURE.

[murrayrm]

I take it back. There were also some problems with the new GFP expression notebook, so I backed that one out and will just put in the unit change fixes. Merging as soon as the checks complete.