# system

This module classes and functions which a given set of hits and a model compute if this set satisfy the model or not

The object which check the compliance of hits to a model is MatchMaker which have 2 sub-classes for ordered and unordered replicons

MatchMaker.match method link hit to a model (`macsypy.hit.ValidHit`) and then check if these valid hit satisfy the quorum constraints defined in the model. According this it instanciate a `macsypy.system.System` or `macsypy.system.RejectedCandidate` for ordered replicons or `macsypy.system.LikelySystem` or `macsypy.system.UnlikelySystem` for unordered replicons

below the inheritance diagram:

Warning

The abstract class `macsypy.system.AbstractSetOfHits` is controlled by the metaclass `macsypy.system.MetaSetOfHits` which inject on the fly several private attributes and public properties (see more in `macsypy.system.MetaSetOfHits` documentation)

## system reference api

## MatchMaker

class `macsypy.system.``MatchMaker`(model)

  Is an abstract class for (Odered/Unordered)MatchMaker the match class method must be implemented in concrete classes

  `__init__`(model)

    Initialize self. See help(type(self)) for accurate signature.

  `__weakref__`

    list of weak references to the object (if defined)

  `_create_exchangeable_map`(genes)

    create a map between an exchangeable (formly homolog or analog) gene name and it’s gene reference

    Parameters

      genes (list of `macsypy.gene.ModelGene` objects) – The genes to get the exchangeable genes

    Return type

      a dict with keys are the exchangeable gene_name and the value the reference gene

  `present_genes`()
    Returns

      the lists of genes name in model which are present in the replicon (included exchangeable)

    Return type

      tuple of 4 lists for mandatory, accessory, neutral and forbidden ([str gene_name, ..], [str gene_name], [str gene_name], [str gene_name])

  `sort_hits_by_status`(hits)

    sort `macsypy.hit.ModelHit` according the the status of the gene the hit code for.

    Parameters

      hits – list of `macsypy.hit.ModelHit` object

    Returns

      the valid hits according their status

    Return type

      a tuple of 4 lists

      - `macsypy.hit.ModelHit` for MANDATORY genes

      - `macsypy.hit.ModelHit` for ACCESSORY genes

      - `macsypy.hit.ModelHit` for NEUTRAL genes

      - `macsypy.hit.ModelHit` for FORBIDDEN genes

## OrderedMatchMaker

class `macsypy.system.``OrderedMatchMaker`(model, redundancy_penalty)

  check if a set of hits match the quorum for ordered replicons (ordered_replicon or gembase)

  `__init__`(model, redundancy_penalty)

    Initialize self. See help(type(self)) for accurate signature.

  `match`(clusters)

    Check a set of clusters fill model constraints. If yes create a `macsypy.system.System` otherwise create a `macsypy.cluster.RejectedCandidate`.

    Parameters

      clusters (list of `macsypy.cluster.Cluster` objects) – The list of cluster to check if fit the model

    Returns

      either a System or a RejectedCandidates

    Return type

      `macsypy.system.System` or `macsypy.system.RejectedCandidate` object

## UnorderedMatchMaker

class `macsypy.system.``UnorderedMatchMaker`(model)
  `match`(hits)
    Parameters

      hits –

    Returns

## HitSystemTracker

class `macsypy.system.``HitSystemTracker`(systems)

  track in which system is implied each hit

  `__init__`(systems)

    Initialize self. See help(type(self)) for accurate signature.

  `__weakref__`

    list of weak references to the object (if defined)

## MetaSetOfHits

class `macsypy.system.``MetaSetOfHits`(name, bases, namespace, **kwargs)

  This metaclass control the AbstractSetOfHits class creation. In this metaclass we inject on the fly several attributes and properties two private attributes and one public property corresponding to each value of _supported_status class attribute defined in the concrete classes. for instance for System class

  > - the attributes

  >     - self._mandatory

  >     - self._mandatory_occ

  >     - self._accessory

  >     - self._accessory_occ

  >     - self._neutral

  >     - self._neutral_occ

  > - and the properties

  >     - mandatory

  >     - accessory

  >     - neutral

  are automatically injected

  The value for attributes _<status>_occ are filled by the count method which is defined in AbstractSetOfHits

  `__call__`(*args, **kwargs)

    Call self as a function.

  `getter_maker`()

    Create a property which allow to access to the gene corresponding of the cat of the model

    Parameters

      cat (str) – the type of gene category to which we create the getter

    Returns

      unbound method

## AbstractSetOfHits

class `macsypy.system.``AbstractSetOfHits`(*args, **kwargs)

  Is the mother class of System, RejectedCandidates, LikelySystems UnlikelySystem, …

  `__init__`(model)

    Initialize self. See help(type(self)) for accurate signature.

  `__weakref__`

    list of weak references to the object (if defined)

  `count`()

    fill structures one for supported status mandatory, accessory, … each structure count how many hit for each gene of the model mandatory_occ = { gene_name : [ModelHit, …] :return: None

  property `position`
    Returns

      The position of the first and last hit, excluded the hit coding for loners. If the system is composed only by loners, used loners to compute position

    Return type

      tuple (start: int, end:int)

  property `replicon_name`
    Returns

      The name of the replicon

    Return type

      str

  property `wholeness`
    Returns

      a score indicating the genes ratio of the model which have at least one hit by default full system is mandatory + accessory (‘neutral’ genes do not count) but for special corner case it can be sepcified in model definition (xml) or on the command line

    Return type

      float

## AbstractClusterizedHits

class `macsypy.system.``AbstractClusterizedHits`(*args, **kwargs)
  `__init__`(model, clusters)

    Initialize self. See help(type(self)) for accurate signature.

  `fulfilled_function`(*genes)
    Parameters

      gene – The genes which must be tested.

    Returns

      the common functions between genes and this system.

    Return type

      set of string

## System

class `macsypy.system.``System`(*args, **kwargs)

  Modelize as system. a system is an occurrence of a given model on a replicon.

  `__init__`(model, clusters, redundancy_penalty=1.5)
    Parameters

      - model (`macsypy.model.Model` object) – The model which has ben used to build this system

      - clusters (list of `macsypy.cluster.Cluster` objects) – The list of cluster that form this system

  `get_hits_encoding_multisystem`()
    Returns

      The hits codding for a gene taged as multi system

    Return type

      set of `macsypy.hit.ModelHit` object

  `get_loners`()
    Returns

      The True Loners (Loner which not colocalize with an other hit) belonging to the systems

    Return type

      set of `macsypy.hit.Loner` object

  `get_multisystems`()
    Returns

      The MultiSystem hit (comming from out system (other cluster or loner) and tag as multisystem)

    Return type

      set of `macsypy.hit.MultiSystem` | `macsypy.hit.LonerMultiSystem` object

  property `hits`
    Returns

      The list of all hits that compose this system

    Return type

      [`macsypy.hit.ValidHits` , … ]

  `is_compatible`(other)
    Parameters

      other (`macsypy.system.System` object) – the other systems to test compatibility

    Returns

      True if other system is compatible with this one. False otherwise. Two systems are compatible if they do not share `macsypy.hit.CoreHit` except hit corresponding to a multi_system gene in the model.

      Note

      This method is used to compute the best combination of systems.

  property `loci_nb`
    Returns

      The number of loci of this system (loners are not considered)

    Return type

      int >= 0

  property `loci_num`
    Returns

      the number of the corresponding locus for each cluster the cluster made of only one Loner are not considered as a loci so these clusters have a negative locus_num

    Return type

      list of int

  property `multi_loci`
    Returns

      True if the systems is encoded in multiple loci. False otherwise

    Return type

      bool

  `occurrence`()

    sometimes several systems collocates so they form only one cluster so macsyfinder build only one system the occurrence is an indicator of how many systems are it’s based on the number of occurrence of each mandatory genes The multi_system genes are not take in account.

    Returns

      a predict number of biologic systems

  property `score`
    Returns

      a score take in account * if a hit match for the gene or it is an exchangeable gene * if a hit is duplicated and already present in the system or the cluster * if a hit match for mandatory/accessory gene of the model

    Return type

      float

## RejectedCandidate

class `macsypy.system.``RejectedCandidate`(*args, **kwargs)

  Handle a set of clusters which has been rejected during the `macsypy.system.match()` step This clusters (can be one) does not fill the requirements or contains forbidden genes.

  `__init__`(model, clusters, reasons)
    Parameters

      - model (`macsypy.model.Model` object) –

      - clusters (list of `macsypy.cluster.Cluster` objects) – list of clusters. These Clusters should be created with `macsypy.cluster.Cluster` of `macsypy.hit.ModelHit` objects

      - reasons (list of string) – the reason why these clusters have been rejected

  `__str__`()
    Returns

      a string representation of this RejectedCandidates

  property `hits`
    Returns

      The list of all hits that compose this system

    Return type

      [`macsypy.hit.ModelHit` , … ]

## AbstractUnordered

class `macsypy.system.``AbstractUnordered`(*args, **kwargs)

  Technical abstract class to factorize code share between LikelySystem and UnlikelySystem

  `__init__`(model, mandatory_hits, accessory_hits, neutral_hits, forbidden_hits)

    Initialize self. See help(type(self)) for accurate signature.

  property `accessory_hits`
    Returns

      The list of accesory hits

    Return type

      list of `macsypy.hit.ModelHit` objects

  property `allowed_hits`
    Returns

      The list of allowed (mandatory, accessory, neutral) hits

    Return type

      list of `macsypy.hit.ModelHit` objects

  property `forbidden_hits`
    Returns

      The list of forbidden hits

    Return type

      list of `macsypy.hit.ModelHit` objects

  property `hits`
    Returns

      The list of all hits sorted by their position

    Return type

      list of `macsypy.hit.ModelHit` objects

  property `mandatory_hits`
    Returns

      The list of mandatory hits

    Return type

      list of `macsypy.hit.ModelHit` objects

  property `neutral_hits`
    Returns

      The list of neutral hits

    Return type

      list of `macsypy.hit.ModelHit` objects

## LikelySystem

class `macsypy.system.``LikelySystem`(*args, **kwargs)

  ” Handle components that fill the quorum requirements defined in model. with no idea about genetic organization (gene cluster) so we cannot take in account forbidden genes

  `__str__`()
    Returns

      a string representation of this LikelySystem

## UnlikelySystem

class `macsypy.system.``UnlikelySystem`(*args, **kwargs)

  Handle components that not fill the quorum requirements defined in model.

  `__init__`(model, mandatory_hits, accessory_hits, neutral_hits, forbidden_hits, reasons)
    Parameters

      - model (`macsypy.model.Model` object) – The model which has ben used to build this system

      - mandatory_hits (list of `macsypy.hit.ModelHit` objects) – The list of mandatory hits (encode for a gene tagged as mandatory)

      - accessory_hits (list of `macsypy.hit.ModelHit` objects) – The list of accessory hits (encode for a gene tagged as accessory)

      - neutral_hits (list of `macsypy.hit.ModelHit` objects) – The list of neutral hits (encode for a gene tagged as neutral)

      - forbidden_hits (list of `macsypy.hit.ModelHit` objects) – The list of hits that are forbidden

      - reasons (List of str) – the reasons why this set of hits has been rejected

  `__str__`()
    Returns

      a string representation of this UnlikelySystem

  property `reasons`
    Returns

      The reasons why it probably not a system

    Return type

      list of string