def test_clear(self): i = MemoryDescriptorSet() n = 10 descrs = [random_descriptor() for _ in range(n)] i.add_many_descriptors(descrs) self.assertEqual(len(i), n) i.clear() self.assertEqual(len(i), 0) self.assertEqual(i._table, {})
class IqrSession(SmqtkObject): """ Encapsulation of IQR Session related data structures with a centralized lock for multi-thread access. This object is compatible with the python with-statement, so when elements are to be used or modified, it should be within a with-block so race conditions do not occur across threads/sub-processes. """ @property def _log(self): return logging.getLogger('.'.join((self.__module__, self.__class__.__name__)) + "[%s]" % self.uuid) def __init__(self, pos_seed_neighbors=500, rel_index_config=None, session_uid=None): """ Initialize the IQR session This does not initialize the working set for ranking as there are no known positive descriptor examples at this time. Adjudications ------------- Adjudications are carried through between initializations. This allows indexed material adjudicated through-out the lifetime of the session to stay relevant. :param pos_seed_neighbors: Number of neighbors to pull from the given ``nn_index`` for each positive exemplar when populating the working set, i.e. this value determines the size of the working set for IQR refinement. By default, we try to get 500 neighbors. Since there may be partial to significant overlap of near neighbors as a result of nn_index queries for positive exemplars, the working set may contain anywhere from this value's number of entries, to ``N*P``, where ``N`` is this value and ``P`` is the number of positive examples at the time of working set initialization. :type pos_seed_neighbors: int :param rel_index_config: Plugin configuration dictionary for the RelevancyIndex to use for ranking user adjudications. If `None` we default to using an in-memory libSVM based index using the histogram intersection metric. :type rel_index_config: None | dict :param session_uid: Optional manual specification of session UUID. By default this will be a string UUID as generated by ``uuid.uuid1()``. :type session_uid: str | uuid.UUID """ self.uuid = session_uid or str(uuid.uuid1()).replace('-', '') self.lock = threading.RLock() self.pos_seed_neighbors = int(pos_seed_neighbors) # Local descriptor set for ranking, populated by a query to the # nn_index instance. # Added external data/descriptors not added to this set. self.working_set = MemoryDescriptorSet() # Book-keeping set so we know what positive descriptors # UUIDs we've used to query the neighbor index with already. #: :type: set[collections.Hashable] self._wi_seeds_used = set() # Descriptor elements representing data from external sources. # These may be arbitrary descriptor elements not present in # ``working_index``. #: :type: set[smqtk.representation.DescriptorElement] self.external_positive_descriptors = set() #: :type: set[smqtk.representation.DescriptorElement] self.external_negative_descriptors = set() # Descriptor references from ``working_set`` that have been # adjudicated. # These should be sub-sets of the descriptors contained in the # ``working_set``. #: :type: set[smqtk.representation.DescriptorElement] self.positive_descriptors = set() #: :type: set[smqtk.representation.DescriptorElement] self.negative_descriptors = set() # Sets of descriptor elements that were used in the last refinement # to achieve the currently cached results, i.e. "contributed" to the # current results state. # These sets are empty before the first refine after construction or a # reset. #: :type: set[smqtk.representation.DescriptorElement] self.rank_contrib_pos = set() #: :type: set[smqtk.representation.DescriptorElement] self.rank_contrib_pos_ext = set() #: :type: set[smqtk.representation.DescriptorElement] self.rank_contrib_neg = set() #: :type: set[smqtk.representation.DescriptorElement] self.rank_contrib_neg_ext = set() # Mapping of a DescriptorElement in our relevancy search index (not the # set that the nn_index uses) to the relevancy score given the # recorded positive and negative adjudications. # This is None before any initialization or refinement occurs. #: :type: None | dict[smqtk.representation.DescriptorElement, float] self.results = None # Cache variables for views of refinement results. # All results as a list in order of relevancy score. #: :type: None | list[(smqtk.representation.DescriptorElement, float)] self._ordered_results = None #: Positively adjudicated descriptors in order of relevancy score. #: :type: None | list[(smqtk.representation.DescriptorElement, float)] self._ordered_pos = None # Negatively adjudicated descriptors in order of relevancy score. #: :type: None | list[(smqtk.representation.DescriptorElement, float)] self._ordered_neg = None # Non-adjudicated descriptors in our working set in order of # relevancy score. #: :type: None | list[(smqtk.representation.DescriptorElement, float)] self._ordered_non_adj = None # # Algorithm Instances [+Config] # # RelevancyIndex configuration and instance that is used for producing # results. # This is only [re]constructed when initializing the session. if rel_index_config is None: rel_index_config = DFLT_REL_INDEX_CONFIG self.rel_index_config = rel_index_config # This is None until session initialization happens after pos/neg # exemplar data has been added. #: :type: None | smqtk.algorithms.relevancy_index.RelevancyIndex self.rel_index = None def __enter__(self): """ :rtype: IqrSession """ self.lock.acquire() return self # noinspection PyUnusedLocal def __exit__(self, exc_type, exc_val, exc_tb): self.lock.release() def external_descriptors(self, positive=(), negative=()): """ Add positive/negative descriptors from external data. These descriptors may not be a part of our working set. TODO: Add ability to "remove" positive/negative external descriptors. See ``adjudicate`` method "un_..." parameters. :param positive: Iterable of descriptors from external sources to consider positive examples. :type positive: collections.Iterable[smqtk.representation.DescriptorElement] :param negative: Iterable of descriptors from external sources to consider negative examples. :type negative: collections.Iterable[smqtk.representation.DescriptorElement] """ positive = set(positive) negative = set(negative) with self.lock: self.external_positive_descriptors.update(positive) self.external_positive_descriptors.difference_update(negative) self.external_negative_descriptors.update(negative) self.external_negative_descriptors.difference_update(positive) def adjudicate(self, new_positives=(), new_negatives=(), un_positives=(), un_negatives=()): """ Update current state of working set positive and negative adjudications based on descriptor UUIDs. If the same descriptor element is listed in both new positives and negatives, they cancel each other out, causing that descriptor to not be included in the adjudication. The given iterables must be re-traversable. Otherwise the given descriptors will not be properly registered. :param new_positives: Descriptors of elements in our working set to now be considered to be positively relevant. :type new_positives: collections.Iterable[smqtk.representation.DescriptorElement] :param new_negatives: Descriptors of elements in our working set to now be considered to be negatively relevant. :type new_negatives: collections.Iterable[smqtk.representation.DescriptorElement] :param un_positives: Descriptors of elements in our working set to now be considered not positive any more. :type un_positives: collections.Iterable[smqtk.representation.DescriptorElement] :param un_negatives: Descriptors of elements in our working set to now be considered not negative any more. :type un_negatives: collections.Iterable[smqtk.representation.DescriptorElement] """ # TODO: Assert that inputs are indeed in the working set? new_positives = set(new_positives) new_negatives = set(new_negatives) un_positives = set(un_positives) un_negatives = set(un_negatives) with self.lock: pos_before = set(self.positive_descriptors) self.positive_descriptors.update(new_positives) self.positive_descriptors.difference_update(un_positives) self.positive_descriptors.difference_update(new_negatives) pos_changed = pos_before != self.positive_descriptors if pos_changed: # Reset ordered positives cache if pos adjudications changed. self._ordered_pos = None neg_before = set(self.negative_descriptors) self.negative_descriptors.update(new_negatives) self.negative_descriptors.difference_update(un_negatives) self.negative_descriptors.difference_update(new_positives) neg_changed = neg_before != self.negative_descriptors if neg_changed: # Reset ordered negatives cache if neg adjudications changed. self._ordered_neg = None if pos_changed or neg_changed: # Reset non-adjudicated cache if anything changed. self._ordered_non_adj = None def update_working_set(self, nn_index): """ Initialize or update our current working set using the given :class:`.NearestNeighborsIndex` instance given our current positively labeled descriptor elements. We only query from the index for new positive elements since the last update or reset. :param nn_index: :class:`.NearestNeighborsIndex` to query from. :type nn_index: smqtk.algorithms.NearestNeighborsIndex :raises RuntimeError: There are no positive example descriptors in this session to use as a basis for querying. """ pos_examples = (self.external_positive_descriptors | self.positive_descriptors) if len(pos_examples) == 0: raise RuntimeError("No positive descriptors to query the neighbor " "index with.") # Not clearing working set because this step is intended to be # additive. updated = False # adding to working set self._log.info( "Building working set using %d positive examples " "(%d external, %d adjudicated)", len(pos_examples), len(self.external_positive_descriptors), len(self.positive_descriptors)) # TODO: parallel_map and reduce with merge-dict for p in pos_examples: if p.uuid() not in self._wi_seeds_used: self._log.debug("Querying neighbors to: %s", p) self.working_set.add_many_descriptors( nn_index.nn(p, n=self.pos_seed_neighbors)[0]) self._wi_seeds_used.add(p.uuid()) updated = True # Make new relevancy index if updated: self._log.info("Creating new relevancy index over working set.") #: :type: smqtk.algorithms.relevancy_index.RelevancyIndex self.rel_index = from_config_dict(self.rel_index_config, RelevancyIndex.get_impls()) self.rel_index.build_index(self.working_set.iterdescriptors()) def refine(self): """ Refine current model results based on current adjudication state :raises RuntimeError: No working set has been initialized. :meth:`update_working_set` should have been called after adjudicating some positive examples. :raises RuntimeError: There are no adjudications to run on. We must have at least one positive adjudication. """ with self.lock: if not self.rel_index: raise RuntimeError("No relevancy index yet. Must not have " "initialized session (no working set).") # combine pos/neg adjudications + added external data descriptors pos = self.positive_descriptors | self.external_positive_descriptors neg = self.negative_descriptors | self.external_negative_descriptors if not pos: raise RuntimeError("Did not find at least one positive " "adjudication.") self._log.debug( "Ranking working set with %d pos and %d neg total " "examples.", len(pos), len(neg)) element_probability_map = self.rel_index.rank(pos, neg) self.results = element_probability_map # Record UIDs of elements used for relevancy ranking. # - shallow copy for separate container instance self.rank_contrib_pos = set(self.positive_descriptors) self.rank_contrib_pos_ext = set(self.external_positive_descriptors) self.rank_contrib_neg = set(self.negative_descriptors) self.rank_contrib_neg_ext = set(self.external_negative_descriptors) # Clear result view caches self._ordered_results = self._ordered_pos = self._ordered_neg = \ self._ordered_non_adj = None def ordered_results(self): """ Return a tuple of all working-set descriptor elements as tuples of ``(element, score)`` in order of descending relevancy score. If refinement has not yet occurred since session creation or the last reset, an empty tuple is returned. :rtype: None | tuple[(smqtk.representation.DescriptorElement, float)] """ with self.lock: try: return list(self._ordered_results) except TypeError: # NoneType is not iterable # Cache did non exist. try: result_items = six.iteritems(self.results) except AttributeError: # NoneType missing items/iteritems attr # No results to iterate over. return list() r = self._ordered_results = sorted(result_items, key=lambda p: p[1], reverse=True) # Shallow copy of the list to protect against external mutation return list(r) def get_positive_adjudication_relevancy(self): """ Return a list of the positively adjudicated descriptors as tuples of ``(element, score)`` in order of descending relevancy score. This does *not* include external positive adjudications, only positively adjudicated descriptors in the working set. If refinement has not yet occurred since session creation or the last reset, an empty list is returned. Cache is invalidated when: - A refinement occurs. - Positive adjudications change. :rtype: None | list[(smqtk.representation.DescriptorElement, float)] """ with self.lock: try: return list(self._ordered_pos) except TypeError: # NoneType is not iterable # No cache yet. rank_contrib_pos = \ self.rank_contrib_pos | self.rank_contrib_pos_ext # Results already ordered, so only filter r = self._ordered_pos = list( filter(lambda t: t[0] in rank_contrib_pos, self.ordered_results())) # Shallow copy of the list to protect against external mutation return list(r) def get_negative_adjudication_relevancy(self): """ Return a list of the negatively adjudicated descriptors as tuples of ``(element, score)`` in order of descending relevancy score. This does *not* include external negative adjudications, only negatively adjudicated descriptors in the working set. If refinement has not yet occurred since session creation or the last reset, an empty list is returned. Cache is invalidated when: - A refinement occurs. - Negative adjudications change. :rtype: None | list[(smqtk.representation.DescriptorElement, float)] """ with self.lock: try: return list(self._ordered_neg) except TypeError: # NoneType is not iterable # No cache yet. rank_contrib_neg = \ self.rank_contrib_neg | self.rank_contrib_neg_ext # Results already ordered, so only filter r = self._ordered_neg = list( filter(lambda t: t[0] in rank_contrib_neg, self.ordered_results())) # Shallow copy of the list to protect against external mutation return list(r) def get_unadjudicated_relevancy(self): """ Return a list of the non-adjudicated descriptor elements as tuples of ``(element, score)`` in order of descending relevancy score. If refinement has not yet occurred since session creation or the last reset, an empty list is returned. :rtype: None | list[(smqtk.representation.DescriptorElement, float)] """ with self.lock: try: return list(self._ordered_non_adj) except TypeError: # NoneType is not iterable # No cache yet pos_and_neg = \ self.rank_contrib_pos | self.rank_contrib_pos_ext | \ self.rank_contrib_neg | self.rank_contrib_neg_ext # Results already ordered, so only filter r = self._ordered_non_adj = list( filter(lambda t: t[0] not in pos_and_neg, self.ordered_results())) # Shallow copy of the list to protect against external mutation return list(r) def reset(self): """ Reset the IQR Search state No positive adjudications, reload original feature data """ with self.lock: self.working_set.clear() self._wi_seeds_used.clear() self.positive_descriptors.clear() self.negative_descriptors.clear() self.external_positive_descriptors.clear() self.external_negative_descriptors.clear() self.rank_contrib_pos.clear() self.rank_contrib_pos_ext.clear() self.rank_contrib_neg.clear() self.rank_contrib_neg_ext.clear() self.rel_index = None self.results = None self._ordered_results = self._ordered_pos = self._ordered_neg = \ self._ordered_non_adj = None ########################################################################### # I/O Methods # I/O Constants. These should not be changed. STATE_ZIP_COMPRESSION = zipfile.ZIP_DEFLATED STATE_ZIP_FILENAME = "iqr_state.json" def get_state_bytes(self): """ Get a byte representation of the current descriptor and adjudication state of this session. This does not encode current results or the relevancy index's state, but these can be reproduced with this state. :return: State representation bytes :rtype: bytes """ def d_set_to_list(d_set): # Convert set of descriptors to list of tuples: # [..., (uuid, type, vector), ...] return [(d.uuid(), d.type(), d.vector().tolist()) for d in d_set] with self: # Convert session descriptors into basic values. pos_d = d_set_to_list(self.positive_descriptors) neg_d = d_set_to_list(self.negative_descriptors) ext_pos_d = d_set_to_list(self.external_positive_descriptors) ext_neg_d = d_set_to_list(self.external_negative_descriptors) z_buffer = io.BytesIO() z = zipfile.ZipFile(z_buffer, 'w', self.STATE_ZIP_COMPRESSION) z.writestr( self.STATE_ZIP_FILENAME, json.dumps({ 'pos': pos_d, 'neg': neg_d, 'external_pos': ext_pos_d, 'external_neg': ext_neg_d, })) z.close() return z_buffer.getvalue() def set_state_bytes(self, b, descriptor_factory): """ Set this session's state to the given byte representation, resetting this session in the process. Bytes given must have been retrieved via a previous call to ``get_state_bytes`` otherwise this method will fail. Since this state may be completely different from the current state, this session is reset before applying the new state. Thus, any current ranking results are thrown away. :param b: Bytes to set this session's state to. :type b: bytes :param descriptor_factory: Descriptor element factory to use when generating descriptor elements from extracted data. :type descriptor_factory: smqtk.representation.DescriptorElementFactory :raises ValueError: The input bytes could not be loaded due to incompatibility. """ z_buffer = io.BytesIO(b) z = zipfile.ZipFile(z_buffer, 'r', self.STATE_ZIP_COMPRESSION) if self.STATE_ZIP_FILENAME not in z.namelist(): raise ValueError("Invalid bytes given, did not contain expected " "zipped file name.") # Extract expected json file object state = json.loads(z.read(self.STATE_ZIP_FILENAME).decode()) del z, z_buffer with self: self.reset() def load_descriptor(_uid, _type_str, vec_list): _e = descriptor_factory.new_descriptor(_type_str, _uid) if _e.has_vector(): assert _e.vector().tolist() == vec_list, \ "Found existing vector for UUID '%s' but vectors did " \ "not match." else: _e.set_vector(vec_list) return _e # Read in raw descriptor data from the state, convert to descriptor # element, then store in our descriptor sets. for source, target in [ (state['external_pos'], self.external_positive_descriptors), (state['external_neg'], self.external_negative_descriptors), (state['pos'], self.positive_descriptors), (state['neg'], self.negative_descriptors) ]: for uid, type_str, vector_list in source: e = load_descriptor(uid, type_str, vector_list) target.add(e)