# ---------------------------------------------------------------------------- # Copyright (c) 2013--, scikit-bio development team. # # Distributed under the terms of the Modified BSD License. # # The full license is in the file COPYING.txt, distributed with this software. # ---------------------------------------------------------------------------- import abc import copy import pandas as pd from skbio.util._decorator import stable, experimental from skbio.metadata import IntervalMetadata class MetadataMixin(metaclass=abc.ABCMeta): @property @stable(as_of="0.4.0") def metadata(self): """``dict`` containing metadata which applies to the entire object. Notes ----- This property can be set and deleted. When setting new metadata a shallow copy of the dictionary is made. Examples -------- .. note:: scikit-bio objects with metadata share a common interface for accessing and manipulating their metadata. The following examples use scikit-bio's ``Sequence`` class to demonstrate metadata behavior. These examples apply to all other scikit-bio objects storing metadata. Create a sequence with metadata: >>> from pprint import pprint >>> from skbio import Sequence >>> seq = Sequence('ACGT', metadata={'description': 'seq description', ... 'id': 'seq-id'}) Retrieve metadata: >>> pprint(seq.metadata) # using pprint to display dict in sorted order {'description': 'seq description', 'id': 'seq-id'} Update metadata: >>> seq.metadata['id'] = 'new-id' >>> seq.metadata['pubmed'] = 12345 >>> pprint(seq.metadata) {'description': 'seq description', 'id': 'new-id', 'pubmed': 12345} Set metadata: >>> seq.metadata = {'abc': 123} >>> seq.metadata {'abc': 123} Delete metadata: >>> seq.has_metadata() True >>> del seq.metadata >>> seq.metadata {} >>> seq.has_metadata() False """ if self._metadata is None: # Not using setter to avoid copy. self._metadata = {} return self._metadata @metadata.setter def metadata(self, metadata): if not isinstance(metadata, dict): raise TypeError("metadata must be a dict, not type %r" % type(metadata).__name__) # Shallow copy. self._metadata = metadata.copy() @metadata.deleter def metadata(self): self._metadata = None @abc.abstractmethod def __init__(self, metadata=None): raise NotImplementedError def _init_(self, metadata=None): if metadata is None: # Could use deleter but this is less overhead and needs to be fast. self._metadata = None else: # Use setter for validation and copy. self.metadata = metadata @abc.abstractmethod def __eq__(self, other): raise NotImplementedError def _eq_(self, other): # We're not simply comparing self.metadata to other.metadata in order # to avoid creating "empty" metadata representations on the objects if # they don't have metadata. if self.has_metadata() and other.has_metadata(): return self.metadata == other.metadata elif not (self.has_metadata() or other.has_metadata()): # Both don't have metadata. return True else: # One has metadata while the other does not. return False @abc.abstractmethod def __ne__(self, other): raise NotImplementedError def _ne_(self, other): return not (self == other) @abc.abstractmethod def __copy__(self): raise NotImplementedError def _copy_(self): if self.has_metadata(): return self.metadata.copy() else: return None @abc.abstractmethod def __deepcopy__(self, memo): raise NotImplementedError def _deepcopy_(self, memo): if self.has_metadata(): return copy.deepcopy(self.metadata, memo) else: return None @stable(as_of="0.4.0") def has_metadata(self): """Determine if the object has metadata. An object has metadata if its ``metadata`` dictionary is not empty (i.e., has at least one key-value pair). Returns ------- bool Indicates whether the object has metadata. Examples -------- .. note:: scikit-bio objects with metadata share a common interface for accessing and manipulating their metadata. The following examples use scikit-bio's ``Sequence`` class to demonstrate metadata behavior. These examples apply to all other scikit-bio objects storing metadata. >>> from skbio import Sequence >>> seq = Sequence('ACGT') >>> seq.has_metadata() False >>> seq = Sequence('ACGT', metadata={}) >>> seq.has_metadata() False >>> seq = Sequence('ACGT', metadata={'id': 'seq-id'}) >>> seq.has_metadata() True """ return self._metadata is not None and bool(self.metadata) class PositionalMetadataMixin(metaclass=abc.ABCMeta): @abc.abstractmethod def _positional_metadata_axis_len_(self): """Return length of axis that positional metadata applies to. Returns ------- int Positional metadata axis length. """ raise NotImplementedError @property @stable(as_of="0.4.0") def positional_metadata(self): """``pd.DataFrame`` containing metadata along an axis. Notes ----- This property can be set and deleted. When setting new positional metadata, a shallow copy is made and the ``pd.DataFrame`` index is set to ``pd.RangeIndex(start=0, stop=axis_len, step=1)``. Examples -------- .. note:: scikit-bio objects with positional metadata share a common interface for accessing and manipulating their positional metadata. The following examples use scikit-bio's ``DNA`` class to demonstrate positional metadata behavior. These examples apply to all other scikit-bio objects storing positional metadata. Create a DNA sequence with positional metadata: >>> from skbio import DNA >>> seq = DNA( ... 'ACGT', ... positional_metadata={'exons': [True, True, False, True], ... 'quality': [3, 3, 20, 11]}) >>> seq DNA ----------------------------- Positional metadata: 'exons': 'quality': Stats: length: 4 has gaps: False has degenerates: False has definites: True GC-content: 50.00% ----------------------------- 0 ACGT Retrieve positional metadata: >>> seq.positional_metadata exons quality 0 True 3 1 True 3 2 False 20 3 True 11 Update positional metadata: >>> seq.positional_metadata['gaps'] = seq.gaps() >>> seq.positional_metadata exons quality gaps 0 True 3 False 1 True 3 False 2 False 20 False 3 True 11 False Set positional metadata: >>> seq.positional_metadata = {'degenerates': seq.degenerates()} >>> seq.positional_metadata # doctest: +NORMALIZE_WHITESPACE degenerates 0 False 1 False 2 False 3 False Delete positional metadata: >>> seq.has_positional_metadata() True >>> del seq.positional_metadata >>> seq.positional_metadata Empty DataFrame Columns: [] Index: [0, 1, 2, 3] >>> seq.has_positional_metadata() False """ if self._positional_metadata is None: # Not using setter to avoid copy. self._positional_metadata = pd.DataFrame( index=self._get_positional_metadata_index()) return self._positional_metadata @positional_metadata.setter def positional_metadata(self, positional_metadata): try: # Pass copy=True to copy underlying data buffer. positional_metadata = pd.DataFrame(positional_metadata, copy=True) # Different versions of pandas will raise different error types. We # don't really care what the type of the error is, just its message, so # a blanket Exception will do. except Exception as e: raise TypeError( "Invalid positional metadata. Must be consumable by " "`pd.DataFrame` constructor. Original pandas error message: " "\"%s\"" % e) num_rows = len(positional_metadata.index) axis_len = self._positional_metadata_axis_len_() if num_rows != axis_len: raise ValueError( "Number of positional metadata values (%d) must match the " "positional metadata axis length (%d)." % (num_rows, axis_len)) positional_metadata.index = self._get_positional_metadata_index() self._positional_metadata = positional_metadata @positional_metadata.deleter def positional_metadata(self): self._positional_metadata = None def _get_positional_metadata_index(self): """Create a memory-efficient integer index for positional metadata.""" return pd.RangeIndex(start=0, stop=self._positional_metadata_axis_len_(), step=1) @abc.abstractmethod def __init__(self, positional_metadata=None): raise NotImplementedError def _init_(self, positional_metadata=None): if positional_metadata is None: # Could use deleter but this is less overhead and needs to be fast. self._positional_metadata = None else: # Use setter for validation and copy. self.positional_metadata = positional_metadata @abc.abstractmethod def __eq__(self, other): raise NotImplementedError def _eq_(self, other): # We're not simply comparing self.positional_metadata to # other.positional_metadata in order to avoid creating "empty" # positional metadata representations on the objects if they don't have # positional metadata. if self.has_positional_metadata() and other.has_positional_metadata(): return self.positional_metadata.equals(other.positional_metadata) elif not (self.has_positional_metadata() or other.has_positional_metadata()): # Both don't have positional metadata. return (self._positional_metadata_axis_len_() == other._positional_metadata_axis_len_()) else: # One has positional metadata while the other does not. return False @abc.abstractmethod def __ne__(self, other): raise NotImplementedError def _ne_(self, other): return not (self == other) @abc.abstractmethod def __copy__(self): raise NotImplementedError def _copy_(self): if self.has_positional_metadata(): # deep=True makes a shallow copy of the underlying data buffer. return self.positional_metadata.copy(deep=True) else: return None @abc.abstractmethod def __deepcopy__(self, memo): raise NotImplementedError def _deepcopy_(self, memo): if self.has_positional_metadata(): # `copy.deepcopy` no longer recursively copies contents of the # DataFrame, so we must handle the deep copy ourselves. # Reference: https://github.com/pandas-dev/pandas/issues/17406 df = self.positional_metadata data_cp = copy.deepcopy(df.values.tolist(), memo) return pd.DataFrame(data_cp, index=df.index.copy(deep=True), columns=df.columns.copy(deep=True), copy=False) else: return None @stable(as_of="0.4.0") def has_positional_metadata(self): """Determine if the object has positional metadata. An object has positional metadata if its ``positional_metadata`` ``pd.DataFrame`` has at least one column. Returns ------- bool Indicates whether the object has positional metadata. Examples -------- .. note:: scikit-bio objects with positional metadata share a common interface for accessing and manipulating their positional metadata. The following examples use scikit-bio's ``DNA`` class to demonstrate positional metadata behavior. These examples apply to all other scikit-bio objects storing positional metadata. >>> import pandas as pd >>> from skbio import DNA >>> seq = DNA('ACGT') >>> seq.has_positional_metadata() False >>> seq = DNA('ACGT', positional_metadata=pd.DataFrame(index=range(4))) >>> seq.has_positional_metadata() False >>> seq = DNA('ACGT', positional_metadata={'quality': range(4)}) >>> seq.has_positional_metadata() True """ return (self._positional_metadata is not None and len(self.positional_metadata.columns) > 0) class IntervalMetadataMixin(metaclass=abc.ABCMeta): @abc.abstractmethod def _interval_metadata_axis_len_(self): '''Return length of axis that interval metadata applies to. Returns ------- int Interval metadata axis length. ''' raise NotImplementedError @abc.abstractmethod def __init__(self, interval_metadata=None): raise NotImplementedError def _init_(self, interval_metadata=None): if interval_metadata is None: # Could use deleter but this is less overhead and needs to be fast. self._interval_metadata = None else: # Use setter for validation and copy. self.interval_metadata = interval_metadata @property @experimental(as_of="0.5.1") def interval_metadata(self): '''``IntervalMetadata`` object containing info about interval features. Notes ----- This property can be set and deleted. When setting new interval metadata, a shallow copy of the ``IntervalMetadata`` object is made. ''' if self._interval_metadata is None: # Not using setter to avoid copy. self._interval_metadata = IntervalMetadata( self._interval_metadata_axis_len_()) return self._interval_metadata @interval_metadata.setter def interval_metadata(self, interval_metadata): if isinstance(interval_metadata, IntervalMetadata): upper_bound = interval_metadata.upper_bound lower_bound = interval_metadata.lower_bound axis_len = self._interval_metadata_axis_len_() if lower_bound != 0: raise ValueError( 'The lower bound for the interval features (%d) ' 'must be zero.' % lower_bound) if upper_bound is not None and upper_bound != axis_len: raise ValueError( 'The upper bound for the interval features (%d) ' 'must match the interval metadata axis length (%d)' % (upper_bound, axis_len)) # copy all the data to the mixin self._interval_metadata = IntervalMetadata( axis_len, copy_from=interval_metadata) else: raise TypeError('You must provide `IntervalMetadata` object, ' 'not type %s.' % type(interval_metadata).__name__) @interval_metadata.deleter def interval_metadata(self): self._interval_metadata = None @experimental(as_of="0.5.1") def has_interval_metadata(self): """Determine if the object has interval metadata. An object has interval metadata if its ``interval_metadata`` has at least one ```Interval`` objects. Returns ------- bool Indicates whether the object has interval metadata. """ return (self._interval_metadata is not None and self.interval_metadata.num_interval_features > 0) @abc.abstractmethod def __eq__(self, other): raise NotImplementedError def _eq_(self, other): # We're not simply comparing self.interval_metadata to # other.interval_metadata in order to avoid creating "empty" # interval metadata representations on the objects if they don't have # interval metadata. if self.has_interval_metadata() and other.has_interval_metadata(): return self.interval_metadata == other.interval_metadata elif not (self.has_interval_metadata() or other.has_interval_metadata()): # Both don't have interval metadata. return (self._interval_metadata_axis_len_() == other._interval_metadata_axis_len_()) else: # One has interval metadata while the other does not. return False @abc.abstractmethod def __ne__(self, other): raise NotImplementedError def _ne_(self, other): return not (self == other) @abc.abstractmethod def __copy__(self): raise NotImplementedError def _copy_(self): if self.has_interval_metadata(): return copy.copy(self.interval_metadata) else: return None @abc.abstractmethod def __deepcopy__(self, memo): raise NotImplementedError def _deepcopy_(self, memo): if self.has_interval_metadata(): return copy.deepcopy(self.interval_metadata, memo) else: return None