biocrnpyler.core.NamedPolymer

class biocrnpyler.core.NamedPolymer(parts, name, default_direction=None, circular=False)

Bases: OrderedPolymer

An OrderedPolymer with an associated name and circularity flag.

Extends OrderedPolymer to include a name identifier and optional circular topology flag. Commonly used to represent named biological constructs like plasmids, chromosomes, or specific DNA/RNA sequences.

Parameters:

• parts (list or tuple) – Sequence of parts to add to the polymer. See OrderedPolymer for format details.

• name (str) – Name identifier for the polymer.

• default_direction (str, int, or None, optional) – Default direction for monomers when not explicitly specified.

• circular (bool, default False) – If True, indicates the polymer has circular topology (e.g., a plasmid). If False, the polymer is linear.

Attributes:

• name (str) – Name identifier for the polymer.

• circular (bool) – Flag indicating circular (True) or linear (False) topology.

• polymer (tuple of OrderedMonomer) – Ordered tuple of monomers in this polymer (inherited).

• default_direction (str, int, or None) – Default direction for monomers (inherited).

See also

OrderedPolymer

Base class for ordered polymer structures.

OrderedMonomer

A unit that belongs to an OrderedPolymer.

Notes

The circular attribute is primarily informational and does not automatically enforce circular topology constraints in polymer operations. Subclasses or external code must handle circular semantics as needed.

Examples

Create a linear named polymer:

>>> mon1 = bcp.OrderedMonomer()
>>> mon2 = bcp.OrderedMonomer()
>>> polymer = bcp.NamedPolymer(
...     parts=[mon1, mon2],
...     name='my_construct',
...     default_direction='forward'
... )
>>> polymer.name
'my_construct'
>>> polymer.circular
False

Create a circular polymer (plasmid):

>>> plasmid = bcp.NamedPolymer(
...     parts=[mon1, mon2],
...     name='pUC19',
...     circular=True
... )
>>> plasmid.circular
True

Methods

append	Add a monomer to the end of the polymer.
changed	Callback method invoked whenever the polymer structure changes.
delpart	Remove a monomer from the polymer at a specific position.
direction_invert	Invert a direction value.
insert	Insert a monomer at a specific position in the polymer.
replace	Replace a monomer at a specific position in the polymer.
reverse	Reverse the order and directions of all monomers in the polymer.

__contains__(item)

Check if a monomer is in the polymer.

Parameters:

item (OrderedMonomer) – The monomer to search for.

Returns:

True if the monomer is in the polymer, False otherwise.

Return type:

bool

__eq__(other)

Check equality with another OrderedPolymer.

Two polymers are equal if they have the same length and each corresponding pair of monomers has the same direction, position, and type.

Parameters:

other (OrderedPolymer) – The polymer to compare with.

Returns:

True if polymers are equal, False otherwise.

Return type:

bool

__getitem__(ii)

Get a monomer or slice of monomers from the polymer.

Parameters:

ii (int or slice) – Index or slice to retrieve from the polymer.

Returns:

The monomer at the given index, or a tuple of monomers for a slice.

Return type:

OrderedMonomer or tuple

__len__()

Return the number of monomers in the polymer.

Returns:

The number of monomers in the polymer sequence.

Return type:

int

__setitem__(ii, val)

Replace a monomer at a specific position.

Parameters:

• ii (int) – Index at which to replace the monomer.

• val (OrderedMonomer) – The new monomer to insert at the position.

Notes

Internally calls replace with the monomer’s existing direction.

append(part, direction=None)

Add a monomer to the end of the polymer.

Appends a copy of the given monomer to the end of the polymer sequence by calling insert at the final position.

Parameters:

• part (OrderedMonomer) – The monomer to append. A copy of this monomer will be added.

• direction (str, int, or None, optional) – Direction for the appended monomer. If None, uses the monomer’s existing direction if available.

See also

insert

Insert a monomer at a specific position.

Examples

>>> polymer = bcp.OrderedPolymer(parts=[])
>>> mon = bcp.OrderedMonomer()
>>> polymer.append(mon, direction='forward')
>>> len(polymer)
1

changed()

Callback method invoked whenever the polymer structure changes.

This method is called after operations that modify the polymer, such as insert, replace, delpart, or reverse. Subclasses can override this to implement custom behavior when the polymer is modified.

Notes

The base implementation does nothing. Override in subclasses to add functionality like name regeneration, validation, or notifications.

delpart(position)

Remove a monomer from the polymer at a specific position.

Removes the monomer at the given position, shifts all subsequent monomers to lower positions, and calls the changed callback.

Parameters:

position (int) – Index of the monomer to remove. Must be a valid position in the polymer.

See also

replace

Replace a monomer at a specific position.

insert

Insert a monomer at a specific position.

Notes

The removed monomer’s remove method is called to clear its parent, position, and direction. If the polymer has a name attribute and a make_name method, the name is regenerated after deletion.

direction_invert(dirname)

Invert a direction value.

Converts a direction to its opposite orientation. Used during polymer reversal operations.

Parameters:

dirname (str, int, or None) –

The direction to invert. Supported values:

• ’forward’ \(\rightleftharpoons\) ‘reverse’

• 0 \(\rightleftharpoons\) 1

• None -> None

Returns:

The inverted direction. Returns the input unchanged if it cannot be inverted.

Return type:

str, int, or None

Warns:

UserWarning – If the direction value is not recognized.

Examples

>>> polymer = bcp.OrderedPolymer(parts=[])
>>> polymer.direction_invert('forward')
'reverse'
>>> polymer.direction_invert(0)
1

insert(position, part, direction=None)

Insert a monomer at a specific position in the polymer.

Inserts a copy of the given monomer at the specified position, shifting all subsequent monomers to higher positions. Calls the changed callback after insertion.

Parameters:

• position (int) – Index at which to insert the monomer. Must be between 0 and len(polymer) (inclusive).

• part (OrderedMonomer) – The monomer to insert. A copy of this monomer will be added.

• direction (str, int, or None, optional) – Direction for the inserted monomer. If None, uses the monomer’s existing direction.

See also

append

Add a monomer to the end of the polymer.

replace

Replace a monomer at a specific position.

Notes

The monomer is deep-copied before insertion to maintain independence from the original object.

replace(position, part, direction=None)

Replace a monomer at a specific position in the polymer.

Removes the monomer at the given position and inserts a copy of the new monomer in its place. Calls the changed callback after replacement.

Parameters:

• position (int) – Index of the monomer to replace. Must be a valid position in the polymer.

• part (OrderedMonomer) – The monomer to insert. A copy of this monomer will be added.

• direction (str, int, or None, optional) – Direction for the new monomer. If None, uses the monomer’s existing direction.

See also

insert

Insert a monomer at a specific position.

delpart

Remove a monomer from the polymer.

Notes

The removed monomer’s remove method is called to clear its parent, position, and direction attributes.

reverse()

Reverse the order and directions of all monomers in the polymer.

Reverses the polymer sequence and inverts the direction of each monomer. Updates all monomer positions to reflect their new locations. Calls the changed callback after reversal.

Notes

This operation modifies the polymer in place. All monomers have their directions inverted using direction_invert and their positions updated to match the reversed sequence.

Examples

>>> mon1 = bcp.OrderedMonomer()
>>> mon2 = bcp.OrderedMonomer()
>>> polymer = bcp.OrderedPolymer(
...     parts=[[mon1, 'forward'], [mon2, 'reverse']]
... )
>>> polymer.reverse()
>>> polymer[0].direction
'forward'
>>> polymer[1].direction
'reverse'