Import peptide spectrum matches (PSMs) from a percolator result file,
    generate :class:`Sii <maspy.core.Sii>` elements and store them in the
    specified :class:`siiContainer <maspy.core.SiiContainer>`. Imported ``Sii``
    are ranked according to a specified attribute and validated if they surpass
    a specified quality threshold.

    :param siiContainer: imported PSM results are added to this instance of
        :class:`siiContainer <maspy.core.SiiContainer>`
    :param filelocation: file path of the percolator result file
    :param specfile: unambiguous identifier of a ms-run file. Is also used as
        a reference to other MasPy file containers.
    :param psmEngine: PSM search engine used for peptide spectrum matching
        before percolator. For details see :func:`readPercolatorResults()`.
        Possible values are 'comet', 'xtandem', 'msgf'.
    :param qcAttr: name of the parameter to define a quality cut off. Typically
        this is some sort of a global false positive estimator (eg FDR)
    :param qcLargerBetter: bool, True if a large value for the ``.qcAttr`` means
        a higher confidence.
    :param qcCutOff: float, the quality threshold for the specifed ``.qcAttr``
    :param rankAttr: name of the parameter used for ranking ``Sii`` according
        to how well they match to a fragment ion spectrum, in the case when
        their are multiple ``Sii`` present for the same spectrum.
    :param rankLargerBetter: bool, True if a large value for the ``.rankAttr``
        means a better match to the fragment ion spectrum

    For details on ``Sii`` ranking see :func:`applySiiRanking()`

    For details on ``Sii`` quality validation see :func:`applySiiQcValidation()`

def importPercolatorResults(siiContainer, filelocation, specfile, psmEngine,
                            qcAttr='qValue', qcLargerBetter=False,
                            qcCutoff=0.01, rankAttr='score',
                            rankLargerBetter=True):
    """Import peptide spectrum matches (PSMs) from a percolator result file,
    generate :class:`Sii <maspy.core.Sii>` elements and store them in the
    specified :class:`siiContainer <maspy.core.SiiContainer>`. Imported ``Sii``
    are ranked according to a specified attribute and validated if they surpass
    a specified quality threshold.

    :param siiContainer: imported PSM results are added to this instance of
        :class:`siiContainer <maspy.core.SiiContainer>`
    :param filelocation: file path of the percolator result file
    :param specfile: unambiguous identifier of a ms-run file. Is also used as
        a reference to other MasPy file containers.
    :param psmEngine: PSM search engine used for peptide spectrum matching
        before percolator. For details see :func:`readPercolatorResults()`.
        Possible values are 'comet', 'xtandem', 'msgf'.
    :param qcAttr: name of the parameter to define a quality cut off. Typically
        this is some sort of a global false positive estimator (eg FDR)
    :param qcLargerBetter: bool, True if a large value for the ``.qcAttr`` means
        a higher confidence.
    :param qcCutOff: float, the quality threshold for the specifed ``.qcAttr``
    :param rankAttr: name of the parameter used for ranking ``Sii`` according
        to how well they match to a fragment ion spectrum, in the case when
        their are multiple ``Sii`` present for the same spectrum.
    :param rankLargerBetter: bool, True if a large value for the ``.rankAttr``
        means a better match to the fragment ion spectrum

    For details on ``Sii`` ranking see :func:`applySiiRanking()`

    For details on ``Sii`` quality validation see :func:`applySiiQcValidation()`
    """

    path = os.path.dirname(filelocation)
    siiList = readPercolatorResults(filelocation, specfile, psmEngine)
    prepareSiiImport(siiContainer, specfile, path, qcAttr, qcLargerBetter,
                     qcCutoff, rankAttr, rankLargerBetter)
    addSiiToContainer(siiContainer, specfile, siiList)
    applySiiRanking(siiContainer, specfile)
    applySiiQcValidation(siiContainer, specfile)