biocrnpyler.Species

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

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:

namestr

Name of the species. Must consist of letters, numbers, or underscores, cannot contain double underscores, and cannot begin/end with special characters.

material_typestr, default=’’

Type of material (e.g., ‘dna’, ‘rna’, ‘protein’, ‘complex’). Required if name starts with a number. Must start with a letter.

attributeslist of str or None, optional

List of attribute tags for the species (e.g., ‘degraded’, ‘phosphorylated’). Each attribute must be alphanumeric.

compartmentCompartment, 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:

namestr

The name of the species.

material_typestr

The material type of the species.

attributeslist of str

List of attribute tags associated with the species.

compartmentCompartment

The compartment containing this species.

directionstr, 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
... )

__init__(name: str, material_type='', attributes: List | None = None, compartment=None, **kwargs)

Initialize an OrderedMonomer.

Parameters:

directionstr, int, or None, optional

Directional orientation of the monomer. Default is None.

positionint or None, optional

Position index within the parent polymer. Default is None.

parentMonomerCollection or None, optional

Reference to the parent collection. Default is None.

Methods

__init__(name[, material_type, attributes, ...])	Initialize an OrderedMonomer.
add_attribute(attribute)	Add an attribute to the species.
contains_species_monomer(s)	Check if the species contains a monomer, ignoring context.
find_polymer_component()	Find the polymer component within this monomer or its species.
flatten_list(in_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([recursive])	Get a list containing this species.
monomer_eq(other)	Check if two monomers are equal, ignoring parent and position.
monomer_insert(parent, position[, direction])	Insert this monomer into a polymer at a specific position.
pretty_print([show_material, ...])	Generate a human-readable string representation of the species.
remove()	Remove the species from its parent polymer.
remove_attribute(attribute)	Remove an attribute from the species.
replace_species(species, new_species)	Replace a species with another species.
set_dir(direction)	Set the direction of the monomer and return self.
subhash()	Compute hash contribution from monomer properties.

Attributes

attributes
compartment
direction
material_type
name
parent
position

__eq__(other)

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:

otherSpecies

The species to compare with.

Returns:

bool

True if species are equivalent, False otherwise.

Notes

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

__gt__(Species2)

Return self>value.

__hash__()

Compute hash value for this monomer.

Returns:

int

Hash value based on position, direction, name (if present), and parent.

__lt__(Species2)

Return self<value.

add_attribute(attribute: str)

Add an attribute to the species.

Parameters:

attributestr

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)

Check if the species contains a monomer, ignoring context.

Parameters:

sSpecies

The species monomer to search for.

Returns:

bool

True if the species contains a monomer equal to s (ignoring parent, position, and direction), False otherwise.

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()

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:

OrderedMonomer or None

The monomer that is part of a polymer structure, or None if no polymer component is found.

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

Recursively flatten a nested list of species.

Parameters:

in_listlist or Species

A potentially nested list of species, or a single species.

Returns:

list

Flattened list containing all species. None elements are filtered out.

Examples

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

get_orphan()

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:

OrderedMonomer

A copy of this monomer with parent set to None but position and direction preserved.

See also

get_removed

Create a fully detached copy.

remove

Remove this monomer from its parent in place.

Notes

This is a shallow copy of the monomer object itself, though the parent reference is explicitly cleared.

get_removed()

Create a fully detached copy of this monomer.

Returns a copy with all polymer-related attributes (parent, position, direction) cleared. Also removes ‘forward’ and ‘reverse’ attributes if present.

Returns:

OrderedMonomer

A copy of this monomer with no parent, position, or direction, and with directional attributes removed.

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)

Get a list containing this species.

Returns:

list of Species

A list containing only this species: [self].

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)

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

Parameters:

otherSpecies

The species to compare with.

Returns:

bool

True if species have the same name, material_type, attributes, and compartment, regardless of parent or position.

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)

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:

parentOrderedPolymer

The polymer to insert this monomer into.

positionint

The position index where this monomer is being inserted.

directionstr, 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)

Generate a human-readable string representation of the species.

Parameters:

show_materialbool, default=True

If True, includes material_type in brackets around the species.

show_compartmentbool, default=False

If True, shows the compartment name in the representation.

show_attributesbool, default=True

If True, includes attributes in parentheses after the name.

show_initial_conditionbool, default=False

Placeholder for compatibility with CRN printing.

**kwargs

Additional keyword arguments (currently unused).

Returns:

str

Formatted string representation of the species.

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()

Remove the species from its parent polymer.

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

Returns:

Species

Returns self after removal for method chaining.

remove_attribute(attribute: str)

Remove an attribute from the species.

Parameters:

attributestr

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)

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:

speciesSpecies

The species to search for and replace.

new_speciesSpecies

The species to replace with.

Returns:

Species

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

Raises:

ValueError

If either argument is not a Species instance.

set_dir(direction)

Set the direction of the monomer and return self.

Convenience method for setting direction in a fluent interface style.

Parameters:

directionstr, int, or None

The direction to assign to this monomer.

Returns:

OrderedMonomer

Returns self for method chaining.

Examples

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

subhash()

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:

int

Hash value based on monomer-specific properties.

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.