allpy
view allpy/base.py @ 1106:2b3cad50c2b1
Partially reversed [afed1f] (see #49)
As explained in the ticket, in real life usecases having a monomer belong to
several sequences is sometimes extremely useful. ANY approach to attribution of
monomer to only one sequence will be either confusing or hindering.
* Removed `monomer.sequence` attribute
* Removed unncecessary specialcasing in pickle
* Removed unused tests
* Restored APIs to backward-compatible
* Added deprecated messages to the restored APIs
| author | Daniil Alexeyevsky <dendik@kodomo.fbb.msu.ru> |
|---|---|
| date | Sun, 10 Jun 2012 16:08:47 +0400 |
| parents | 41a167bbf150 |
| children | 79978caa35ee |
line source
8 # import this very module as means of having all related classes in one place
12 """Set of characters to recoginze as gaps when parsing alignment."""
15 """Monomer object."""
18 """Either of 'dna', 'rna', 'protein'."""
21 """Mapping of related types. SHOULD be redefined in subclasses."""
24 """A mapping from 1-letter code to Monomer subclass."""
27 """A mapping from 3-letter code to Monomer subclass."""
30 """A mapping from full monomer name to Monomer subclass."""
32 @classmethod
34 """Create new subclass of Monomer for given monomer type."""
36 pass
47 # Save the class in data.monomers so that it can be pickled
48 # Some names are not unique, we append underscores to them
49 # in order to fix it.
58 # We duplicate distinguished long names into Monomer itself, so that we
59 # can use Monomer.from_code3 to create the relevant type of monomer.
64 @classmethod
66 """Create all relevant subclasses of Monomer."""
70 @classmethod
72 """Create new monomer from 1-letter code."""
74 "Monomer.from_code1(...) is deprecated in favor of Sequence.append_monomer(code1=...)"
75 )
80 @classmethod
82 """Create new monomer from 3-letter code."""
84 "Monomer.from_code3(...) is deprecated in favor of Sequence.append_monomer(code3=...)"
85 )
88 @classmethod
90 """Create new monomer from full name."""
92 "Monomer.from_name(...) is deprecated in favor of Sequence.append_monomer(name=...)"
93 )
100 """Returns one-letter code"""
104 """Monomers within same monomer type are compared by code1."""
114 """Common functions for alignment and sequence for dealing with markups.
115 """
118 """Hook to be called from __init__ of actual class."""
122 """Create a markup object, add to self. Return the created markup.
124 - `name` is name for markup in `self.markups` dictionary
125 - optional `markup_class` is class for created markup
126 - if optional `use_existing` is true, it is no error, if same named
127 markup already exists (in this case, nothing is changed)
128 - optional keyword arguments are passed on to the markup constructor
130 For user markups you have to specify `name` and `markup_class`,
131 for the standard automatical markups just `name` is enough.
132 """
133 # We have to import markups here, and not in the module header
134 # so as not to create bad import loops.
135 # `base` module is used extensively in `markups` for inherinance,
136 # so breaking the loop here seems a lot easier.
150 """Remove markup."""
155 """Sequence of Monomers.
157 This behaves like list of monomer objects. In addition to standard list
158 behaviour, Sequence has the following attributes:
160 * name -- str with the name of the sequence
161 * description -- str with description of the sequence
162 * source -- str denoting source of the sequence
164 Any of them may be empty (i.e. hold empty string)
165 """
168 """Mapping of related types. SHOULD be redefined in subclasses."""
171 """Description of object kind."""
174 """Squence identifier."""
177 """Detailed sequence description."""
180 """Sequence source."""
191 """Append a new monomer to the sequence. Return the new monomer."""
193 "Please specify exactly one of: code1, code3, name"
205 @classmethod
207 """Create sequence from a list of monomer objecst."""
209 "Sequence.from_monomers(...) is deprecated in favor of Sequence(...)"
210 )
213 @classmethod
215 """Create sequences from string of one-letter codes."""
228 """Returns sequence of one-letter codes."""
232 """Hash sequence by identity."""
236 """Alignment. It is a list of Columns."""
239 """Mapping of related types. SHOULD be redefined in subclasses."""
242 """Ordered list of sequences in alignment. Read, but DO NOT FIDDLE!"""
245 """Description of object kind."""
248 """Initialize empty alignment."""
253 # Alignment grow & IO methods
254 # ==============================
257 """Add sequence to alignment. Return self.
259 If sequence is too short, pad it with gaps on the right.
260 """
269 """Add row from a string of one-letter codes and gaps. Return self."""
277 ]
284 """Add row from row_as_list representation and sequence. Return self."""
293 """Insert list of `columns` after position `n`."""
297 """Pad alignment with empty columns on the right to width n."""
302 """Append sequences from file to alignment. Return self.
304 If sequences in file have gaps (detected as characters belonging to
305 `gaps` set), treat them accordingly.
306 """
311 """Write alignment in FASTA file as sequences with gaps."""
315 # Data access methods for alignment
316 # =================================
319 """Return list of rows (temporary objects) in alignment.
321 Each row is a dictionary of { column : monomer }.
323 For gap positions there is no key for the column in row.
325 Each row has attribute `sequence` pointing to the sequence the row is
326 describing.
328 Modifications of row have no effect on the alignment.
329 """
330 # For now, the function returns a list rather than iterator.
331 # It is yet to see, whether memory performance here becomes critical,
332 # or is random access useful.
344 """Return list of rows (temporary objects) in alignment.
346 Each row here is a list of either monomer or None (for gaps).
348 Each row has attribute `sequence` pointing to the sequence of row.
350 Modifications of row have no effect on the alignment.
351 """
362 """Return list of string representation of rows in alignment.
364 Each row has attribute `sequence` pointing to the sequence of row.
366 `gap` is the symbol to use for gap.
367 """
382 """Return representaion of row as list with `Monomers` and `None`s."""
386 """Return string representaion of row in alignment.
388 String will have gaps represented by `gap` symbol (defaults to '-').
389 """
398 """Return list of columns (temorary objects) in alignment.
400 Each column here is a list of either monomer or None (for gaps).
402 Items of column are sorted in the same way as alignment.sequences.
404 Modifications of column have no effect on the alignment.
405 """
415 # Alignment / Block editing methods
416 # =================================
419 """Remove all gaps from alignment and flush results to one side.
421 `whence` must be one of 'left', 'right' or 'center'
422 """
424 "aln.flush('left') is deprecated in favor of aln.realign(Left())"
425 )
437 """Remove all empty columns."""
443 """Turn all row positions into gaps (but keep sequences intact)."""
449 """Replace column contents with those of `new` alignment.
451 In other words: copy gap patterns from `new` to `self`.
453 `self.sequences` and `new.sequences` should have the same contents.
454 """
464 ]
470 """Realign self.
472 * apply function to self to produce a new alignment,
473 * update self to have the same gap patterns as the new alignment.
474 """
479 """Column of alignment.
481 Column is a dict of { sequence : monomer }.
483 For sequences that have gaps in current row, given key is not present in
484 the column.
485 """
488 """Mapping of related types. SHOULD be redefined in subclasses."""
491 """Return hash by identity."""
496 """Block of alignment.
498 Block is an intersection of several rows & columns. (The collections of
499 rows and columns are represented as ordered lists, to retain display order
500 of Alignment or add ability to tweak it). Most of blocks look like
501 rectangular part of alignment if you shuffle alignment rows the right way.
502 """
505 """Alignment the block belongs to."""
508 """List of sequences in block."""
511 """List of columns in block."""
513 @classmethod
515 """Build new block from alignment.
517 If sequences are not given, the block uses all sequences in alignment.
519 If columns are not given, the block uses all columns in alignment.
521 In both cases we use exactly the list used in alignment, thus, if new
522 sequences or columns are added to alignment, the block tracks this too.
523 """
535 """Insert list of `columns` after position `n`."""
546 """Base class for sequence and alignment markups.
548 We shall call either sequence or alignment a container. And we shall call
549 either monomers or columns elements respectively.
551 Markup behaves like a dictionary of [element] -> value.
553 Every container has a dictionary of [name] -> markup. It is Markup's
554 responsibility to add itself to this dictionary and to avoid collisions
555 while doing it.
556 """
559 """Name of markup elements."""
562 """If set to false, fileio should not save this markup."""
565 """Markup takes mandatory container and name and optional kwargs.
567 Markups should never be created by the user. They are created by
568 Sequence or Alignment.
569 """
575 """Recalculate markup values (if they are generated automatically)."""
576 pass
579 """Remove the traces of markup object. Do not call this yourself!"""
580 pass
582 @classmethod
584 """Restore markup from `record`. (Used for loading from file).
586 `record` is a dict of all metadata and data related to one markup. All
587 keys and values in `record` are strings, markup must parse them itself.
589 Markup values should be stored in `record['markup']`, which is a list
590 of items separated with either `record['separator']` or a comma.
591 """
595 """Save markup to `record`, for saving to file.
597 For description of `record` see docstring for `from_record` method.
599 If `keys` argument is given, restrict output to the given keys.
600 """
604 """Return list of elements in the container in proper order."""
608 """Return list of markup values in container.
610 Possible arguments:
612 - `map` -- a function, applied to each existing value
613 - `default` -- a value to return for non-existing values
615 If `default` is not specified, the function fails on markups that do
616 not have all of the values set.
617 """
628 """Markup for sequence.
630 Behaves like a dictionary of [monomer] -> value. Value may be anything
631 or something specific, depending on subclass.
633 Actual values are stored in monomers themselves as attributes.
634 """
643 """Remove the traces of markup object. Do not call this yourself!"""
648 """Return list of monomers."""
652 """Part of Mapping collection interface."""
658 """Part of Mapping collection interface."""
662 """Part of Mapping collection interface."""
666 """Part of Mapping collection interface."""
670 """Part of Mapping collection interface."""
674 """Markupf for alignment.
676 Is a dictionary of [column] -> value. Value may be anything or something
677 specific, depending on subclass.
678 """
687 """Return a list of columns."""
690 # vim: set ts=4 sts=4 sw=4 et: