# cluster

A cluster is an ordered set of hits related to a model which satisfy the model distance constraints.

## cluster API reference

## cluster

class `macsypy.cluster.``Cluster`(hits, model, hit_weights)

  Handle hits relative to a model which collocates

  `__contains__`(v_hit)
    Parameters

      v_hit (`macsypy.hit.ModelHit` object) – The hit to test

    Returns

      True if the hit is in the cluster hits, False otherwise

  `__init__`(hits, model, hit_weights)
    Parameters

      - hits ([ `macsypy.hit.CoreHit` | `macsypy.hit.ModelHit`, … ]) – the hits constituting this cluster

      - model (`macsypy.model.Model`) – the model associated to this cluster

  `__str__`()
    Returns

      a string representation of this cluster

  `__weakref__`

    list of weak references to the object (if defined)

  `_check_replicon_consistency`()
    Raise

      MacsypyError if all hits of a cluster are NOT related to the same replicon

  `fulfilled_function`(*genes)
    Parameters

      gene – The genes which must be tested.

    Returns

      the common functions between genes and this cluster.

    Return type

      set of string

  property `hit_weights`
    Returns

      the different weight for the hits used to compute the score

    Return type

      `macsypy.hit.HitWeight`

  property `loner`
    Returns

      True if this cluster is made of only one hit representing a loner gene False otherwise: - contains several hits - contains one hit but gene is not tag as loner (max_gene_required = 1)

  `merge`(cluster, before=False)

    merge the cluster in this one. (do it in place)

    Parameters

      - cluster (`macsypy.cluster.Cluster` object) –

      - before (bool) – If False the hits of the cluster will be add at the end of this one, Otherwise the cluster hits will be inserted before the hits of this one.

    Returns

      None

    Raises

      MacsypyError – if the two clusters have not the same model

  property `multi_system`
    Returns

      True if this cluster is made of only one hit representing a multi_system gene False otherwise: - contains several hits - contains one hit but gene is not tag as loner (max_gene_required = 1)

  `replace`(old, new)

    replace hit old in this cluster by new one. (work in place)

    Parameters

      - old (`macsypy.hit.ModelHit` object.) – the hit to replace

      - new (`macsypy.hit.ModelHit` object.) – the new hit

    Returns

      None

  property `replicon_name`
    Returns

      The name of the replicon where this cluster is located

    Return type

      str

  property `score`
    Returns

      The score for this cluster

    Return type

      float

## build_clusters

`macsypy.cluster.``build_clusters`(hits, rep_info, model, hit_weights)

  From a list of filtered hits, and replicon information (topology, length), build all lists of hits that satisfied the constraints:

  > - max_gene_inter_space

  > - loner

  > - multi_system

  If Yes create a cluster A cluster contains at least two hits separated by less or equal than max_gene_inter_space Except for loner genes which are allowed to be alone in a cluster

  Parameters

    - hits (list of `macsypy.hit.ModelHit` objects) – list of filtered hits

    - rep_info (`macsypy.Indexes.RepliconInfo` object) – the replicon to analyse

    - model (`macsypy.model.Model` object) – the model to study

  Returns

    list of regular clusters, the special clusters (loners not in cluster and multi systems)

  Return type

    tuple with 2 elements

    - true_clusters which is list of `Cluster` objects

    - true_loners: a dict { str function: :class:macsypy.hit.Loner | :class:macsypy.hit.LonerMultiSystem object}