Repository: cogent3/cogent3
Pull request #2133 (2024-11-25 03:40:02)

ENH: repr of new Aligned
## Summary by Sourcery

Refactor the __repr__ method of the Aligned class to enhance its string representation. Update the test for alignment indexing to reflect changes in the __repr__ method. Add a changelog entry highlighting the major rewrite of alignment classes, which unifies previous classes into a single, more efficient class.

Enhancements:
- Refactor the __repr__ method of the Aligned class to provide a more informative string representation, including name, sequence, and moltype.

Documentation:
- Add a changelog entry describing the major rewrite of alignment classes, unifying Alignment and AlignmentArray into a single class with improved performance and a largely backwards-compatible API.


Patch:
diff --git a/changelog.d/20241125_084555_Gavin.Huttley.md b/changelog.d/20241125_084555_Gavin.Huttley.md
new file mode 100644
index 000000000..d4e15f6d6
--- /dev/null
+++ b/changelog.d/20241125_084555_Gavin.Huttley.md
@@ -0,0 +1,47 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+### Contributors
+
+- Many thousand lines of code --- @KatherineCaley 🚀
+
+
+### ENH
+
+- The grand rewrite of alignment classes is ready for use! This is a major effort,
+  unifying the capabilities of the `Alignment` and `AlignmentArray` classes into a
+  single class. The logic is cleaner, the performance is better, and the API is
+  largely (but not entirely) backwards compatible. The new approach gives us the
+  foundation for major performance improvements in the future. As with the
+  moltype, alphabet, genetic code and SequenceCollection, you can select the new
+  class via `make_aligned_seqs()` or `load_aligned_seqs()` by specifying new_type=True.
+  Please post any bugs or issues to the issue tracker.
+
+
+<!--
+### BUG
+
+- A bullet item for the BUG category.
+
+-->
+<!--
+### DOC
+
+- A bullet item for the DOC category.
+
+-->
+<!--
+### Deprecations
+
+- A bullet item for the Deprecations category.
+
+-->
+<!--
+### Discontinued
+
+- A bullet item for the Discontinued category.
+
+-->
diff --git a/doc/api/index.rst b/doc/api/index.rst
index bd9f2b307..8a4c2d621 100644
--- a/doc/api/index.rst
+++ b/doc/api/index.rst
@@ -98,6 +98,19 @@ The Major cogent3 Data Types
     table/table
     tree/tree
 
+****************************
+NEW Major cogent3 Data Types
+****************************
+
+.. toctree::
+    :maxdepth: 1
+
+    new_alignment/alignment
+    new_sequence/sequence
+    new_genetic_code/genetic_code
+    new_moltype/moltype
+    new_alphabet/alphabet
+
 ***************
 Composable Apps
 ***************
diff --git a/doc/api/new_alignment/alignment.rst b/doc/api/new_alignment/alignment.rst
new file mode 100644
index 000000000..d610024ef
--- /dev/null
+++ b/doc/api/new_alignment/alignment.rst
@@ -0,0 +1,17 @@
+:mod:`new_alignment`
+====================
+
+.. currentmodule:: cogent3.core.new_alignment
+
+.. autosummary::
+    :toctree: classes
+    :template: class.rst
+
+    SeqsData
+    SeqDataView
+    SequenceCollection
+    AlignedSeqsData
+    AlignedDataView
+    Aligned
+    Alignment
+
diff --git a/doc/api/new_alignment/classes/cogent3.core.new_alignment.Aligned.rst b/doc/api/new_alignment/classes/cogent3.core.new_alignment.Aligned.rst
new file mode 100644
index 000000000..b99227734
--- /dev/null
+++ b/doc/api/new_alignment/classes/cogent3.core.new_alignment.Aligned.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_alignment.Aligned
+===================================
+
+.. currentmodule:: cogent3.core.new_alignment
+
+.. autoclass:: Aligned
\ No newline at end of file
diff --git a/doc/api/new_alignment/classes/cogent3.core.new_alignment.AlignedDataView.rst b/doc/api/new_alignment/classes/cogent3.core.new_alignment.AlignedDataView.rst
new file mode 100644
index 000000000..e1edad24a
--- /dev/null
+++ b/doc/api/new_alignment/classes/cogent3.core.new_alignment.AlignedDataView.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_alignment.AlignedDataView
+===========================================
+
+.. currentmodule:: cogent3.core.new_alignment
+
+.. autoclass:: AlignedDataView
\ No newline at end of file
diff --git a/doc/api/new_alignment/classes/cogent3.core.new_alignment.AlignedSeqsData.rst b/doc/api/new_alignment/classes/cogent3.core.new_alignment.AlignedSeqsData.rst
new file mode 100644
index 000000000..31f64c738
--- /dev/null
+++ b/doc/api/new_alignment/classes/cogent3.core.new_alignment.AlignedSeqsData.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_alignment.AlignedSeqsData
+===========================================
+
+.. currentmodule:: cogent3.core.new_alignment
+
+.. autoclass:: AlignedSeqsData
\ No newline at end of file
diff --git a/doc/api/new_alignment/classes/cogent3.core.new_alignment.Alignment.rst b/doc/api/new_alignment/classes/cogent3.core.new_alignment.Alignment.rst
new file mode 100644
index 000000000..d99330261
--- /dev/null
+++ b/doc/api/new_alignment/classes/cogent3.core.new_alignment.Alignment.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_alignment.Alignment
+=====================================
+
+.. currentmodule:: cogent3.core.new_alignment
+
+.. autoclass:: Alignment
\ No newline at end of file
diff --git a/doc/api/new_alignment/classes/cogent3.core.new_alignment.SeqDataView.rst b/doc/api/new_alignment/classes/cogent3.core.new_alignment.SeqDataView.rst
new file mode 100644
index 000000000..6246dd33c
--- /dev/null
+++ b/doc/api/new_alignment/classes/cogent3.core.new_alignment.SeqDataView.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_alignment.SeqDataView
+=======================================
+
+.. currentmodule:: cogent3.core.new_alignment
+
+.. autoclass:: SeqDataView
\ No newline at end of file
diff --git a/doc/api/new_alignment/classes/cogent3.core.new_alignment.SeqsData.rst b/doc/api/new_alignment/classes/cogent3.core.new_alignment.SeqsData.rst
new file mode 100644
index 000000000..6d86bf037
--- /dev/null
+++ b/doc/api/new_alignment/classes/cogent3.core.new_alignment.SeqsData.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_alignment.SeqsData
+====================================
+
+.. currentmodule:: cogent3.core.new_alignment
+
+.. autoclass:: SeqsData
\ No newline at end of file
diff --git a/doc/api/new_alignment/classes/cogent3.core.new_alignment.SequenceCollection.rst b/doc/api/new_alignment/classes/cogent3.core.new_alignment.SequenceCollection.rst
new file mode 100644
index 000000000..b8ee1c374
--- /dev/null
+++ b/doc/api/new_alignment/classes/cogent3.core.new_alignment.SequenceCollection.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_alignment.SequenceCollection
+==============================================
+
+.. currentmodule:: cogent3.core.new_alignment
+
+.. autoclass:: SequenceCollection
\ No newline at end of file
diff --git a/doc/api/new_alphabet/alphabet.rst b/doc/api/new_alphabet/alphabet.rst
new file mode 100644
index 000000000..21923edd4
--- /dev/null
+++ b/doc/api/new_alphabet/alphabet.rst
@@ -0,0 +1,11 @@
+:mod:`new_alphabet`
+===================
+
+.. currentmodule:: cogent3.core.new_alphabet
+
+.. autosummary::
+    :toctree: classes
+    :template: class.rst
+
+    CharAlphabet
+    KmerAlphabet
diff --git a/doc/api/new_alphabet/classes/cogent3.core.new_alphabet.CharAlphabet.rst b/doc/api/new_alphabet/classes/cogent3.core.new_alphabet.CharAlphabet.rst
new file mode 100644
index 000000000..899b3e344
--- /dev/null
+++ b/doc/api/new_alphabet/classes/cogent3.core.new_alphabet.CharAlphabet.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_alphabet.CharAlphabet
+=======================================
+
+.. currentmodule:: cogent3.core.new_alphabet
+
+.. autoclass:: CharAlphabet
\ No newline at end of file
diff --git a/doc/api/new_alphabet/classes/cogent3.core.new_alphabet.KmerAlphabet.rst b/doc/api/new_alphabet/classes/cogent3.core.new_alphabet.KmerAlphabet.rst
new file mode 100644
index 000000000..f0665dd98
--- /dev/null
+++ b/doc/api/new_alphabet/classes/cogent3.core.new_alphabet.KmerAlphabet.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_alphabet.KmerAlphabet
+=======================================
+
+.. currentmodule:: cogent3.core.new_alphabet
+
+.. autoclass:: KmerAlphabet
\ No newline at end of file
diff --git a/doc/api/new_genetic_code/classes/cogent3.core.new_genetic_code.GeneticCode.rst b/doc/api/new_genetic_code/classes/cogent3.core.new_genetic_code.GeneticCode.rst
new file mode 100644
index 000000000..9289bc02d
--- /dev/null
+++ b/doc/api/new_genetic_code/classes/cogent3.core.new_genetic_code.GeneticCode.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_genetic\_code.GeneticCode
+===========================================
+
+.. currentmodule:: cogent3.core.new_genetic_code
+
+.. autoclass:: GeneticCode
\ No newline at end of file
diff --git a/doc/api/new_genetic_code/genetic_code.rst b/doc/api/new_genetic_code/genetic_code.rst
new file mode 100644
index 000000000..472f68ef3
--- /dev/null
+++ b/doc/api/new_genetic_code/genetic_code.rst
@@ -0,0 +1,10 @@
+:mod:`new_genetic_code`
+=======================
+
+.. currentmodule:: cogent3.core.new_genetic_code
+
+.. autosummary::
+    :toctree: classes
+    :template: class.rst
+
+    GeneticCode
diff --git a/doc/api/new_moltype/classes/cogent3.core.new_moltype.MolType.rst b/doc/api/new_moltype/classes/cogent3.core.new_moltype.MolType.rst
new file mode 100644
index 000000000..249bd0eeb
--- /dev/null
+++ b/doc/api/new_moltype/classes/cogent3.core.new_moltype.MolType.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_moltype.MolType
+=================================
+
+.. currentmodule:: cogent3.core.new_moltype
+
+.. autoclass:: MolType
\ No newline at end of file
diff --git a/doc/api/new_moltype/moltype.rst b/doc/api/new_moltype/moltype.rst
new file mode 100644
index 000000000..1cdbc6a8a
--- /dev/null
+++ b/doc/api/new_moltype/moltype.rst
@@ -0,0 +1,10 @@
+:mod:`new_moltype`
+==================
+
+.. currentmodule:: cogent3.core.new_moltype
+
+.. autosummary::
+    :toctree: classes
+    :template: class.rst
+
+    MolType
diff --git a/doc/api/new_sequence/classes/cogent3.core.new_sequence.DnaSequence.rst b/doc/api/new_sequence/classes/cogent3.core.new_sequence.DnaSequence.rst
new file mode 100644
index 000000000..8d03062cc
--- /dev/null
+++ b/doc/api/new_sequence/classes/cogent3.core.new_sequence.DnaSequence.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_sequence.DnaSequence
+======================================
+
+.. currentmodule:: cogent3.core.new_sequence
+
+.. autoclass:: DnaSequence
\ No newline at end of file
diff --git a/doc/api/new_sequence/classes/cogent3.core.new_sequence.ProteinSequence.rst b/doc/api/new_sequence/classes/cogent3.core.new_sequence.ProteinSequence.rst
new file mode 100644
index 000000000..b81ddfd63
--- /dev/null
+++ b/doc/api/new_sequence/classes/cogent3.core.new_sequence.ProteinSequence.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_sequence.ProteinSequence
+==========================================
+
+.. currentmodule:: cogent3.core.new_sequence
+
+.. autoclass:: ProteinSequence
\ No newline at end of file
diff --git a/doc/api/new_sequence/classes/cogent3.core.new_sequence.RnaSequence.rst b/doc/api/new_sequence/classes/cogent3.core.new_sequence.RnaSequence.rst
new file mode 100644
index 000000000..7429ff3e9
--- /dev/null
+++ b/doc/api/new_sequence/classes/cogent3.core.new_sequence.RnaSequence.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_sequence.RnaSequence
+======================================
+
+.. currentmodule:: cogent3.core.new_sequence
+
+.. autoclass:: RnaSequence
\ No newline at end of file
diff --git a/doc/api/new_sequence/classes/cogent3.core.new_sequence.SeqView.rst b/doc/api/new_sequence/classes/cogent3.core.new_sequence.SeqView.rst
new file mode 100644
index 000000000..39840dde7
--- /dev/null
+++ b/doc/api/new_sequence/classes/cogent3.core.new_sequence.SeqView.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_sequence.SeqView
+==================================
+
+.. currentmodule:: cogent3.core.new_sequence
+
+.. autoclass:: SeqView
\ No newline at end of file
diff --git a/doc/api/new_sequence/classes/cogent3.core.new_sequence.SliceRecord.rst b/doc/api/new_sequence/classes/cogent3.core.new_sequence.SliceRecord.rst
new file mode 100644
index 000000000..1daced23f
--- /dev/null
+++ b/doc/api/new_sequence/classes/cogent3.core.new_sequence.SliceRecord.rst
@@ -0,0 +1,6 @@
+﻿cogent3.core.new\_sequence.SliceRecord
+======================================
+
+.. currentmodule:: cogent3.core.new_sequence
+
+.. autoclass:: SliceRecord
\ No newline at end of file
diff --git a/doc/api/new_sequence/sequence.rst b/doc/api/new_sequence/sequence.rst
new file mode 100644
index 000000000..5ec09e335
--- /dev/null
+++ b/doc/api/new_sequence/sequence.rst
@@ -0,0 +1,14 @@
+:mod:`new_sequence`
+===================
+
+.. currentmodule:: cogent3.core.new_sequence
+
+.. autosummary::
+    :toctree: classes
+    :template: class.rst
+
+    DnaSequence
+    RnaSequence
+    ProteinSequence
+    SeqView
+    SliceRecord
diff --git a/src/cogent3/core/new_alignment.py b/src/cogent3/core/new_alignment.py
index cc825aa1d..4df43ebc1 100644
--- a/src/cogent3/core/new_alignment.py
+++ b/src/cogent3/core/new_alignment.py
@@ -160,19 +160,13 @@ def _gap_ok_vector_multi(
 
 class SeqDataView(new_sequence.SeqView):
     """
-    A view class for SeqsData, providing methods for different representations
-    of a single sequence.
-
-    self.seq is a SeqsData() instance, but other properties are a reference to a
-    single seqid only.
+    A view class for ``SeqsData``, providing methods for different
+    representations of a single sequence.
 
-    Example
-    -------
-    data = {"seq1": "ACGT", "seq2": "GTTTGCA"}
-    sd = SeqsData(data=data)
-    sdv = sd.get_seq_view(seqid="seq1")
-    sdv.array_value
-    # array([3, 1, 2, 0], dtype=int8)
+    Notes
+    -----
+    ``str_value`` / ``array_value`` are not complemented, but can be reversed.
+    The latter is done by the ``Sequence`` object which has a moltype.
     """
 
     __slots__ = ("parent", "alphabet", "_seqid", "_parent_len", "_slice_record")
@@ -315,21 +309,16 @@ class SeqsDataABC(ABC):
 
 
 class SeqsData(SeqsDataABC):
-    """A collection of sequences underlying a SequenceCollection. The sequence
-    data is stored as numpy arrays, however the underlying data can be accessed
-    as strings, bytes, or numpy arrays.
+    """The builtin ``cogent3`` implementation of a collection of sequences underlying
+    a ``SequenceCollection``. The sequence data is stored as numpy arrays. Indexing
+    this object (using an int or seq name) returns a ``SeqDataView``, which can realise
+    the corresponding slice as a string, bytes, or numpy array via the alphabet.
 
-    Attributes
-    ----------
-    data
-        a dictionary of {name: sequence} pairs
-    alphabet
-        an instance of CharAlphabet valid for the sequences
-    offset
-        a dictionary of {name: offset} pairs indicating the offset of the sequence
-    check
-        a boolean indicating if the data should be checked for naming consistency
-        between arguments
+    Notes
+    -----
+    Methods on this object only accepts plust strand start, stop and step
+    indices for selecting segments of data. It can return the gap coordinates
+    for a sequence as used by IndelMap.
     """
 
     __slots__ = ("_data", "_alphabet", "_offset")
@@ -342,6 +331,24 @@ class SeqsData(SeqsDataABC):
         offset: dict[str, int] = None,
         check: bool = True,
     ):
+        """
+        Parameters
+        ----------
+        data
+            raw data as {seq name: sequence, ...} where the sequence can be converted
+            to a numpy array using the provided alphabet.
+        alphabet
+            a cogent3 CharAlphabet instance, typically defined as
+            <moltype>.most_degen_alphabet()
+        offset
+            dict indicating annotation offsets for each sequence
+        check
+            use the alphabet to check the sequences are valid
+
+        Raises
+        ------
+        new_alphabet.AlphabetError if the check fails
+        """
         self._alphabet = alphabet
         self._offset = offset or {}
         if check:
@@ -543,7 +550,12 @@ class SeqsData(SeqsDataABC):
 
 
 class SequenceCollection:
-    """A container of unaligned sequences"""
+    """A container of unaligned sequences.
+
+    Notes
+    -----
+    Should be constructed using ``make_unaligned_seqs()``.
+    """
 
     def __init__(
         self,
@@ -556,8 +568,7 @@ class SequenceCollection:
         name_map: OptDict = None,
         is_reversed: bool = False,
     ):
-        """Initialises a new SequenceCollection.
-
+        """
         Parameters
         ----------
         seqs_data
@@ -2684,7 +2695,15 @@ def compose_gapped_seq(
 
 
 class Aligned:
-    """A single sequence in an alignment."""
+    """A single sequence in an alignment.
+
+    Notes
+    -----
+    This is a wrapper around a ``AlignedDataView``. This class performs any
+    complenting needed. It can be cast directly to a string or numpy array,
+    e.g. ``numpy.array(<aligned instance>)`` returns a numpy unsigned 8-bit
+    integer array.
+    """
 
     __slots__ = ("_data", "_moltype", "_name", "_annotation_db")
 
@@ -2713,7 +2732,7 @@ class Aligned:
 
     @property
     def seq(self) -> new_sequence.Sequence:
-        """Returns Sequence object, excluding gaps."""
+        """the ungapped sequence."""
         # if the slice record has abs(step) > 1, we cannot retain a connection
         # to the underlying aligned seq data container because the gaps are
         # not going to be modulo the step.
@@ -2774,6 +2793,12 @@ class Aligned:
         # todo should indicate whether tidy or not
         return annot.remapped_to(alignment, inverted)
 
+    def __repr__(self) -> str:
+        seq = f"{str(self)[:7]}... {len(self):,}" if len(self) > 10 else str(self)
+        return (
+            f"Aligned(name={self.name!r}, seq={seq!r}, moltype={self.moltype.name!r})"
+        )
+
     def __str__(self) -> str:
         return str(self.gapped_seq)
 
@@ -2874,11 +2899,6 @@ class Aligned:
             allow_multiple=allow_multiple,
         )
 
-    def __repr__(self) -> str:
-        # refactor: design
-        # avoid using map in the repr
-        return f"Aligned(map={self.data.map}, data={self.seq})"
-
 
 class AlignedSeqsDataABC(SeqsDataABC):
     # all methods that are from SeqsDataABC should work in sequence coordinates,
@@ -3036,8 +3056,17 @@ def _gapped_seq_len(seq: numpy.ndarray, gap_map: numpy.ndarray) -> int:
 
 
 class AlignedSeqsData(AlignedSeqsDataABC):
-    # refactor: docstring
-    # refactor: design
+    """The builtin ``cogent3`` implementation of a container of aligned sequences
+    underlying an ``Alignment``. Indexing this object returns an ``AlignedDataView``
+    which can realise the corresponding slice as a string, bytes, or numpy array,
+    gapped or ungapped.
+
+    Notes
+    -----
+    Methods on this object only accepts plust strand start, stop and step
+    indices for selecting segments of data. It can return the gap coordinates
+    for a sequence as used by ``IndelMap``.
+    """
 
     __slots__ = (
         "_names",
@@ -3589,7 +3618,16 @@ class AlignedDataViewABC(new_sequence.SeqViewABC):
 
 
 class AlignedDataView(new_sequence.SeqViewABC):
-    # refactor: docstring
+    """
+    A view class for ``AlignedSeqsData``, providing methods for different representations
+    of a single sequence.
+
+    Notes
+    -----
+    ``str_value`` / ``array_value`` are not complemented, but can be reversed. The latter
+    is done by the ``Aligned`` object which has a moltype. The ``slice_record`` attribute
+    is shared with the containing ``Alignment``.
+    """
 
     __slots__ = (
         "parent",
@@ -3859,7 +3897,13 @@ class _IndexableSeqs:
 
 
 class Alignment(SequenceCollection):
-    # refactor: docstring
+    """A collection of aligned sequences.
+
+    Notes
+    -----
+    Should be constructed using ``make_aligned_seqs()``.
+    """
+
     def __init__(
         self,
         seqs_data: AlignedSeqsDataABC,  # seqs_data
diff --git a/src/cogent3/core/new_alphabet.py b/src/cogent3/core/new_alphabet.py
index a29b19f8d..f8963d294 100644
--- a/src/cogent3/core/new_alphabet.py
+++ b/src/cogent3/core/new_alphabet.py
@@ -231,12 +231,30 @@ class array_to_bytes:
 
 
 class CharAlphabet(tuple, AlphabetABC, MonomerAlphabetABC):
+    """representing fundamental monomer character sets.
+
+    Notes
+    -----
+    Provides methods for efficient conversion between characters and integers
+    from fundamental types of strings, bytes and numpy arrays.
+    """
+
     def __new__(
         cls,
         chars: typing.Sequence[StrORBytes],
         gap: OptStr = None,
         missing: OptStr = None,
     ):
+        """
+        Parameters
+        ----------
+        chars
+            the characters in the alphabet
+        gap
+            character representing the gap character (universally '-' in cogent3)
+        missing
+            character representing the missing data, typically '?'.
+        """
         if not chars:
             raise ValueError(f"cannot create empty {cls.__name__!r}")
 
@@ -594,6 +612,14 @@ class KmerAlphabetABC(ABC):
 
 
 class KmerAlphabet(tuple, AlphabetABC, KmerAlphabetABC):
+    """k-mer alphabet represents complete non-monomer alphabets
+
+    Notes
+    -----
+    Differs from SenseCodonAlphabet case by representing all possible permutations of
+    k-length of the provided monomer alphabet. More efficient mapping between
+    """
+
     def __new__(
         cls,
         words: tuple[StrORBytes, ...],
@@ -602,6 +628,20 @@ class KmerAlphabet(tuple, AlphabetABC, KmerAlphabetABC):
         gap: OptStr = None,
         missing: OptStr = None,
     ):
+        """
+        Parameters
+        ----------
+        words
+            len(monomers)**k k-length strings
+        monomers
+            the underlying character alphabet
+        k
+            the number of monomers per word
+        gap
+            k monomer gap characters
+        missing, optional
+            k monomer missing characters
+        """
         if not words:
             raise ValueError(f"cannot create empty {cls.__name__!r}")
 
diff --git a/src/cogent3/core/new_moltype.py b/src/cogent3/core/new_moltype.py
index a16e85887..bff1cf40b 100644
--- a/src/cogent3/core/new_moltype.py
+++ b/src/cogent3/core/new_moltype.py
@@ -371,6 +371,16 @@ def _strictly_upper(monomers: tuple[StrORBytes]):
 
 @dataclasses.dataclass
 class MolType:
+    """MolType handles operations that depend on the sequence type.
+
+    Notes
+    -----
+    The only way to create sequences is via a MolType instance.
+    The instance defines different alphabets that are used for data
+    conversions.
+    Create a moltype using the ``get_moltype()`` function.
+    """
+
     name: str
     monomers: dataclasses.InitVar[StrORBytes]
     make_seq: dataclasses.InitVar[typing.Type]
diff --git a/src/cogent3/core/new_sequence.py b/src/cogent3/core/new_sequence.py
index 85bcc20be..b859978f9 100644
--- a/src/cogent3/core/new_sequence.py
+++ b/src/cogent3/core/new_sequence.py
@@ -2489,6 +2489,14 @@ class SliceRecordABC(ABC):
 
 
 class SliceRecord(SliceRecordABC):
+    """records cumulative slice operations on an object without modifying it
+
+    Notes
+    -----
+    Basis for lazy evaluation of slicing operations on sequences and alignments.
+    A reference to an instance of this class is used by different view objects.
+    """
+
     __slots__ = "_parent_len"
 
     def __init__(
@@ -2500,6 +2508,21 @@ class SliceRecord(SliceRecordABC):
         step: OptInt = None,
         offset: int = 0,
     ):
+        """
+        Parameters
+        ----------
+        start
+            start of the slice (inclusive indexing)
+        stop
+            stop of the slice (exclusive indexing)
+        step
+            step of the slice
+        offset
+            can be set with any additional offset that exists before the start of
+            the underlying data
+        parent_len
+            length of the underlying data (not including offset)
+        """
         if step == 0:
             raise ValueError("step cannot be 0")
         step = step if step is not None else 1
@@ -2633,8 +2656,8 @@ class SeqView(SeqViewABC):
     """
     Provides a view of a sequence with support for slicing operations.
 
-    This class represents a view of a sequence, allowing for efficient slicing
-    without altering the original sequence data.
+    This class represents a view of a sequence. It uses ``SliceRecord`` to
+    enable efficient slicing without altering the original sequence data.
 
     Parameters
     ----------
@@ -2647,11 +2670,12 @@ class SeqView(SeqViewABC):
     parent_len
         the length of the sequence. Defaults to the length of the input sequence
 
+    Notes
+    -----
+    It utilises the alphabet object to allow providing different types
+    such as strings or numpy arrays, corresponding to its underlying data.
     """
 
-    # todo: kath,
-    # update the docstring to reflect the new design
-
     __slots__ = (
         "parent",
         "alphabet",


Test patch:
diff --git a/tests/test_core/test_new_alignment.py b/tests/test_core/test_new_alignment.py
index 77da9ef34..e8bd69342 100644
--- a/tests/test_core/test_new_alignment.py
+++ b/tests/test_core/test_new_alignment.py
@@ -4828,8 +4828,20 @@ def test_alignment_indexing_seqs_repr(names_seqs):
     raw = dict(zip(names, seqs))
     obj = new_alignment.make_aligned_seqs(raw, moltype="dna")
     got = repr(obj.seqs)
-    class_name = obj.seqs[0].__class__.__name__
-    expect = f"({class_name}(map=[]/6, data={seqs[0]}), + {len(names)-1} seqs)"
+    class_name = "Aligned"
+    expect = f"({class_name}(name={names[0]!r}, seq={seqs[0]!r}, moltype={obj.moltype.name!r}), + {len(names)-1} seqs)"
+    assert got == expect
+
+
+def test_aligned_repr():
+    seqs = {
+        "s1": "G-TG---TAGTAGAAGTTCCAAATAATGAA",
+        "s2": "GTG------GTAGAAGTTCCAAATAATGAA",
+        "s3": "GC--AAGTAGTGGAAGTTGCAAAT---GAA",
+    }
+    aln = new_alignment.make_aligned_seqs(seqs, moltype="dna")
+    got = repr(aln.seqs["s1"])
+    expect = f"Aligned(name='s1', seq='G-TG---... {len(seqs['s1'])}', moltype='dna')"
     assert got == expect