Docstring updates

[murrayrm]

This PR provides updated docstrings for components, mechanisms, mixtures, and core classes and functions. Existing docstrings were converted to NumPy format (with numpydoc conventions) and missing docstrings were added, along with examples.

I used Claude to generate the docstrings and then checked them all to make sure they made sense and that the examples ran. Here is the prompt that was used for Claude (Opus 4.1 and Sonnet 4.5):

I would like your help in writing docstrings for a Python package called 'BioCRNpyler" (imported as 'bcp'). I have added files from the Git repository to the project so that you have access to the code and user documention. I am writing the documentaion in NumPy style, using Sphinx and numpydocs.

For each file in the package, I will attached the current version of the file, which has been modified from what is in the repository, I would like you to generate properly formatted numpydoc-style docstrings for all classes, methods, and fucntions in the file, following the NumPy doc format and the guidelines in the BioCRNpyler Developer Notes (available in the project files). You should then insert them directly into the code (for example using str_replace tool) and return a file with the updated docstrings.

I am attaching two example files (component.py and chemical_reaction_network.py) that are examples from previous sessions. Please use these as a guide.

Some additional notes:

• I use a line length limit of 78 characters. Please respect this when writing the docstrings.
• I use single quotes for strings.
• When you generate numbered or unnumbered lists, make sure to leave a blank line prior to the start of the list, otherwise Sphinx doesn't process it properly.
• When you describe mechanisms (e.g. 'binding') or parameters (e.g. 'kb' and 'ku') put them in single quotes.
• Assume that BioCRNpyler has been imported and is available with prefix 'bcp'.
• Assume that NumPy has been imported and is available with prefix 'np'.

Confirm that you understand the instructions and then I will give you the files one at a time.

In addition, specialized prompts were used for DNA components, mechanisms, and mixtures:

DNA components: The first set of files I am going to give you are for DNA components. These files define a set of Component subclasses that are used to define genetic constructions (DNA --> RNA --> protein). The main component is a DNA assembly, and so I will start with that one, then give you the files for the different elements (promoters, RBS, coding sequence, etc).

Mechanisms: The set of files I am going to give you are for mechanisms. Make sure to list all of the parameters that are required for that mechanism in the notes section, enclosed in single quotes. Make sure to list all of the parameters that are required for the mechanism in the notes section, in single quotes (e.g., 'ku' or 'kb').

I'm attaching two examples of mechanism files, 'binding.py' and 'global_mechanisms.py', that can be used as a rough template for what I am looking for. Note in particular that examples are included at the class level, but not within internal methods.

Mixtures: I would now like to process some mixtures. Here are some specific instructions:

• In the Notes section, list the default mechanisms included in the mixture. For each mechanism, specify:
  • The mechanism type (in single quotes, e.g., 'transcription')
  • The explicit mechanism class name (in backticks, e.g., Transcription_MM)
  • A brief description of what the mechanism does, including the reaction scheme where appropriate
• Include Examples at the class level that show how to create a mixture using bcp.DNAassembly components
• In examples, use the components and parameter_file keywords in the constructor to create the complete mixture in one call
• Create a "mixture" (not "extract") in the examples
• Keep examples simple and focused on the main use case

In addition to the updated docstrings, a few changes were made to the code:

• The degredase keyword in the Deg_Tagged_Degradation global mechanism was changed to degradase (corrected spelling)
• The AnitDilutionConstiutiveCreation global mechanism was renamed AntiDilutionConstitutiveCreation (corrected spellings)

Some requests:

• @dr3y It would be great if you could do a quick check on the many classes you contributed around enumeration and DNA constructs and make sure the doc strings make sense.
• @zjuradoq It would be great if you could do a quick check on the membrane-related components and mechanisms and make sure they make sense.
• @WilliamIX, @ayush9pandey: Feedback welcome on this choice of format and whether there are other changes we should make to docstrings as part of this PR.

[ayush9pandey]

I think this line "produces no reactions on its own" is added to the docstrings of all components but it is slightly misleading. Components are not supposed to produce reaction by definition. For example, when the RBS component updates the reactions it calls on the mechanism to do it:

def update_reactions(self):
        mech_tl = self.get_mechanism('translation')
        reactions = []

        if self.protein is not None:
            reactions += mech_tl.update_reactions(
                transcript=self.transcript,
                protein=self.protein,
                component=self,
                part_id=self.name,
            )
        return reactions

I think I can go in and edit this to clarify in all such component docstrings..

[murrayrm]

Suggestions for better wording for components that do not have an associated mechanism and hence don't cause reactions to be generated?

Perhaps "This component has no associated mechanism to generate species or reactions, but can be used to represent mRNA, tRNA, rRNA, or other RNA molecules."?

[ayush9pandey]

Yes, that is a good re-wording.

[ayush9pandey]

Similar to the previous comment, I am not sure if the component "generates a reaction". The code below gets the mechanism to associate it with the component and then the mechanism generates the reactions. I understand that this is perhaps minor but it's also core to how biocrnpyler was designed.

[murrayrm]

Is there better wording we can use? The description section of the docstring makes clear that it is the 'binding' mechanism that generates the reactions, but I agree that the summary line is misleading.

Summary lines are supposed to be short (65 characters or less, I think), so we have to keep the wording tight. Some possibilities:

• "Call 'binding' mechanism to generate component reactions." (55 chars)
• "Use 'binding' mechanism to create binding/unbinding reactions." (64 chars)
• "Apply 'binding' mechanism to generate complex reactions." (57 chars)

[murrayrm]

Also: do we want to use similar wording for update_species?

[ayush9pandey]

I like either the first or the second possibilities you listed out: ""Call 'binding' mechanism to generate component reactions." or "Use...."

and yes, we might similarly re-word update_species in the components.

[ayush9pandey]

Do we want to add here that bioscrape simulation is built into biocrnpyler..

[ayush9pandey]

This is great. I skimmed through the docstrings and read some of the ones in core classes in detail. It looks good to me.

[murrayrm]

I've addressed @ayush9pandey's comments. I've got some more documentation updates coming (for the reference manual), so my plan is to merge this tomorrow (Sun) unless someone (e.g., @dr3y, @zjuradoq, or @WilliamIX) let me know they would like me to wait so that they can look through things (definitely not urgent; these are just docstrings and we can modify them later).

[zjuradoq]

@murrayrm I’ve reviewed the updates to the membrane components and mechanism, and everything looks correct. The updated docstrings are really well written and clearly described.

[ayush9pandey]

Thank you for all the changes. Looks great!!