`msmu.pp.adjust_ptm_by_protein`

Adjust PTM site intensities by parent protein abundance from a matched global dataset.

This computes differential PTM usage (DPU), as described by Demeulemeester et al. (2024): the site's log intensity minus the log intensity of its parent protein in the same sample, so that a site's change is read relative to whatever its protein did. It is not occupancy/stoichiometry -- that additionally requires the unmodified counterpart peptide, and is a different estimand with far lower coverage.

A site's denominator is found through the accessions it was localized on, translated into a global protein group via the global dataset's .uns['protein_map']. Nothing is looked up by peptide, so a PTM peptide the global run never observed is still adjustable whenever its protein was quantified there. Sites whose accessions span two or more quantified global groups have no valid denominator and are left unadjusted; .var['adjustment_status'] records why for every site.

The adjusted values replace the quantification that was read -- .X, or .layers[layer] when given -- the same contract as log2_transform, normalise and correct_batch_effect. A site that could not be adjusted is set to NaN rather than left holding its raw abundance, so residuals and raw abundances never share a matrix. To keep the unadjusted values, copy them into a layer first::

mdata[modality].layers["unadjusted"] = mdata[modality].X.copy()

Parameters:

Name	Type	Description	Default
`mdata`	`MuData`	`MuData` object holding the PTM data.	required
`global_mdata`	`MuData \| str \| PathLike[str]`	Matched global protein data as a `MuData` object or an `.h5mu` file path.	required
`modality`	`str`	PTM modality to adjust (e.g., `phospho_site`, `{ptm}_site`).	`'phospho_site'`
`layer`	`str \| None`	Layer to adjust. If `None`, the default layer (`.X`) will be used.	`None`
`method`	`PTMAdjustmentMethod`	Estimator to use. `'ratio'` subtracts the protein level, assuming the slope-one relationship mass action predicts; `'ridge'` instead fits a slope per site. Default is `'ratio'`, which needs no fitting and so stays usable at proteomics sample counts.	`'ratio'`
`rescale`	`bool`	If `True`, shift the adjusted values by the PTM data's overall median so they read on a comparable scale. A single constant, so it cancels in any contrast. Default is `True`.	`True`
`ridge_alpha`	`float \| None`	Ridge penalty, used only when `method='ridge'`. A single-predictor ridge keeps `Sxx / (Sxx + alpha)` of the least-squares slope, so a large alpha silently turns the residual into a plain mean-centering. Defaults to `DEFAULT_RIDGE_ALPHA`.	`None`

Returns:

Type	Description
`MuData`	`MuData` object with the adjusted quantification and per-site adjustment annotations.

References

Demeulemeester, N. et al. msqrob2PTM: differential abundance and differential usage analysis of MS-based proteomics data at the posttranslational modification and peptidoform level. Molecular & Cellular Proteomics 23, 100708 (2024). https://doi.org/10.1016/j.mcpro.2023.100708.