API Reference

Package

Command Line

class mcp_pyphotomol.main.EnvironmentType(*values)

Bases: Enum

Enum to define environment type.

PRODUCTION = 1

DEVELOPMENT = 2

Server State

Tools

mcp_pyphotomol.tools._photomol.append_function_call_to_logbook(function_name: str, params: dict) → None

Append a function call to the MCP logbook.

Parameters:

• function_name (str) – The name of the function being called.

• params (dict) – The parameters passed to the function.

mcp_pyphotomol.tools._photomol.tool_with_log()

Decorator that combines @mcp.tool() with automatic logging to the MCP logbook.

Returns:

Decorator that registers a function as an MCP tool and logs calls.

Return type:

Callable

mcp_pyphotomol.tools._photomol.get_user_name() → str

Get the current user name Useful to finding the path to a folder when the user wants to import a file or a folder :returns: The current user name. :rtype: str

mcp_pyphotomol.tools._photomol.list_MP_files_in_folder(folder_path: Path) → str

List all files in a folder.

Parameters:

folder_path (Path) – The path to the folder to list files from.

Returns:

A comma-separated list of file names in the folder.

Return type:

str

Notes

This function only lists files with the “.h5” or “.csv” extension.

mcp_pyphotomol.tools._photomol.reset_analyzer() → str

Reset the MP_ANALYZER instance.

Returns:

A message indicating that the analyzer has been reset.

Return type:

str

mcp_pyphotomol.tools._photomol.reset_calibrator() → str

Reset the MP_CALIBRATOR instance.

Returns:

A message indicating that the calibrator has been reset.

Return type:

str

mcp_pyphotomol.tools._photomol.get_model_names(calibrator: bool = False) → list

Get the names of the models in the MP_ANALYZER or MP_CALIBRATOR instance.

Parameters:

calibrator (bool) – If True, get the model names from the MP_CALIBRATOR instance. If False, get the model names from the MP_ANALYZER instance.

Returns:

A list of model names.

Return type:

list

mcp_pyphotomol.tools._photomol.import_single_file(file_path: Path, name: str = '', calibrator: bool = False) → str

Import data files into the MP_ANALYZER instance.

Parameters:

• file_path (Path) – The path to the data file to be imported.

• name (str) – The name to assign to the imported data. If the name is not provided, it will be derived from the file name.

• calibrator (bool) – If True, the data will be imported into the MP_CALIBRATOR instance instead of MP_ANALYZER. This is useful for calibration data.

Returns:

A message indicating the success or failure of the import operation.

Return type:

str

mcp_pyphotomol.tools._photomol.load_example_data() → str

Load example data into the MP_ANALYZER instance. The example data contains simulated MP measurements of a protein at different concentrations The proteins can dimerize: A + A <=> A2 :returns: A message indicating that the example data has been loaded successfully. :rtype: str

mcp_pyphotomol.tools._photomol.load_example_data_for_calibration() → str

Load example data (contrasts) in the MP_CALIBRATOR instance. As a result, the MP_CALIBRATOR will have two MP files. One file with one peak, and another file with two peaks.

We recommend running the tool ‘calibrate’ afterwards with the following parameters:

known_standards=[[148,66],[480]]

Returns:

A message indicating that the example data has been loaded successfully.

Return type:

str

mcp_pyphotomol.tools._photomol.import_folder(folder_path: Path, pattern: str = '', calibrator: bool = False) → str

Import all data files from a folder into the MP_ANALYZER instance. To create the histograms, proceed with the create_histogram_manual or create_histogram_automatic tool.

Parameters:

• folder_path (Path) – The path to the folder containing data files to be imported.

• pattern (str) – A pattern to filter the files to be imported. If not provided, all files in the folder will be imported. For example, if the pattern is ‘monomer’, only files containing ‘monomer’ in their name will be imported.

• calibrator (bool) – If True, the data will be imported into the MP_CALIBRATOR instance instead of MP_ANALYZER. This is useful for calibration data.

Returns:

A message indicating the success or failure of the import operation.

Return type:

str

Note

After importing the data, the natural step is to call the tool ‘create_histogram_manual’ or ‘create_histogram_automatic’.

mcp_pyphotomol.tools._photomol.create_histogram(min_value: float | None = None, max_value: float | None = None, bin_width: float | None = None, use_masses: bool = True, calibrator: bool = False) → str

Create the histograms with the specified parameters. To let the function infer the min_value, max_value and bin_width, leave them as None.

Parameters:

• min_value (float) – The minimum value for the histogram. If None, it will be inferred from the data.

• max_value (float) – The maximum value for the histogram. If None, it will be inferred from the data.

• bin_width (float) – The size of each bin in the histogram. If None, it will be inferred from the data.

• use_masses (bool) – If True, the histogram will be created using mass values. If False, it will use contrast values.

• calibrator (bool) – If True, the histogram will be created for the MP_CALIBRATOR instance instead of MP_ANALYZER. This is useful for calibration data.

Returns:

A message indicating the success or failure of the histogram creation, and the parameters used for the histogram.

Return type:

str

mcp_pyphotomol.tools._photomol.create_histogram_manual(min_value: float, max_value: float, bin_width: float, use_masses: bool = True, calibrator: bool = False) → str

Create the histograms using parameters given by the user

Parameters:

• min_value (float) – The minimum value for the histogram.

• max_value (float) – The maximum value for the histogram.

• bin_width (float) – The width of the bins for the histogram.

• use_masses (bool) – If True, the histogram will be created using mass values.

• calibrator (bool) – If True, the histogram will be created for the MP_CALIBRATOR instance If False, the histogram will be created for the MP_ANALYZER instance.

Returns:

A message indicating the success or failure of the histogram creation, and the parameters used for the histogram.

Return type:

str

Notes

The following default values could work.

For contrast data, try:

min_value=-0.1, max_value=0, bin_width=0.0004, use_masses=False

For mass data:

min_value=0, max_value=1000, bin_width=10, use_masses=True

mcp_pyphotomol.tools._photomol.create_histogram_automatic(use_masses: bool = True, calibrator: bool = False) → str

Let pyphotomol find suitable histogram parameters automatically. And then create the histograms.

Parameters:

• use_masses (bool) – If True, the histogram will be created using mass values.

• calibrator (bool) – If True, the histogram will be created for the MP_CALIBRATOR instance If False, the histogram will be created for the MP_ANALYZER instance.

Returns:

A message indicating the success or failure of the histogram creation, and the parameters used for the histogram.

Return type:

str

mcp_pyphotomol.tools._photomol.update_plot_config(plot_width: int = 1000, plot_height: int = 600, plot_type: str = 'png', font_size: int = 14, normalize: bool = False, contrasts: bool = False, cst_factor_for_contrast: float = 1, x_range: list[float] | None = None) → str

Edit the plot configuration for the histograms.

Parameters:

• plot_width (int) – The width of the plot in pixels.

• plot_height (int) – The height of the plot in pixels.

• plot_type (str) – The type of the plot, e.g., ‘png’, ‘svg’, or ‘jpg’.

• font_size (int) – The font size for the plot

• normalize (bool) – If True, the histogram will be normalized.

• contrasts (bool) – If True, the histogram will be created using contrast values.

• cst_factor_for_contrast (float) – The contrast factor to be used when creating the histogram with contrast values.

• x_range (list[float] | None) – The x-axis range for the histogram. For example, [0, 400]. If None, the default range will be used.

Returns:

A message indicating the success or failure of the plot configuration update.

Return type:

str

mcp_pyphotomol.tools._photomol.update_legend_config(add_masses_to_legend: bool = True, add_percentage_to_legend: bool = False, add_labels: bool = True, add_percentages: bool = True, line_width: int = 3) → str

Edit the legend configuration for the histograms.

Parameters:

• add_masses_to_legend (bool) – If True, masses (or contrasts) will be added to the legend. The masses/contrasts are obtained from a multi-gaussian fit.

• add_percentage_to_legend (bool) – If True, the percentage of counts will be added to the legend.

• add_labels (bool) – If True, labels will be added to the plot.

• add_percentages (bool) – If True, percentages will be added to the plot.

• line_width (int) – The width of the lines in the legend.

Returns:

A message indicating the success or failure of the legend configuration update.

Return type:

str

mcp_pyphotomol.tools._photomol.update_layout_config(stacked: bool = True, show_subplot_titles: bool = False, vertical_spacing: float = 0.04, shared_yaxes: bool = True, extra_padding_y_label: float = 0.04) → str

Edit the layout configuration for the histograms.

Parameters:

• stacked (bool) – If True, the histograms will be stacked. There will be as many rows as input files.

• show_subplot_titles (bool) – If True, the subplot titles will be shown.

• vertical_spacing (float) – The vertical spacing between subplots.

• shared_yaxes (bool) – If True, the y-axes will be shared across subplots.

• extra_padding_y_label (float) – Extra padding for the y-axis label. Important for the y-axis label to be visible. Only used if the plots are stacked.

Returns:

A message indicating the success or failure of the layout configuration update.

Return type:

str

mcp_pyphotomol.tools._photomol.update_axis_config(showgrid_x: bool = True, showgrid_y: bool = True, n_y_axis_ticks: int = 3, axis_linewidth: int = 1, axis_tickwidth: int = 1, axis_gridwidth: int = 1) → str

Edit the axis configuration for the histograms. :param showgrid_x: If True, the x-axis grid will be shown. :type showgrid_x: bool :param showgrid_y: If True, the y-axis grid will be shown. :type showgrid_y: bool :param n_y_axis_ticks: The number of ticks on the y-axis. :type n_y_axis_ticks: int :param axis_linewidth: The width of the axis lines. :type axis_linewidth: int :param axis_tickwidth: The width of the axis ticks. :type axis_tickwidth: int :param axis_gridwidth: The width of the axis grid lines. :type axis_gridwidth: int

Returns:

A message indicating the success or failure of the axis configuration update.

Return type:

str

mcp_pyphotomol.tools._photomol.plot_histograms(colors_hist: list[str] | str | None = None, save_as_html: bool = False, calibrator: bool = False) → str

Plot the histograms using the current configuration.

Parameters:

• colors_hist (list[str] | str | None) – A list of colors to be used for the histograms. One color per file Each color should be a valid hex color code (e.g., ‘#FF5733’) or a named color (e.g., ‘red’). If None, default colors will be used. If a single string is provided, it will be used for all histograms

• save_as_html (bool) – If True, the plot will be saved as an HTML file.

• calibrator (bool) – If True, the histograms will be plotted for the MP_CALIBRATOR instance instead than MP_ANALYZER. This is useful for calibration data.

Returns:

The path to the saved plot

Return type:

str

Note

This function will only work if the tool ‘create_histogram_manual’ or the tool ‘create_histogram_automatic’ has been called first.

mcp_pyphotomol.tools._photomol.guess_peaks(min_height: float = 10, min_distance: float = 4, prominence: float = 4, calibrator: bool = False, experiment: str = 'all') → str

Automatically detect histogram peaks.

Parameters:

• min_height (float) – The minimum height of the peaks to be detected.

• min_distance (float) – The minimum distance between peaks to be detected.

• prominence (float) – The prominence of the peaks to be detected.

• calibrator (bool) – If True, the peak detection will be performed on the MP_CALIBRATOR instance instead of the MP_ANALYZER instance.

• experiment (str) – The name of the experiment to perform peak detection on. If ‘all’, peak detection will be performed on all experiments.

Returns:

JSON string with peak positions for each experiment.

Return type:

str

mcp_pyphotomol.tools._photomol.fit_multi_gaussian(peaks_guess: list[float] | dict[str, list[float]] | None = None, mean_tolerance: float | None = None, std_tolerance: float | None = None, threshold: float | None = None, fit_baseline: bool = False, baseline: float = 0.0, min_height: float = 10, min_distance: float = 4, prominence: float = 4, calibrator: bool = False, experiment: str = 'all') → str

Fit a multi-gaussian model to the histograms.

Parameters:

• peaks_guess (list[float] | None) – A list of initial guesses for the peaks of the gaussians. If a dictionary is supplied, keys must match experiment names and values must be lists of initial guesses for the peaks of the gaussians for each experiment.

• mean_tolerance (float | None) – The tolerance for the mean of the gaussians. If None, defaults will be applied: guess ± abs(guess)/2

• std_tolerance (float | None) – The tolerance for the standard deviation of the gaussians. If None, the maximum fitted standard deviation will be equal to the initial guesses.

• threshold (float | None) – For masses: minimum value that can be observed (in kDa units). Default is 40. For contrasts: maximum value that can be observed (should be negative). Default is -0.0024. If None, defaults are applied based on detected data type.

• fit_baseline (bool) – If True, a baseline will be fitted and subtracted from the histograms before fitting the gaussians. The baseline argument will be ignored in this case.

• baseline (float) – The baseline value to be subtracted from the histograms before fitting. Useful to remove background noise.

• min_height (float) – The minimum height of the peaks to find the initial guesses.

• min_distance (float) – The minimum distance between the peaks to find the initial guesses.

• prominence (float) – The prominence of the peaks to find the initial guesses.

• calibrator (bool) – If True, the fitting will be performed on the MP_CALIBRATOR instance instead of the MP_ANALYZER instance.

• experiment (str) – The name of the experiment to fit the model to. If ‘all’, the fitting will be performed on all experiments.

Returns:

A message indicating the success or failure of the fitting process.

Return type:

str

Notes

After running this tool, we recommend running show_fitted_parameters() to see the results, and running get_legends_dataframe() to obtain the legends information before plotting with plot_histograms_and_fits().

mcp_pyphotomol.tools._photomol.show_fitted_parameters(calibrator: bool = False) → str

Show the fitted parameters of the multi-gaussian model.

Parameters:

calibrator (bool) – If True, the fitted parameters will be shown for the MP_CALIBRATOR instance instead of MP_ANALYZER. This is useful for calibration data.

Returns:

A JSON string containing the fitted parameters of the multi-gaussian model.

Return type:

str

mcp_pyphotomol.tools._photomol.get_legends_dataframe(repeat_colors: bool = True, calibrator: bool = False) → str

Obtain default labels and colors to plot the fitted histograms.

Parameters:

• repeat_colors (bool, default True) – If True, repeat the same color scheme for each model’s peaks. If False, use sequential colors across all peaks from all models.

• calibrator (bool) – If True, the legends will be obtained for the MP_CALIBRATOR instance instead of MP_ANALYZER. This is useful for calibration data.

Returns:

A JSON string containing the legends and colors for the fitted histograms. The four columns are [‘legends’, ‘color’, ‘select’, ‘show_legend’]. The ‘select’ column controls if traces are shown or not, while the ‘show_legend’ column controls if the legend is shown.

Return type:

str

mcp_pyphotomol.tools._photomol.plot_histograms_and_fits(legends_df: str | None = None, colors_hist: list[str] | str | None = None, save_as_html: bool = False, calibrator: bool = False) → str

Plot the histograms and fitted curves using the current plotting configuration. The plotting configuration is defined by the PLOT_CONFIG, LEGEND_CONFIG, LAYOUT_CONFIG, and AXIS_CONFIG. To update use the tools update_plot_config, update_legend_config, update_layout_config, and update_axis_config.

Parameters:

• legends_df (str | None) – A JSON string representing a DataFrame containing legends, colors, and selections If None, the default legends will be used. This DataFrame affects the fitted curves only, not the histograms. It contains the columns [‘legends’, ‘color’, ‘select’, ‘show_legend’]. The ‘select’ column is a boolean mask indicating which peaks to include in the plot. The ‘show_legend’ column controls if the corresponding legend is shown.

• colors_hist (list[str] | str | None) – A list of colors for the histograms (one per model). If a string, it will be used for all histograms, If None, default colors will be used.

• save_as_html (bool) – If True, the plot will be also saved as an HTML file.

• calibrator (bool) – If True, the histograms and fits will be plotted for the MP_CALIBRATOR instance instead of MP_ANALYZER. This is useful for calibration data.

Returns:

The path to the saved plot.

Return type:

str

Note

The legends_df JSON can be obtained by calling the get_legends_dataframe tool.

mcp_pyphotomol.tools._photomol.calibrate(known_standards: list) → str

Obtain a calibration function using a list of known standards The calibration function is defined as f(mass) = contrast f(mass) = slope * mass + intercept

Parameters:

known_standards (list) – A list of known standard values to be used for calibration. Can be a list of floats in we only have one MP file Must be a list of lists with floats if we have multiple MP files

Returns:

A json string with the results of the calibration

Return type:

str

Note

An example input for known_standards is [[148, 66], [480]] if we have two MP files An example input for one MP file is [480,148,66]

mcp_pyphotomol.tools._photomol.plot_calibration(save_as_html: bool) → str

Plot the calibration results. :param save_as_html: Whether to save the plot as an HTML file. :type save_as_html: bool

Returns:

A message indicating the success or failure of the plotting process.

Return type:

str

Resources

mcp_pyphotomol.resources._photomol.get_mcp_logbook(date: str) → str

Retrieves the mcp server logbook for a specific date. :param date: The date for which the logbook is requested, formatted as ‘YYYY-MM-DD’ or ‘DD-MM-YYYY’. :type date: str

Returns:

JSON text with the logbook data for the specified date, or an error message if no logbook is found.

Return type:

str