The singleHit parameter for ms_proteinsummary and ms_peptidesummary should only be used for retrieving the results for a single protein. The purpose of the parameter is to do the retrieval more quickly than by generating a full results file object. This is used, for example, in the Mascot Server protein view report.

Note that the value passed as the singleHit parameter will be different in these two cases. However, in both cases the single protein hit can be obtained using ms_mascotresults::getHit(1).

Getting a single hit from the protein summary

The parameters when creating an ms_proteinsummary object should be as follows:

resfile should be the ms_mascotresfile object.
flags should generally be set to MSRES_IGNORE_PMF_MIXTURE, because the return value from getProteinSummaryHit() is the hit number that corresponds to the protein summary with mixtures and grouping ignored.

Obviously, if the protein is from the decoy section, then MSRES_DECOY also needs to be specified.
minProbability should be set to zero. If this is set to a higher value than the score for the requested protein, then no results will be returned.
maxHitsToReport should be set to 1 for clarity. Any value above one would still return only one protein. A value of zero would return no proteins.
unigeneIndexFile can be used as normal for a UniGene entry.
singleHit is the hit number as a string from the protein summary. This is the hit number in the results file, and hence is the same number as when the protein summary is used without grouping. The hit number can be obtained by creating an ms_proteinsummary object without the singleHit parameter and using getProteinSummaryHit().

Getting a single hit from the peptide summary

Mascot Server 2.3 introduced caching of results files for peptide summary reports. See Using the pepsum cache for protein_view.pl for details. If caching is enabled, opening the results file in the usual way is as fast as using the singleHit parameter.

For backwards compatibility, and when caching is disabled, you can still use the singleHit parameter. In that case, the parameters when creating an ms_peptidesummary object should be as follows:

resfile should be the ms_mascotresfile object.
flags can be set to 0. All of the flags are still processed and used as for a normal results object. However, since a single protein is being returned, flags relating to grouping are essentially ignored.

MSRES_REQUIRE_BOLD_RED will have a limited meaning: every peptide will be 'bold' because it s the first time it has been reported.

The MSRES_DUPE_INCL_ and MSRES_DUPE_REMOVE_ flags are treated as normal.
minProbability should be set to zero. If this is set to a higher value than the score for the requested protein, then no results will be returned.
maxHitsToReport should be set to 1 for clarity. Any value above one would still return only one protein. A value of zero would return no proteins.
unigeneIndexFile can be used as normal for a UniGene entry.
ignoreIonsScoreBelow should be set to the same value that you would normally use.
minPepLenInPepSummary should be set to the same value that you would normally use.
singleHit is the accession string for the protein that is to be retrieved. For new applications, the database ID should be specified in the string, followed by a colon. Example: "3:CH60_SHEON".
flags2 should be MSPEPSUM_SINGLE_HIT_DBIDX if the singleHit accession string starts with the database ID followed by a colon.