Add Sankey diagram visualization functions

[sueoglu]

fixes #232
two new visualization functions sankey_diagram and sankey_diagram_time for creating Sankey diagrams to analyze patient flows and state transitions in EHR data, added comprehensive tests

sankey_diagram : relationships across observation columns
sankey_diagram_time: observation state transitions over time

Examples

• ep.pl.sankey_diagram()

import ehrapy as ep
import ehrdata as ed

edata = diabetes_130_fairlearn_sample_100()
ep.pl.sankey_diagram(edata, columns=["gender", "race"])

Output:

• ep.pl.sankey_diagram_time()

import ehrapy as ep
import ehrdata as ed

edata = ed.dt.ehrdata_blobs(base_timepoints=5, n_variables=1, n_observations=5, random_state=59)
edata.layers["tem_data] = edata.layers["tem_data].astype(int)
sankey_time = ep.pl.sankey_diagram_time(edata, var_name="feature_0", layer="tem_data", state_labels={-2: "no", -3: "mild", -4: "moderate", -5: "severe", -6: "critical"})

Output:

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[Zethson]

Thank you very much!

1. Don't forget add the function to our docs, please.
2. Could you please add previews to the PR description?
3. We should have a consistent plotting user interface where all have the same parameters and style like height, width etc. We should avoid kwargs where possible.
4. Great tests! We might need to use try -> finally because you're changing the plotting backend. If the test fails and the plotting backend is not reset, it could cause other tests to fail.

[Zethson]

@sueoglu FYI you have to ensure that you're not updating the submodule of the tutorials in this PR, please. Unless you're adding your new plotting functions somewhere of course but I don't think that we're there yet.

[eroell]

• Make self-contained examples in the first comment of this PR (currently, they don't run

I'm not sure how 2 columns are used in ep.pl.sankey_diagram_time:

import ehrdata as ed
import ehrapy as ep
edata = ed.dt.ehrdata_blobs(base_timepoints=5, n_variables=2, n_observations=5, random_state=59)
edata.layers["tem_data"] = edata.layers["tem_data"].astype(int)
state_labels = {-2: "no", -3: "mild", -4: "moderate", -5: "severe", -6: "critical"}
ep.pl.sankey_diagram_time(
    edata,
    columns=["feature_0", "feature_1"],
    layer="tem_data",
    state_labels=state_labels,
)

and

import ehrdata as ed
import ehrapy as ep
edata = ed.dt.ehrdata_blobs(base_timepoints=5, n_variables=2, n_observations=5, random_state=59)
edata.layers["tem_data"] = edata.layers["tem_data"].astype(int)
state_labels = {-2: "no", -3: "mild", -4: "moderate", -5: "severe", -6: "critical"}
ep.pl.sankey_diagram_time(
    edata,
    columns=["feature_0"],
    layer="tem_data",
    state_labels=state_labels,
)

Yield the same plots if I see this correctly, and I think only 1 variable being allowed makes sense, or do I misunderstand that? :)

[Zethson]

I'm very confident that we're very close to merging this now.

[Zethson]

edata.layers["tem_data] = edata.layers["tem_data].astype(int)

is there a way to circumvent this requirement? Like handling it internally or it working with any type here?

[sueoglu]

edata.layers["tem_data] = edata.layers["tem_data].astype(int)

is there a way to circumvent this requirement? Like handling it internally or it working with any type here?

For the time being, I did it with type casting so that we can have a working example and tests as ehrdata_blobs currently doesnt produce discrete states. But if the state labels in a given input could also be of other types I should also handle the conversion internally

[Zethson]

This is related to theislab/ehrdata#196 right? I'm fine with temporarily having this until we have a new ehrdata release but I feel like the plotting function might need to be more robust? Like sure - blobs looks like this but our users can do whatever they like.

WDYT?

[eroell]

This is related to theislab/ehrdata#196 right?

yes it is

I'm fine with temporarily having this until we have a new ehrdata release but I feel like the plotting function might need to be more robust?

If you have continuous values in a feature, then the sankey diagram is not the right way to plot it, no? If you'd want a sankey diagram of a continuous value, you need to bin your data, and I'd suggest users need to think about that and do the binning before calling this plotting function

[Zethson]

Yeah so I think we need to

1. Fail early and suggest a solution
2. Automatically bin

But I think that atm we do neither.

[eroell]

Yep - I'm in favor of 1

[eroell]

3 small points - when they are addressed, this looks good from my side!