agglovar.merge.cumulative
=========================

.. py:module:: agglovar.merge.cumulative

.. autoapi-nested-parse::

   A merging strategy that adds callsets cumulatively to the merge.

   This strategy uses a table of variants that accumulates as callsets are added (the cumulative
   table). The cumulative table is initially empty. As callsets are added, variant intersecting the
   cumulative table are added to existing entries, and variants not intersecting the cumulative table
   are appended as new variants. This process is repeated for each callset added.

   After all callsets are procesesd, the cumulative table represents a nonredundant callset where
   each entry is one variant that was found in one or more of the original callsets. Columns
   tracking the sources and the variant within each source.

   This strategy is fast and uses minimal memory, but is not necessarily optimal. The order variants
   are input into the callset may alter the merged results in nontrivial ways, especially in loci
   where multiple join choices are possible.



Classes
-------

.. autoapisummary::

   agglovar.merge.cumulative.LeadStrategy
   agglovar.merge.cumulative.MergeCumulative


Module Contents
---------------

.. py:class:: LeadStrategy(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Strategy for choosing the lead variant.

   When variants from multiple sources join into one record, this strategy determines which
   variant is chosen as the lead variant. The lead variant represents the merged records in the
   merged callset.


   .. py:attribute:: FIRST
      :value: 'right'



   .. py:attribute:: LEFT
      :value: 'left'



.. py:class:: MergeCumulative(pairwise_join: agglovar.pairwise.base.PairwiseJoin, lead_strategy: LeadStrategy = LeadStrategy.LEFT)

   Bases: :py:obj:`agglovar.merge.base.MergeBase`


   Iterative intersection.

   :ivar join: Pairwise join strategy for intersects.


   .. py:method:: __call__(callsets: collections.abc.Iterable[agglovar.merge.base.CallsetDefType], retain_index: bool = False, pre_filter: Optional[collections.abc.Iterable[polars.Expr] | polars.Expr] = None, sort: bool = True, add_id: bool = True, temp_dir: bool | str | pathlib.Path = False) -> polars.LazyFrame

      Intersect callsets.

      :param callsets: Callsets to intersect.
      :param retain_index: If `True`, do not drop an existing "_index" column in callset tables
          if they exist.
      :param pre_filter: If set, filter each table with these expressions. Filter is applied
          last (after "_index" is set).
      :param temp_dir: Forwarded to the pairwise intersect for each cumulative step. See
          :meth:`agglovar.pairwise.base.PairwiseJoin.join_iter`.

      :return: A merged callset table.



   .. py:attribute:: join
      :type:  agglovar.pairwise.base.PairwiseJoin


   .. py:attribute:: lead_strategy


   .. py:attribute:: pairwise_join