Use consistent naming conventions for classes

[murrayrm]

The current code uses a lot of different naming conventions for classes. For example, just in the area of mechanisms, we have:

• mechanisms/binding.py:class Two_Step_Cooperative_Binding
• mechanisms/enzyme.py:class MichaelisMentenReversible
• mechanisms/global_mechanisms.py:class Degradation_mRNA_MM
• mechanisms/global_mechanisms.py:class Deg_Tagged_Degradation
• mechanisms/txtl.py:class Transcription_MM
• mechanisms/txtl.py:class Translation_MM
• mechanisms/txtl.py:class multi_tx
  Camel case (Python), lower case with underscores (C), mixtures of the two, abbreviations (MM, tx, Tx), etc.

We should decide on a more consistent convention for classes. Let's use this issue to sort out what makes sense and then we can document a consistent set of guidelines and update all of the class names (with legacy names still allowed for backward compatability).

[murrayrm]

For mechanisms, one possibility would be a pattern that looks like this: MechType_primary_secondary. So, for example:

• Binding_TwoStep_Cooperative: a type of 'binding' mechanism
• Catalysis_MichaelisMenten: a type of 'catalysis' mechanism
• Catalysis_MichaelisMenten_Reversible: a type of 'catalysis' mechanism
  This doesn't exactly follow Python conventions (which would be pure camel case), but the first word would match the mechanism name, the next word(s) would describe the level of detail of that mechanism, and any additional words (optional) would provide additional functionality.

[murrayrm]

I asked Claude to go through all 35 mechanism classes and trace how the names are used at runtime. Summary of what it found:

There are three name spaces here, not one

Every mechanism carries three independently-chosen names, and today all three drift apart:

	example	who consumes it
class name	Transcription_MM	users writing Python
mechanism_type	'transcription'	dict key for mechanisms={...} lookup
instance .name	'transcription_mm'	column 1 of the parameter TSVs

The third one creates another issue to consider. ParameterDatabase.find_parameter searches (mechanism.name, ...) first and (mechanism.mechanism_type, ...) second, so .name is a load-bearing string baked into seven .tsv files. Whatever convention we adopt has to say what happens to all three — otherwise a rename breaks parameter lookup silently, because the defaulting chain just quietly falls through to a more general key.

Full inventory of the three names (click to expand)

class                                    mechanism_type       default .name
---------------------------------------  -------------------  --------------------------------------
One_Step_Cooperative_Binding             binding              one_step_cooperative_binding
Two_Step_Cooperative_Binding             binding              two_step_cooperative_binding
Combinatorial_Cooperative_Binding        binding              Combinatorial_Cooperative_binding   (!)
One_Step_Binding                         binding              one_step_binding
One_Step_Reversible_Conformation_Change  conformation_change  one_step_conformation_change
BasicCatalysis                           catalysis            basic_catalysis
BasicProduction                          catalysis            basic_production
MichaelisMenten                          catalysis            michaelis_menten
MichaelisMentenReversible                catalysis            michaelis_menten_reverse_binding    (!)
MichaelisMentenCopy                      copy                 michaelis_menten_copy
GlobalMechanism                          (none)               -
Dilution                                 dilution             global_degradation_via_dilution     (!)
AntiDilutionConstitutiveCreation         (unset)          (!) anti_dilution_constiuitive_creation (!)
Degradation_mRNA_MM                      rna_degradation      rna_degradation_mm
Deg_Tagged_Degradation                   degradation          deg_tagged_degradation
BasicIntegration                         integration          basic_integration
EnzymeIntegration                        integration          enzyme_integration
OneStepPathway                           metabolic_pathway    one_step_pathway
Membrane_Signaling_Pathway_MM            membrane_sensor      two_component_membrane_signaling    (!)
Simple_Diffusion                         diffusion            simple_diffusion
Membrane_Protein_Integration             membrane_insertion   membrane_protein_integration
Simple_Transport                         transport            simple_membrane_protein_transport   (!)
Facilitated_Transport_MM                 transport            facilitated_membrane_protein_transport
Primary_Active_Transport_MM              transport            active_membrane_protein_transport
OneStepGeneExpression                    transcription    (!)  gene_expression
SimpleTranscription                      transcription        simple_transcription
SimpleTranslation                        translation          simple_translation
PositiveHillTranscription                transcription        positivehill_transcription
NegativeHillTranscription                transcription        negativehill_transcription
Transcription_MM                         transcription        transcription_mm
Translation_MM                           translation          translation_mm
Energy_Transcription_MM                  transcription        energy_transcription_mm
Energy_Translation_MM                    translation          energy_translation_mm
multi_tx                                 transcription        multi_tx
multi_tl                                 translation          multi_tl

(!) marks cases where .name isn't derivable from the class name at all, plus a few outright bugs worth fixing regardless of what we decide here:

• Combinatorial_Cooperative_Binding has a stray lowercase b in its default name (Combinatorial_Cooperative_binding)
• anti_dilution_constiuitive_creation misspells "constitutive"
• AntiDilutionConstitutiveCreation never sets mechanism_type, so it trips the "instantiated without a type" warning in Mechanism.__init__

What comparable packages do

• NumPy/SciPy: PEP 8 CapWords for classes. The lowercase ones (ndarray, dtype, csr_matrix) are documented historical exceptions, not a pattern to copy. Acronyms stay uppercase (BDF, LSODA, RK45, DOP853).
• SciPy's answer for pluggable algorithms is a string selector, not a class-name prefix: solve_ivp(method='RK45'). Family membership lives in the module and the docstring, not the class name.
• scikit-learn is the closest structural analog — strategy objects the user constructs and hands to a container, exactly like mechanisms handed to a Mixture. Its convention is CapWords with the family as a suffix, with the module carrying the grouping: linear_model.LogisticRegression, ensemble.RandomForestClassifier, cluster.AgglomerativeClustering. It scales to ~200 estimators, and discovery is solved by all_estimators() rather than by name prefixes.

Also worth noting: docs/develop.rst already commits us to "standard Python and NumPy naming conventions," which the mechanism library today mostly doesn't follow.

On the MechType_primary_secondary proposal

It's a coherent scheme and it wins exactly where suffix-style gets ugly — the long compound names. Side by side on the hard cases:

current	family-as-suffix	prefix scheme (as proposed above)
Two_Step_Cooperative_Binding	TwoStepCooperativeBinding	Binding_TwoStep_Cooperative
MichaelisMentenReversible	ReversibleMichaelisMentenCatalysis	Catalysis_MichaelisMenten_Reversible
Transcription_MM	MichaelisMentenTranscription	Transcription_MichaelisMenten
Energy_Transcription_MM	EnergyMichaelisMentenTranscription	Transcription_MichaelisMenten_Energy
Primary_Active_Transport_MM	PrimaryActiveMichaelisMentenTransport	Transport_PrimaryActive_MichaelisMenten
multi_tx	MultiStateTranscription	Transcription_MultiState

Suffix-style reads better for short names and worse for long ones — PrimaryActiveMichaelisMentenTransport is genuinely hard to parse and Transport_PrimaryActive_MichaelisMenten isn't. The underscore is the price of prefix-grouping, and it does buy something real.

Claude's Proposal

1. Family as a CapWords suffix. Three reasons, in order of weight:

• It's already the de facto convention in the healthy third of the library — SimpleTranscription, PositiveHillTranscription, NegativeHillTranscription, SimpleTranslation, BasicIntegration, EnzymeIntegration, BasicCatalysis, BasicProduction, OneStepPathway. Adopting it converts the remaining two-thirds rather than churning all 35.
• scikit-learn is the closest analog and made this call for a much larger library.
• The grouping a prefix would give us is already available in two better places — the module (mechanisms/binding.py) and mechanism_type. Duplicating a taxonomy into the class name lets it drift, which is arguably what happened to OneStepGeneExpression.

This axis is a taste call, though, and the remaining three points apply either way.

2. Promote mechanism_type to a class attribute. It's currently a constructor default, which is why AntiDilutionConstitutiveCreation has none and Transcription_MM sets it positionally inside the __init__ body instead of in the signature. As a class attribute it becomes introspectable without instantiation:

class Mechanism:
    mechanism_type: str = ''   # subclasses override

def list_mechanisms(mechanism_type=None):
    """Return mechanism classes, optionally filtered by type."""

That's the real discoverability fix — bcp.list_mechanisms('binding') beats any naming scheme, and it feeds docs/generate_library_docs.py so the autogenerated pages can group by family.

3. Expand the abbreviations. MM → MichaelisMenten, tx/tl → Transcription/Translation, Deg_Tagged → Tagged. PEP 8's keep-acronyms-uppercase rule (HTTPServer) is for genuine acronyms; MM is a surname pair and tx/tl are field jargon that won't read to a new user.

4. Freeze the default .name values in this pass. Rename classes, leave every name='...' default exactly as it is, and don't touch the TSVs. Those strings are data, not API. Aligning them to the new class names is worth doing, but it needs its own issue and a migration that updates all seven parameter files in the same commit — mixing it into a class rename is how we'd get silent wrong-parameter bugs. The two typos are the exception, since neither has a matching TSV row.

Backward compatibility

PEP 562 module __getattr__ is the clean mechanism, and NumPy 2.0 used exactly this for its removed aliases:

# biocrnpyler/mechanisms/__init__.py
_LEGACY_NAMES = {
    'Transcription_MM': 'MichaelisMentenTranscription',
    'multi_tx': 'MultiStateTranscription',
    # ...
}

def __getattr__(name):
    if name in _LEGACY_NAMES:
        new = _LEGACY_NAMES[name]
        warn(f"'{name}' is deprecated; use '{new}'", DeprecationWarning, stacklevel=2)
        return globals()[new]
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

Better than plain OldName = NewName aliases: it warns on use rather than on import, keeps legacy names out of dir() and the autogenerated docs, and leaves one table to delete at removal time. One caveat — bcp.Transcription_MM re-exported via the top-level from .mechanisms import * won't route through this, since import * resolves eagerly, so the same hook is needed in biocrnpyler/__init__.py.

[zjuradoq]

I am in favor with the MechType_primary_secondary prefix proposal. This format provides clarity when instantiating different mechanisms, making the mapping clean and intuitive (e.g., mechanism = {'transport': Transport_Name, 'transcription': Transcription_Name}).

Regarding the proposal to expand "MM" to "MichaelisMenten", I respectfully disagree. Expanding it increases the name length needlessly. I recommend keeping "MM" as an abbreviation.

Applying this prefix logic to the membrane mechanisms, here is my proposed naming scheme for the transport mechanisms:

Current Class Name	Proposed Name
Simple_Diffusion	Transport_Diffusion
Membrane_Protein_Integration	Integration_MembraneProtein
Simple_Transport	Transport_Pore
Facilitated_Transport_MM	Transport_Facilitated_MM
Primary_Active_Transport_MM	Transport_PrimaryActive_MM

We also need clear guidelines on how to distinguish 'primary' from 'secondary' modifiers to ensure consistency. For example, I suggest naming the energy-driven mechanism Transcription_Energy_MM rather than Transcription_MM_Energy. I would regard that the energy is the fundamental biological distinction (primary), whereas the Michaelis-Menten kinetics simply specify the mathematical model (secondary).

I will be actively rewriting and editing the membrane mechanisms over the next few days. I plan to use these proposed names unless we decide on a different approach. I will also keep track of the legacy names so they can be easily added to the _LEGACY_NAMES dictionary.