msmu.pp.to_ptm

Summarize peptide-level data to PTM-level data.

Sites are localized from the peptide's own proteins accessions and the attached FASTA, so this step does not need an inferred protein_group and the resulting site ids do not depend on any other dataset.

A site's position counts residues only -- the text inside a modification tag is never counted -- so the same peptidoform yields the same site in every notation. Each peptidoform is parsed and checked against its stripped_peptide; a notation msmu cannot read raises rather than produce misplaced sites.

Parameters:

Name	Type	Description	Default
mdata	MuData	MuData object containing peptide-level data.	required
modi_name	str	Name of the PTM to summarize (e.g., "phospho"). Will be used in the output modality name (e.g., phospho_site).	required
modification	str | Sequence[str]	The modification tag, exactly as it appears in peptide (brackets and case included), or several of them to summarize into one modality. A tag may be qualified by its residue to match that residue only. Examples: "[+79.9663]" (Sage; the decimals follow the search settings), "(UniMod:21)" (DIA-NN), "(Phospho (STY))" (MaxQuant), ["S[167]", "T[181]", "Y[243]"] (FragPipe, which writes the modified residue's total mass). If nothing matches, the error lists the tags the data contains.	required
layer	str | None	Layer to use for quantification aggregation. If None, the default layer (.X) will be used. Defaults to None.	None
agg_method	Literal['median', 'mean', 'sum', 'median_polish', 'directlfq']	Aggregation method to use. One of "median", "mean", "sum", "median_polish", or "directlfq". Defaults to "median_polish", which models a per-peptidoform effect and so is not perturbed when the set of peptidoforms supporting a site changes between samples; for a site backed by a single peptidoform it is identical to "median". A sample whose peptidoforms are all observed in that sample alone cannot be compared with the others and is left NaN. "median_polish" applies Tukey's median polish per group and "directlfq" applies the DirectLFQ rollup per group; both assume the quantification is in log2 space (apply log2_transform first).	'median_polish'
top_n	int | None	Number of top features to consider for summarization. If None, all features are used. Defaults to None.	None
rank_method	Literal['median_intensity', 'total_intensity', 'max_intensity', 'mean_intensity']	Method to rank features when selecting top_n. Defaults to "median_intensity".	'median_intensity'
multisite	Multisite	What a peptidoform carrying the target modification on several residues quantifies. "combination" (default) gives it to the set of sites it carries, as one feature ("P1|S5_S8"): a multiply modified peptide's change cannot be attributed to one of its sites, the way a shared peptide's cannot be attributed to one protein, so it is reported as the group it belongs to. Every peptidoform then feeds exactly one feature, and the features with .var["count_site"] == 1 are the site table built from singly modified peptidoforms alone. "pool" gives its whole value to each of its sites instead -- copied, not divided -- so a site pools singly and multiply modified peptidoforms and one measurement can reach several sites. Peptidoforms differing only in other modifications or missed cleavages share a feature either way.	'combination'

Returns:

Name	Type	Description
MuData	MuData	MuData object containing PTM-level data.

Notes

Adds <modi_name>_site to the supplied MuData in place. Use a copy to preserve the original. Requires peptide data and FASTA-derived protein_info; see to_peptide and attach_fasta.

Examples:

import msmu as mm
# mdata already contains peptide quantification and attached FASTA annotations.
mdata = mm.pp.to_ptm(mdata, modi_name="phospho", modification="(unimod:21)")