Package 'tidymst'

Get fitted model coefficients

Description

Get fitted model coefficients

Usage

mst_coefs(fits, conf_level = 0.95)

Arguments

fits	A tibble of fits from mst_fit().
conf_level	Confidence level of the intervals.

Value

A tibble with one row per parameter per fit, with the grouping columns of fits and:

• model: the model fitted.

• term: the parameter: unbound, bound, and kd and target_concentration for the Kd model or ec50 and hill for the Hill model. A fixed target_concentration is not included.

• estimate and std_error: the estimate and its standard error. Concentrations are molar.

• conf_low and conf_high: the confidence interval, from the t-distribution. Concentrations are fitted on a log scale, so their intervals are calculated on that scale and are asymmetric, and their standard errors are approximate.

Examples

doses <- read_mst_dose_response(
  tidymst_example("dppr10-cy5_dose-response-flat.xlsx")
)
fits <- mst_fit(doses, .by = target)
mst_coefs(fits)

---

Predict fitted binding curves

Description

Predict fitted binding curves

Usage

mst_curve(fits, n = 100)

Arguments

fits	A tibble of fits from mst_fit().
n	Number of points on each curve, spaced evenly on a log scale over the range of concentrations fitted.

Value

A tibble with n rows per fit, with the grouping columns of fits and:

• The concentration, named as in mst_fit() (ligand_concentration by default).

• response: the fitted response.

• delta_fnorm: the response relative to the unbound state.

• fraction_bound: the fraction of target bound.

Examples

doses <- read_mst_dose_response(
  tidymst_example("dppr10-cy5_dose-response-flat.xlsx")
)
fits <- mst_fit(doses, .by = target)
mst_curve(fits)

---

Detect the type of a MO.Affinity Analysis export

Description

MO.Affinity Analysis records which view an Excel export was made from in its ⁠Exported from:⁠ field. mst_export_type() reads that field and returns a short identifier, which read_mst() uses to pick a reader. It also recognises the project files written by MO.Control (.moc) and MO.Affinity Analysis (.nta), which are SQLite databases.

Usage

mst_export_type(path)

Arguments

path	Path to an .xlsx file exported from MO.Affinity Analysis, or a .moc or .nta project file.

Value

A string, one of:

• "traces": MST Traces, including the Raw Data Inspection variant.

• "capillary_scan": Capillary Scan.

• "compare_chart": Compare Results (Chart).

• "compare_grid": Compare Results (Grid).

• "dose_response_grouped": Dose-Response (Grouped).

• "dose_response_flat": Dose-Response (Flat).

• "affinity_project": an MO.Affinity Analysis project (.nta), with both the measurements and their analysis.

• "control_project": an MO.Control project (.moc), with the measurements only.

Examples

mst_export_type(tidymst_example("dppr10-cy5_traces.xlsx"))
mst_export_type(tidymst_example("dppr10-cy5_compare-fnorm.xlsx"))
mst_export_type(tidymst_example("dppr10-cy5.nta"))

---

Fit binding models to dose-response data

Description

Fits the binding models used by MO.Affinity Analysis by non-linear least squares, with stats::nls().

Usage

mst_fit(
  data,
  model = c("kd", "hill"),
  concentration = ligand_concentration,
  response = response,
  target_concentration = NULL,
  .by = NULL
)

Arguments

data	A data frame with a row for each concentration, such as from read_mst_dose_response() or mst_fnorm(). If data is grouped with dplyr::group_by(), each group is fitted separately.
model	The model to fit, "kd" or "hill". See the Models section.
concentration, response	<data-masking> The columns of ligand concentration (molar) and response.
target_concentration	For the Kd model, the target concentration in molar. If NULL, the default, it is estimated along with the other parameters, as MO.Affinity Analysis can do. If it is known, fixing it gives a more stable fit.
.by	<tidy-select> Columns to group by, fitting each group separately. An alternative to grouping data.

Value

A tibble with one row per group, with the grouping columns and:

• model: the model fitted.

• n: the number of points fitted.

• sigma: the residual standard deviation.

• fit: the fitted model, used by mst_coefs(), mst_curve() and mst_normalise(). NULL if the fit failed.

Models

The Kd model describes 1:1 binding of a ligand to a target, accounting for depletion of free ligand:

$f = \frac{c + c_T + K_d - \sqrt{(c + c_T + K_d)^2 - 4 c c_T}}{2 c_T}$

$y = U + (B - U) f$

where $c$ is the ligand concentration, $c_T$ the target concentration, $f$ the fraction of target bound, and $U$ and $B$ the responses of the unbound and bound states.

The Hill model describes cooperative binding:

$y = U + \frac{B - U}{1 + (EC_{50} / c)^n}$

Examples

doses <- read_mst_dose_response(
  tidymst_example("dppr10-cy5_dose-response-flat.xlsx")
)
fits <- mst_fit(doses, .by = target)
fits

mst_coefs(fits)

# Fix the target concentration at its nominal value
mst_fit(doses, target_concentration = 50e-9, .by = target)

---

Calculate normalised fluorescence from MST traces

Description

Fnorm is the ratio of the mean fluorescence in a "hot" window, while the IR laser is on, to the mean fluorescence in a "cold" window just before it, expressed in per mille. Recalculating Fnorm from read_mst_traces() lets you choose the windows without going back to MO.Affinity Analysis.

Usage

mst_fnorm(data, hot, cold = c(-1, 0))

Arguments

data	A data frame of traces, as returned by read_mst_traces(), with columns time and fluorescence.
hot, cold	Start and end times of the hot and cold windows, in seconds, as numeric vectors of length 2. The hot window depends on how long the laser was on; look up the one used in MO.Affinity Analysis with read_mst_metadata().

Details

Windows include their start and exclude their end, as MO.Affinity Analysis does, so the results match its Fnorm for the same windows.

Value

A tibble with one row per capillary, with the columns of data other than time, fluorescence and fluorescence_raw, plus response_type (always "fnorm") and response, the Fnorm in per mille. This is the same form as read_mst_dose_response(), ready for mst_fit().

Examples

traces <- read_mst_traces(tidymst_example("dppr10-cy5_traces.xlsx"))
mst_fnorm(traces, hot = c(19, 20))

# Use a shorter hot window, excluding outliers
traces |>
  dplyr::filter(included) |>
  mst_fnorm(hot = c(1.5, 2.5))

---

Normalise responses to delta Fnorm and fraction bound

Description

Uses the unbound and bound states of fitted models to express responses relative to the unbound state (delta Fnorm), and as the fraction of target bound. This puts merge sets with different baselines on the same scale.

Usage

mst_normalise(data, fits, response = response)

Arguments

data	A data frame of dose-response data, as passed to mst_fit().
fits	A tibble of fits from mst_fit(). Its grouping columns must also be in data.
response	<data-masking> The column of response, in the same units as the fits.

Value

data with two new columns:

• delta_fnorm: the response minus the unbound response.

• fraction_bound: delta_fnorm divided by the difference between the bound and unbound responses.

Examples

doses <- read_mst_dose_response(
  tidymst_example("dppr10-cy5_dose-response-flat.xlsx")
)
fits <- mst_fit(doses, .by = target)
mst_normalise(doses, fits)

---

Plot dose-response curves

Description

Draws the response at each concentration, with error bars if data has an error column, and optionally the fitted curves. Requires ggplot2.

Usage

mst_plot_dose_response(
  data,
  fits = NULL,
  concentration = ligand_concentration,
  response = response,
  colour = NULL
)

Arguments

data	A data frame of dose-response data, such as from read_mst_dose_response() or mst_fnorm().
fits	Optionally, a tibble of fits from mst_fit() to draw.
concentration, response, colour	<data-masking> The columns of ligand concentration, response, and colour of the points.

Value

A ggplot.

Examples

doses <- read_mst_dose_response(
  tidymst_example("dppr10-cy5_dose-response-flat.xlsx")
)
fits <- mst_fit(doses, .by = target)
mst_plot_dose_response(doses, fits, colour = target)

---

Plot MST traces

Description

Draws one line per capillary. Requires ggplot2.

Usage

mst_plot_traces(data, colour = ligand_concentration)

Arguments

data	A data frame of traces, as returned by read_mst_traces().
colour	<data-masking> The column to colour lines by. Numeric columns are coloured on a log scale.

Value

A ggplot.

Examples

traces <- read_mst_traces(tidymst_example("dppr10-cy5_traces.xlsx"))
mst_plot_traces(traces)

---

Read a MO.Affinity Analysis export

Description

read_mst() detects the type of export with mst_export_type() and reads its main table:

Usage

read_mst(path)

Arguments

path	Path to an .xlsx file exported from MO.Affinity Analysis, or a .moc or .nta project file.

Details

• MST Traces: read_mst_traces().

• Capillary Scan: read_mst_capillary_scan().

• Compare Results (Chart) and Dose-Response (Grouped and Flat): read_mst_dose_response().

• Compare Results (Grid): read_mst_fit().

• MO.Control (.moc) and MO.Affinity Analysis (.nta) project files: read_mst_traces().

Value

A tibble.

Project files

MO.Control (.moc) and MO.Affinity Analysis (.nta) save projects as SQLite databases, which hold everything the Excel exports are made from. read_mst_traces(), read_mst_capillary_scan() and read_mst_metadata() read both kinds of project; read_mst_dose_response() and read_mst_fit() read MO.Affinity Analysis projects, which include the analysis. They return the same columns as for the Excel exports, with these differences:

• An analysis_set column names the analysis set, as a project can hold several. A trace in more than one analysis set appears once for each. MO.Control projects have no analysis, so analysis_set, merge_set and included are missing, and run is named as MO.Affinity Analysis would name it.

• Traces also have fluorescence_raw, the fluorescence in raw counts. fluorescence is normalised to the mean before the laser switches on, which is within about 0.2% of MO.Affinity Analysis's normalisation.

• Measurement times are in UTC (the Excel exports use local time), and temperature is the measured temperature in degrees Celsius.

• mst_power is a percentage, such as "40%", rather than a label such as "Medium", and excitation_type is not available.

• The fits from read_mst_fit() are those saved in the project, which may differ from an export made at another time. They include each parameter's standard error as reported by MO.Affinity Analysis (⁠*_std_error⁠), and fixed lists any parameters that were fixed.

Fit curves (read_mst_fit_curve()) are not read from projects; calculate them with mst_fit() and mst_curve().

See Also

read_mst_metadata() for the file-level header, and read_mst_fit() and read_mst_fit_curve() for the fits included in Compare Results and Dose-Response (Grouped) exports.

Examples

read_mst(tidymst_example("dppr10-cy5_dose-response-flat.xlsx"))

# A project file from MO.Affinity Analysis
read_mst(tidymst_example("dppr10-cy5.nta"))

---

Read capillary scans

Description

Reads a Capillary Scan export: the raw fluorescence across the tray before each measurement, which is used to check for sticking, aggregation and pipetting errors.

Usage

read_mst_capillary_scan(path)

Arguments

path	Path to an .xlsx file exported from MO.Affinity Analysis, or a .moc or .nta project file.

Value

A tibble with one row per scan position per capillary. Alongside the sample and measurement settings of each capillary, it has columns:

• included: FALSE if the capillary was marked as an outlier.

• position: position along the tray, in capillary index units.

• fluorescence: raw fluorescence counts.

Project files give some extra columns; see the Project files section of read_mst().

Examples

read_mst_capillary_scan(tidymst_example("dppr10c2_capillary-scan.xlsx"))
read_mst_capillary_scan(tidymst_example("dppr10-cy5.nta"))

---

Read dose-response data

Description

Reads the response of each ligand concentration from a dose-response export.

Usage

read_mst_dose_response(path)

Arguments

path	Path to an .xlsx file exported from MO.Affinity Analysis, or a .moc or .nta project file.

Details

• Compare Results (Chart) and Dose-Response (Grouped) exports give the mean response of each concentration in each merge set, with its error. Capillaries marked as outliers are excluded.

• Dose-Response (Flat) exports give the Fnorm of every capillary. They do not record which capillaries were marked as outliers, so all are included; join to read_mst_traces() by run and capillary to find them.

• MO.Affinity Analysis project files (.nta) give the Fnorm of every capillary, calculated with mst_fnorm() using the cold and hot regions of its analysis set, and whether it was included. See the Project files section of read_mst().

Note that dates of measurement in Dose-Response (Flat) exports appear to be in UTC, while other exports use the local time of the instrument computer. Both are returned as recorded, labelled as UTC.

Value

A tibble with one row per concentration per series. It always has columns merge_set, target, target_concentration, ligand, ligand_concentration, response_type and response, followed by the other settings in the export.

• response_type is one of "fnorm", "delta_fnorm" or "fraction_bound", depending on how the data was exported. Fnorm and delta Fnorm are in per mille.

• series numbers the merge sets in the order they appear in the export, to tell apart series that share a name. It matches series in read_mst_fit() and read_mst_fit_curve().

• error is the error of the mean response.

Concentrations are molar.

Examples

read_mst_dose_response(tidymst_example("dppr10-cy5_compare-fnorm.xlsx"))

read_mst_dose_response(
  tidymst_example("dppr10-cy5_dose-response-flat.xlsx")
)

read_mst_dose_response(tidymst_example("dppr10-cy5.nta"))

---

Read binding fits

Description

Reads the fits that MO.Affinity Analysis made to each merge set. These are included in Compare Results (Chart and Grid) and Dose-Response (Grouped) exports.

Usage

read_mst_fit(path)

Arguments

path	Path to an .xlsx file exported from MO.Affinity Analysis, or a .moc or .nta project file.

Value

A tibble with one row per merge set, with columns:

• series, merge_set, target, target_concentration and ligand identify the merge set. series is missing for Grid exports.

• model: the fit model, "kd" or "hill".

• unbound and bound: the response of the unbound and bound states.

• kd and kd_confidence (Kd model): the dissociation constant and its confidence, in molar.

• target_concentration_fit (Kd model): the target concentration used in the fit, which may differ from the nominal target_concentration if it was a free parameter.

• ec50, ec50_confidence and hill (Hill model): the half-maximal concentration, its confidence, and the Hill coefficient.

• std_dev: the standard deviation of the residuals.

Grid exports also include fit statistics such as std_error, reduced_chi_sq and signal_to_noise. MO.Affinity Analysis project files (.nta) give one row per merge set per model fitted, with standard errors instead of confidences; see the Project files section of read_mst().

Examples

read_mst_fit(tidymst_example("dppr10-cy5_compare-fnorm.xlsx"))
read_mst_fit(tidymst_example("dsnppr10_compare-delta-fnorm.xlsx"))

---

Read fitted binding curves

Description

Reads the curves MO.Affinity Analysis fitted to each merge set, from the Fit-Values sheet of Compare Results (Chart) and Dose-Response (Grouped) exports.

Usage

read_mst_fit_curve(path)

Arguments

path	Path to an .xlsx file exported from MO.Affinity Analysis, or a .moc or .nta project file.

Value

A tibble with one row per point on each curve, with columns series, merge_set, target, ligand_concentration, fnorm, response_type and response. response is the curve in the units the data was exported in (see response_type); fnorm is the same curve as Fnorm. Some exports leave the curves empty, giving a tibble with no rows.

Examples

read_mst_fit_curve(tidymst_example("dsnppr10_compare-delta-fnorm.xlsx"))

---

Read export metadata

Description

Reads the header that MO.Affinity Analysis writes at the top of every export: where the data came from, when it was exported, and (for most exports) the analysis settings.

Usage

read_mst_metadata(path)

Arguments

path	Path to an .xlsx file exported from MO.Affinity Analysis, or a .moc or .nta project file.

Value

A tibble with one row. Columns include software, project, analysis_set, exported_from and exported_on, and, when the export has a single set of analysis settings, analysis_type, evaluation_strategy and the cold and hot regions in seconds (cold_start, cold_end, hot_start, hot_end).

For project files, it gives the software that wrote the file, the project name, when it was created and updated, and the instrument's device_type and optics_type. MO.Affinity Analysis projects have one row for each analysis set, with its settings.

Examples

read_mst_metadata(tidymst_example("dppr10-cy5_traces.xlsx"))
read_mst_metadata(tidymst_example("dppr10-cy5.nta"))

---

Read MST traces

Description

Reads an MST Traces export: the fluorescence of each capillary over time, before and while the IR laser heats it. Normalised fluorescence (Fnorm) can be recalculated from the traces with mst_fnorm().

Usage

read_mst_traces(path)

Arguments

path	Path to an .xlsx file exported from MO.Affinity Analysis, or a .moc or .nta project file.

Value

A tibble with one row per time point per capillary. Alongside the sample and measurement settings of each capillary, it has columns:

• included: FALSE if the capillary was marked as an outlier.

• time: time in seconds relative to the laser switching on.

• fluorescence: fluorescence, normalised by MO.Affinity Analysis.

Concentrations are molar. Project files give some extra columns; see the Project files section of read_mst().

Examples

read_mst_traces(tidymst_example("dppr10-cy5_traces.xlsx"))
read_mst_traces(tidymst_example("dppr10-cy5.nta"))

---

Get paths to example exports

Description

tidymst comes bundled with example MO.Affinity Analysis exports in its inst/extdata directory. This function makes them easy to access.

Usage

tidymst_example(file = NULL)

Arguments

file	Name of a file. If NULL, the example files will be listed.

Details

Most of the files are from one experiment: the binding of a Cy5-labelled PPR protein, dPPR10-Cy5, to two RNA targets (atpH-fl and NEAT1-fl), exported in several formats.

Value

A path, or a character vector of file names.

Examples

tidymst_example()
tidymst_example("dppr10-cy5_traces.xlsx")

---