Lacking a user manual or help page

[WuyangFF95]

Dear Shah Lab Members,

I'm a software user which want to study your results and use different models in your package. Unfortunately, I can only find one example in the main page of this package: (https://github.com/shahcompbio/MultiModalMuSig.jl/blob/master/README.md)

I also tried to fetch the description and the user manual of this package within Julia by
\code{?MultiModalMuSig} but failed.

Can you provide a user manual for me? So that I can learn the package faster. Thanks!

[funnell]

Hi @WuyangFF95, what are you trying to do? I'm happy to help, and can certainly improve the documentation!

[WuyangFF95]

I have three questions:

1. Extract signatures and determine signature probabilities from tumors' mutation counts matrix. But different from the samples provided, my mutation count matrix has 1536 SBS mutation types + 78 Double Base Substitution (DBS) mutation types + 83 Indel mutation types. I think that I should split each of these mutation count matrix into 3 matrices, and consider them as 3 modalities of mutation types so that I can run the MMCTM model. But what is the code to realize this task?
   (The example mutation count matrix is provided in the attached file. Matrix format may be different from your example, but format conversion is trivial and can be easily done)
   ground.truth.syn.catalog.xlsx

2. How can I convert signature probabilities within a tumor to mutation counts of signatures within a tumor? Is it simply by multiplying probabilities with total mutation count of the tumor?

3. What is the code to realize the task in 1. , but using LDA or CTM model?

Thanks!

[funnell]

Hi @WuyangFF95 ,

I've updated the README file to hopefully make things clearer.

1. I'd recommend splitting the three mutation types into three separate matrices and construct the model input like so:

X = format_counts_mmctm(sbs_counts, dbs_counts, indel_counts)
model = MMCTM([sbs_k, dbs_k, indel_k], [sbs_alpha, dbs_alpha, indel_alpha], X)
fit!(model, tol=1e-5)

where sbs_k, etc. are the number of signatures for the SBS modality, and sbs_alpha is the signature Dirichlet hyperparameter for SBS signatures (maybe something like 0.1), etc. You can check the example count files in the data directory to see the format (pretty basic and the "term" column should be optional)

2. Sure you could do that. You might also consider setting a probability threshold. I'd also be careful that rounding errors don't produce an incorrect number of total mutations per sample.

3. See the updated README

I hope that helps, let me know if anything else is unclear or if you have any other questions.

[WuyangFF95]

Thank you @funnell ! Your explanation helps a lot!

I just have two more questions:

1. Is it always safe to set hyperparameters = 0.1 for all modality types?

2. What is the mathematical explanation of "tolerance" in the fit!(model, tol=1e-5)?

[funnell]

Great I'm glad!

1. I've found that the model is reasonably stable across hyperparameter values given the number of mutations that I've worked with. I think 0.1 is a good starting point, but it would be a good idea to run it for a number of hyperparameter values and see how performance is affected. For these types of models, smaller values encourage sparser distributions. In short, it isn't safe to assume that 0.1 will work well in all cases.

2. This is the threshold for the relative change in average per-word log-likelihood, which is the metric being monitored for convergence. rel_diff = abs(ll[n-1] - ll[n]) / abs(ll[n]); converged = rel_diff < tol. The code is at the bottom of this file if you are curious:
   https://github.com/shahcompbio/MultiModalMuSig.jl/blob/master/src/common.jl

[WuyangFF95]

Thank you @funnell ! I think I can close my issue now.

[WuyangFF95]

Hi @funnell , I would also like to run LDA() function and CTM() function. Can you provide an example usage for LDA() and CTM()?

Specially, what are the default values for α, η and V in LDA function?

MultiModalMuSig.LDA
No documentation found.

Summary
≡≡≡≡≡≡≡≡≡

mutable struct LDA <: Any

Fields
≡≡≡≡≡≡≡≡

K :: Int64
D :: Int64
N :: Array{Int64,1}
V :: Int64
η :: Float64
λ :: Array{Float64,2}
β :: Array{Float64,2}
Elnβ :: Array{Float64,2}
α :: Float64
γ :: Array{Float64,2}
θ :: Array{Float64,2}
Elnθ :: Array{Float64,2}
ϕ :: Array{Array{Float64,2},1}
X :: Array{Array{Int64,2},1}
converged :: Bool
elbo :: Float64
ll :: Float64

[funnell]

Hi @WuyangFF95, have you tried the examples at the bottom of the readme?

• V is the vocabulary size (or number of mutation types), there is an LDA function that calculates this automatically from your data. That is the function used in the readme.
• α, η are dirichlet parameters, values < 1 promote sparsity. I've usually set them to 0.1 and at least with my testing it seems that the model isn't very sensitive to these values, although there are smarter ways to set these values than what I'm doing.

[WuyangFF95]

Thank you @funnell !

I would then set α, η= 0.1, and set V as number of mutation types.