mscompress.annotations

Peptide-spectrum match (PSM) readers.

Data class

PSM dataclass

PSM(
    scan_number: int,
    peptide: str,
    charge: int,
    score: float,
    proteins: List[str] = list(),
    spectrum_index: Optional[int] = None,
    q_value: Optional[float] = None,
    pep: Optional[float] = None,
    retention_time: Optional[float] = None,
    precursor_mz: Optional[float] = None,
    precursor_mass: Optional[float] = None,
    mass_diff: Optional[float] = None,
    modified_peptide: Optional[str] = None,
    num_matched_ions: Optional[int] = None,
    num_total_ions: Optional[int] = None,
    rank: int = 1,
    is_decoy: bool = False,
    extra: Dict[str, Any] = dict(),
)

Peptide-Spectrum Match (PSM) data structure.

Represents a single identification result linking a spectrum to a peptide.

Attributes:

Name	Type	Description
scan_number	int	Scan number from the mass spectrometer.
peptide	str	Identified peptide sequence (without modifications).
charge	int	Precursor charge state.
score	float	Primary search/scoring metric.
proteins	List[str]	List of protein accessions.
spectrum_index	Optional[int]	Zero-based index of the spectrum (if known).
q_value	Optional[float]	FDR-controlled q-value.
pep	Optional[float]	Posterior Error Probability.
retention_time	Optional[float]	Retention time in seconds.
precursor_mz	Optional[float]	Precursor m/z value.
precursor_mass	Optional[float]	Precursor neutral mass.
mass_diff	Optional[float]	Difference between observed and calculated mass.
modified_peptide	Optional[str]	Peptide sequence with modification annotations.
num_matched_ions	Optional[int]	Number of matched fragment ions.
num_total_ions	Optional[int]	Total number of theoretical fragment ions.
rank	int	Hit rank (1 = best).
is_decoy	bool	Whether this is a decoy hit.
extra	Dict[str, Any]	Additional format-specific fields.

is_target property

is_target: bool

Whether this is a target (non-decoy) hit.

Readers

TSVReader

TSVReader(
    source: Union[str, Path, BaseAnnotationFile],
    decoy_prefix: str = "DECOY_",
)

Bases: BasePSMReader

Reader for Percolator TSV/PIN files.

Supports reading from file paths (compressed or uncompressed), tar archive members, or raw bytes via BaseAnnotationFile.

Example

reader = TSVReader("results.pin")
for psm in reader:
    print(psm.peptide, psm.score)

# Read from tar archive
import tarfile
with tarfile.open("archive.tar") as tar:
    reader = PINReader.from_tar(tar, "results.pin")
    for psm in reader:
        print(psm.peptide)

Initialize the PIN reader.

Parameters:

Name	Type	Description	Default
source	Union[str, Path, BaseAnnotationFile]	Source for reading - file path or AnnotationSource.	required
decoy_prefix	str	Prefix used to identify decoy proteins.	'DECOY_'

format property

format: AnnotationFormat

Return the format identifier.

filter_to_file

filter_to_file(
    output_path: Union[str, Path], scan_numbers: Set[int]
) -> None

Write a subset of PSMs matching the given scan numbers to a new file.

Parameters:

Name	Type	Description	Default
output_path	Union[str, Path]	Path to the output file.	required
scan_numbers	Set[int]	Set of scan numbers to include.	required

PepXMLReader

PepXMLReader(
    source: Union[str, Path, BaseAnnotationFile],
    min_rank: int = 1,
    decoy_prefix: str = "DECOY_",
)

Bases: BasePSMReader

Reader for pepXML search result files.

pepXML is an XML format for peptide identification results from database search engines like Comet, X!Tandem, MSFragger, etc.

Supports reading from file paths (compressed or uncompressed), tar archive members, or raw bytes via AnnotationSource.

Example

reader = PepXMLReader("results.pepXML")
for psm in reader:
    print(psm.peptide, psm.score)

# Get PSMs for a specific scan
psms = reader.get_by_scan(1234)

Initialize the pepXML reader.

Parameters:

Name	Type	Description	Default
source	Union[str, Path, BaseAnnotationFile]	Source for reading - file path or BaseAnnotationFile.	required
min_rank	int	Only include hits with rank <= min_rank.	1
decoy_prefix	str	Prefix used to identify decoy proteins.	'DECOY_'

format property

format: AnnotationFormat

Return the format identifier.

filter_to_file

filter_to_file(
    output_path: Union[str, Path], scan_numbers: Set[int]
) -> None

Write a subset of PSMs matching the given scan numbers to a new file.

Parameters:

Name	Type	Description	Default
output_path	Union[str, Path]	Path to the output file.	required
scan_numbers	Set[int]	Set of scan numbers to include.	required