Implementing new viscosity function to compute the elastic modulus

Question

Implementing new viscosity function to compute the elastic modulus

Closed this issue 2 years ago · 20 comments

We published updated functions how to compute the viscosity of the CellCarrier solutions (https://www.biorxiv.org/content/10.1101/2022.11.18.517048) and now it should be time to implement them in dclab. I already checked where this would come into effect and it would bascially just be a change to the get_viscosity function in dclab.features.emodulus.viscosity. Now we need to decide how to do this exactly:

overwrite the old functions with the new functions? (probably not what we want)
Add the new functions as new default but keep old function as legacy? (I would opt for this)
Default stays as is but new functions become available

The new functions look like this:

With the temperature in Kelvin and the shear rate in 1/s. The shear rate can be calculated from the flow rate, channel width and shear thinning exponent (this is hidden as term1 * term2 in the current implementation; lines 71-75).

What do you think?

Answer 1 · 2022-11-25T12:24:55.000Z

The problem with new defaults is the breaking change introduced to current analysis pipelines.

Do you already have a quantification on how these new curves would affect the analysis for e.g. a standard blood measurement?

Answer 2 · 2022-11-25T12:31:19.000Z

Ok, I see how changing the default creates problems with running projects.

I have not checked how changing the viscosity curve alone influences the Young's modulus. But is this necessary for adding it to dclab?

Answer 3 · 2022-11-25T12:37:11.000Z

Yes, it would be nice to have just a simple plot here in this issue (and them maybe also in the docs) to have a comparison (As we currently have e.g. for the different YM-LUTs).

Answer 4 · 2022-11-25T12:42:09.000Z

Ok. I can prepare a plot that shows how the viscosity for the different buffers changes, dependent on flow rate and channel size dependent on the model.

These changes then scale linearly with the resulting Young's modulus. So, every measurement gets affected in the same way by this change. Only if you want to compare measurements at different flow rates, these changes have an effect. This is different to changing the LUT because this affects every cell individually.

Answer 5 · 2022-12-09T09:37:36.000Z

I finally got around doing this. I compared the resulting viscosity curves of CellCarrier and CellCarrier B for typical flow rates and temperatures in 20 µm and 30 µm channels:

When we implement it, I can also add a brief description to the documentation about how to get the viscosity at a given flow rate, channel size and temperature because this is not discussed in the paper.

Answer 6 · 2022-12-09T09:37:45.000Z

How would you add it to the code? My suggestion is to extent KNOWN_MEDIA by two new options and name them CellCarrier 2022 and CellCarrierB 2022 and then add the viscosity calculation to ... emodulus.viscosity.get_viscosity(). Would this be enough to make the emodulus calculation work like this:

ds.config["calculation"]["emodulus lut"] = "HE-3D-FEM-22"
ds.config["calculation"]["emodulus medium"] = "CellCarrierB 2022"
ds.config["calculation"]["emodulus temperature"] = 25.0  # a guess

?

Answer 7 · 2022-12-09T19:10:19.000Z

Wow, those are huge differences. Since it's still the same medium, I would not change the "medium" key. Maybe it makes sense to accept strings for the "emodulus viscosity" key. I'm not sure yet what the best solution would be.

Answer 8 · 2022-12-09T22:48:08.000Z

Little correction here from my side. Had an error in the Herold-viscosity equation:

Answer 9 · 2022-12-19T22:08:11.000Z

Hey,
The manuscript is currently in review and will likely be accepted after we resubmit the revisions. I would like to mention, that the new model is implemented in dclab to compute the Young's modulus in RT-DC. What do you think? Realistic or too early?

Answer 10 · 2022-12-19T22:45:17.000Z

Hey, I think it is unlikely that I will have time to look into this any further before the end of January. But you could still mention that the model will be made available in dclab for user convenience.

Answer 11 · 2023-01-20T09:02:05.000Z

Hey,
Is there any progress on this issue?

Answer 12 · 2023-01-20T10:04:10.000Z

No, sorry. No progress so far.

Answer 13 · 2023-01-28T10:42:12.000Z

@felix-r could you please comment on the differences between the Herold and the Büyükurgancı models? I would like to add two or three sentences to the docs so users can make an informed decision about which one to choose.

Answer 14 · 2023-01-28T10:52:27.000Z

When we implement it, I can also add a brief description to the documentation about how to get the viscosity at a given flow rate, channel size and temperature because this is not discussed in the paper.

@felix-r The viscosity is normally computed from the data and metadata in the .rtdc file. So this should be implemented in dclab. Can you please share the corresponding code? As a reference, this is the function currently implemented in dclab: https://dclab.readthedocs.io/en/0.47.5/_modules/dclab/features/emodulus/viscosity.html

EDIT: found it: https://github.com/bbueyue/viscosity-calculator/blob/main/app.py#L136-L150

EDIT2: Please explain why the parameters in the viscosity calculator web app are different than the ones in the manuscript. To me it looks like the web app uses a generalized formula, but I am not sure.

Answer 15 · 2023-01-28T14:35:13.000Z

I am currently working on this at https://github.com/DC-analysis/dclab/tree/viscosity_model_buyukurganci_22, where I already refactored dclab such that it accepts the 'emodulus viscosity model' key in the calculation section of the configuration. The only thing missing now is the actual implementation of the viscosity computation and an update for the docs (already prepared as well in that branch).

Answer 16 · 2023-01-30T09:07:21.000Z

EDIT2: Please explain why the parameters in the viscosity calculator web app are different than the ones in the manuscript. To me it looks like the web app uses a generalized formula, but I am not sure.

That is something I wanted to explain in the documentation. A brief explanation why we don't use the numbers presented in the paper: The general formula for the viscosity is $\eta = K\cdot\dot\gamma^{n-1}$ where $K$ and $n$ are temperature dependent:
$n = \alpha\cdot T + \beta$
$K = A\cdot e^{\lambda/T}$.

It showed that the parameters $\alpha$ and $\lambda$ did not depend on buffer concentration and can be assumed as a material constant of MC in dissolved in PBS (Within error margins $\alpha$ and $\lambda$ are the same for all three buffers). So we decided to take the mean value of $\alpha$ and $\lambda$ of the three buffers to determine the temperature dependence of all buffers. When you change $\alpha$ and $\lambda$, this will also change $\beta$ and $K$ to fit the curve again.

If we would take the values as described in the manuscript, it can happen that under certain conditions, the 0.59% buffer has a lower viscosity than the 0.49% buffer. We never observed this and that's why we decided to take the averaging approach for the viscosity calculator and this is also the approach I would recommend to implement here.

In the docs I would write a description with some plots how we got these values.

Answer 17 · 2023-01-30T09:09:46.000Z

I am currently working on this at https://github.com/DC-analysis/dclab/tree/viscosity_model_buyukurganci_22, where I already refactored dclab such that it accepts the 'emodulus viscosity model' key in the calculation section of the configuration. The only thing missing now is the actual implementation of the viscosity computation and an update for the docs (already prepared as well in that branch).

I will have a look at this and prepare a pull request. Or do you want to handle the PR?

Answer 18 · 2023-01-30T12:09:54.000Z

I am currently working on this at https://github.com/DC-analysis/dclab/tree/viscosity_model_buyukurganci_22, where I already refactored dclab such that it accepts the 'emodulus viscosity model' key in the calculation section of the configuration. The only thing missing now is the actual implementation of the viscosity computation and an update for the docs (already prepared as well in that branch).

I will have a look at this and prepare a pull request. Or do you want to handle the PR?

Yes, please create a pull request for the viscosity_model_buyukurganci_22 branch (not for master).

Answer 19 · 2023-02-06T08:19:36.000Z

The article deriving the viscosity equations is now live on arxiv: https://arxiv.org/abs/2302.01664.

Answer 20 · 2023-02-07T15:18:27.000Z

TODO

Add an example code snippet reproducing one of the subfigures in this issue here
Make sure the default in the docs is now always the new viscosity model
Add test methods for the new model
Understand how shear rate is converted to flow rate in the old and new models
Wait until the third version of the arxiv manuscript is online and compare the formulas