biocrnpyler.core.OrderedPolymer

class biocrnpyler.core.OrderedPolymer(parts, default_direction=None)[source]

Bases: MonomerCollection

A polymer made up of OrderedMonomers with a specific order.

Represents a linear sequence of monomers where each monomer has a defined position and direction. This class extends MonomerCollection to provide ordered, directional polymer structures commonly used to represent DNA constructs, RNA sequences, and protein chains.

Parameters:

parts (list or tuple) –
Sequence of parts to add to the polymer. Each element can be:
- An OrderedMonomer object (uses existing direction)
- A list/tuple [OrderedMonomer, direction] specifying monomer and its direction explicitly
default_direction (str or int, optional) – Default direction for monomers when not explicitly specified. Common values include ‘forward’, ‘reverse’, 0, 1, or None.

Attributes:

polymer (tuple of OrderedMonomer) – Ordered tuple of monomers in this polymer. Alias for monomers property inherited from MonomerCollection.
default_direction (str, int, or None) – Default direction assigned to monomers lacking explicit direction.

See also

NamedPolymer: An OrderedPolymer with an associated name.
OrderedMonomer: A unit that belongs to an OrderedPolymer.
MonomerCollection: Base class for monomer collections.

Notes

Directions indicate the orientation of monomers in the polymer:

‘forward’ or 0: Standard/positive orientation
‘reverse’ or 1: Inverted/negative orientation
None: No specified orientation

The polymer tuple is immutable, but monomers can be added via insert, append, or replace methods. Direct assignment to positions uses __setitem__ which calls replace.

All monomers are deep-copied when added to ensure the polymer maintains independent references. This prevents external modifications from affecting the polymer structure.

Examples

Create a polymer from monomers:

>>> mon1 = bcp.OrderedMonomer()
>>> mon2 = bcp.OrderedMonomer()
>>> polymer = bcp.OrderedPolymer(
...     parts=[mon1, mon2],
...     default_direction='forward'
... )
>>> len(polymer)
2

Create a polymer with explicit directions:

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

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)[source]

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)[source]

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)[source]

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__()[source]

Return the number of monomers in the polymer.

Returns:: The number of monomers in the polymer sequence.
Return type:: int

__setitem__(ii, val)[source]

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)[source]

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()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

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'