biocrnpyler.core.Species

class biocrnpyler.core.Species(name: str, material_type='', attributes: List | None = None, compartment=None, **kwargs)[source]

Bases: OrderedMonomer

A formal species object for a chemical reaction network (CRN).

Represents a chemical species in a CRN with a name, material type, attributes, and compartment. Species inherits from OrderedMonomer, allowing it to be part of polymer structures while also functioning as an independent chemical entity in reactions.

Parameters:

name (str) – Name of the species. Must consist of letters, numbers, or underscores, cannot contain double underscores, and cannot begin/end with special characters.
material_type (str, default '') – Type of material (e.g., ‘dna’, ‘rna’, ‘protein’, ‘complex’). Required if name starts with a number. Must start with a letter.
attributes (list of str or None, optional) – List of attribute tags for the species (e.g., ‘degraded’, ‘phosphorylated’). Each attribute must be alphanumeric.
compartment (Compartment, str, or None, optional) – The compartment containing this species. If None, uses default compartment. If str, creates a new Compartment with that name.
**kwargs – Additional keyword arguments passed to OrderedMonomer.

Attributes:

name (str) – The name of the species.
material_type (str) – The material type of the species.
attributes (list of str) – List of attribute tags associated with the species.
compartment (Compartment) – The compartment containing this species.
direction (str, int, or None) – Directional orientation (inherited from OrderedMonomer). When set, the direction is also added as an attribute.

See also

ComplexSpecies: Species formed from multiple bound species.
OrderedPolymerSpecies: Polymer species for chemical reactions.
WeightedSpecies: Species with stoichiometry coefficient.

Notes

Species names must:

Contain only letters, numbers, and underscores
Not contain double underscores (‘__’)
Not end with an underscore
Start with a letter or number (if starting with number, requires material_type)

Species are represented as strings in the format:

material_type_name_attribute1_attribute2_compartment

Components are omitted if empty or default values.

Two species are equal if they have the same name, material_type, attributes, compartment, parent, and position.

Examples

Create a simple species:

>>> S = bcp.Species('S')
>>> S.name
'S'

Create a protein with attributes:

>>> GFP = bcp.Species(
...     name='GFP',
...     material_type='protein',
...     attributes=['fluorescent', 'degraded']
... )
>>> repr(GFP)
'protein_GFP_fluorescent_degraded'

Create a species in a compartment:

>>> cytoplasm = bcp.Compartment('cytoplasm')
>>> enzyme = bcp.Species(
...     name='enzyme',
...     material_type='protein',
...     compartment=cytoplasm
... )

Methods

`add_attribute`	Add an attribute to the species.
`contains_species_monomer`	Check if the species contains a monomer, ignoring context.
`find_polymer_component`	Find the polymer component within this monomer or its species.
`flatten_list`	Recursively flatten a nested list of species.
`get_orphan`	Create a copy of this monomer without a parent reference.
`get_removed`	Create a fully detached copy of this monomer.
`get_species`	Get a list containing this species.
`monomer_eq`	Check if two monomers are equal, ignoring parent and position.
`monomer_insert`	Insert this monomer into a polymer at a specific position.
`pretty_print`	Generate a human-readable string representation of the species.
`remove`	Remove the species from its parent polymer.
`remove_attribute`	Remove an attribute from the species.
`replace_species`	Replace a species with another species.
`set_dir`	Set the direction of the monomer and return self.
`subhash`	Compute hash contribution from monomer properties.

__eq__(other)[source]

Check if two species are equivalent.

Two species are equal if they have the same name, material_type, attributes (as sets), parent, compartment, and position.

Parameters:: other (Species) – The species to compare with.
Returns:: True if species are equivalent, False otherwise.
Return type:: bool

Notes

Equality between parents and children can result in loops, so string equality is used for parent comparison.

__gt__(Species2)[source]: Return self>value.

__lt__(Species2)[source]: Return self<value.

add_attribute(attribute: str)[source]

Add an attribute to the species.

Parameters:: attribute (str) – The attribute to add. Must be an alphanumeric string and non-None.
Raises:: AssertionError – If attribute is not an alphanumeric string or is None.

Notes

Duplicate attributes are not added - each attribute appears only once in the attributes list.

Examples

>>> species = bcp.Species('MyProtein')
>>> species.add_attribute('degraded')
>>> species.attributes
['degraded']

contains_species_monomer(s)[source]

Check if the species contains a monomer, ignoring context.

Parameters:: s (Species) – The species monomer to search for.
Returns:: True if the species contains a monomer equal to s (ignoring parent, position, and direction), False otherwise.
Return type:: bool

Notes

This is a less stringent version of __contains__ that checks without considering Species.parent, Species.position, or direction. Useful for determining if a species is present regardless of its polymer context.

find_polymer_component()[source]

Find the polymer component within this monomer or its species.

Searches this monomer and, if it is a ComplexSpecies, its constituent species to find which one is marked as a polymer component.

Returns:: The monomer that is part of a polymer structure, or None if no polymer component is found.
Return type:: OrderedMonomer or None
Raises:: ValueError – If multiple species are marked as polymer components in the same location.

Notes

This method is primarily used internally to handle complex species that may contain monomers as part of larger structures.

static flatten_list(in_list) → List[source]

Recursively flatten a nested list of species.

Parameters:: in_list (list or Species) – A potentially nested list of species, or a single species.
Returns:: Flattened list containing all species. None elements are filtered out.
Return type:: list

Examples

>>> S1 = bcp.Species('S1')
>>> S2 = bcp.Species('S2')
>>> nested = [S1, [S2, None]]
>>> bcp.Species.flatten_list(nested)
[S1, S2]

get_orphan()[source]

Create a copy of this monomer without a parent reference.

Returns a copy that retains position and direction but has no parent polymer. Useful for temporarily working with monomers outside their polymer context.

Returns:: A copy of this monomer with parent set to None but position and direction preserved.
Return type:: OrderedMonomer

See also

get_orphan: Create a copy without parent but with position and direction.
remove: Remove this monomer from its parent in place.

Notes

This method is useful for creating completely independent copies of monomers that can be reused in different contexts without any polymer associations.

get_species(recursive=None)[source]

Get a list containing this species.

Returns:: A list containing only this species: [self].
Return type:: list of Species

Notes

This method is used in recursive calls where ComplexSpecies returns a list of constituent species while Species returns just itself in a list. The recursive parameter is accepted for compatibility but not used in the base Species class.

monomer_eq(other)[source]

Check if two monomers are equal, ignoring parent and position.

Parameters:: other (Species) – The species to compare with.
Returns:: True if species have the same name, material_type, attributes, and compartment, regardless of parent or position.
Return type:: bool

Notes

This is the same as normal equality but does not check for parents or positions. Useful for comparing species that may be in different polymer contexts.

monomer_insert(parent: OrderedPolymer, position: int, direction=None)[source]

Insert this monomer into a polymer at a specific position.

Sets the monomer’s parent, position, and direction attributes to reflect its insertion into the polymer. Marks the monomer (or its polymer component if it is a complex species) as a polymer component.

Parameters:

parent (OrderedPolymer) – The polymer to insert this monomer into.
position (int) – The position index where this monomer is being inserted.
direction (str, int, or None, optional) – The direction for this monomer. If None, uses the monomer’s existing direction.

Raises:

ValueError – If position is None, or if parent is None.

pretty_print(show_material=True, show_compartment=False, show_attributes=True, show_initial_condition=False, **kwargs)[source]

Generate a human-readable string representation of the species.

Parameters:

show_material (bool, default True) – If True, includes material_type in brackets around the species.
show_compartment (bool, default False) – If True, shows the compartment name in the representation.
show_attributes (bool, default True) – If True, includes attributes in parentheses after the name.
show_initial_condition (bool, default False) – Placeholder for compatibility with CRN printing.
**kwargs – Additional keyword arguments (currently unused).

Returns:

Formatted string representation of the species.

Return type:

str

Notes

This method provides more detailed output than __repr__, useful for understanding CRNs but does not return string identifiers compatible with parsers.

Format: material_type[name(attr1, attr2)-direction]

Examples

>>> S = bcp.Species('S', material_type='protein',
...                 attributes=['active'])
>>> S.pretty_print()
'protein[S(active)]'

remove()[source]

Remove the species from its parent polymer.

Overrides OrderedMonomer.remove to also remove the direction attribute if present.

Returns:: Returns self after removal for method chaining.
Return type:: Species

remove_attribute(attribute: str)[source]

Remove an attribute from the species.

Parameters:: attribute (str) – The attribute to remove. Must be an alphanumeric string.

Notes

If the attribute is not present or is None, no action is taken. All occurrences of the attribute are removed from the attributes list.

replace_species(species, new_species)[source]

Replace a species with another species.

For a simple Species, returns new_species if this species equals species, otherwise returns self. For complex species, acts recursively.

Parameters:

species (Species) – The species to search for and replace.
new_species (Species) – The species to replace with.

Returns:

Either new_species (if self == species) or self.

Return type:

Species

Raises:

ValueError – If either argument is not a Species instance.

set_dir(direction)[source]

Set the direction of the monomer and return self.

Convenience method for setting direction in a fluent interface style.

Parameters:: direction (str, int, or None) – The direction to assign to this monomer.
Returns:: Returns self for method chaining.
Return type:: OrderedMonomer

Examples

>>> monomer = bcp.OrderedMonomer().set_dir('forward')
>>> monomer.direction
'forward'

subhash()[source]

Compute hash contribution from monomer properties.

Computes a hash value based on the monomer’s position, direction, and name (if present), excluding the parent reference.

Returns:: Hash value based on monomer-specific properties.
Return type:: int

Notes

This method is used by __hash__ to compute the monomer’s hash contribution. It excludes the parent to avoid circular dependencies in hash computation.