From 096f0bc65f75954cd8191fddc8c4c9aff58534ad Mon Sep 17 00:00:00 2001 From: Daniel Weindl Date: Fri, 15 Dec 2023 18:37:13 +0100 Subject: [PATCH] Doc: Clean up visualization examples * Don't use deprecated `Problem.from_files` * Simplify by not loading all files separately * Fix grammar / typos * Add replicate plot example --- doc/example/example_visualization.ipynb | 159 ++++++++++-------- .../example_visualization_with_visspec.ipynb | 92 ++++------ ...xample_visualization_without_visspec.ipynb | 48 +++--- 3 files changed, 146 insertions(+), 153 deletions(-) diff --git a/doc/example/example_visualization.ipynb b/doc/example/example_visualization.ipynb index 113de75a..c7b5bba6 100644 --- a/doc/example/example_visualization.ipynb +++ b/doc/example/example_visualization.ipynb @@ -25,7 +25,10 @@ }, "outputs": [], "source": [ - "from petab.visualize import plot_with_vis_spec, plot_without_vis_spec" + "from petab.visualize import plot_problem, plot_without_vis_spec\n", + "from petab import Problem\n", + "from pathlib import Path\n", + "import petab" ] }, { @@ -38,12 +41,8 @@ }, "outputs": [], "source": [ - "folder = \"example_Isensee/\"\n", - "\n", - "data_file_path = folder + \"Isensee_measurementData.tsv\"\n", - "condition_file_path = folder + \"Isensee_experimentalCondition.tsv\"\n", - "visualization_file_path = folder + \"Isensee_visualizationSpecification.tsv\"\n", - "simulation_file_path = folder + \"Isensee_simulationData.tsv\"" + "example_dir = Path(\"example_Isensee\")\n", + "petab_problem = Problem.from_yaml(example_dir / \"Isensee.yaml\")" ] }, { @@ -52,12 +51,7 @@ "metadata": {}, "outputs": [], "source": [ - "ax = plot_with_vis_spec(\n", - " visualization_file_path,\n", - " condition_file_path,\n", - " data_file_path,\n", - " simulation_file_path,\n", - ")" + "plot_problem(petab_problem);" ] }, { @@ -73,9 +67,9 @@ "metadata": {}, "outputs": [], "source": [ - "ax_without_sim = plot_with_vis_spec(\n", - " visualization_file_path, condition_file_path, data_file_path\n", - ")" + "plot_problem(\n", + " petab_problem, simulations_df=example_dir / \"Isensee_simulationData.tsv\"\n", + ");" ] }, { @@ -91,49 +85,76 @@ "metadata": {}, "outputs": [], "source": [ - "ax = plot_with_vis_spec(\n", - " visualization_file_path,\n", - " condition_file_path,\n", - " simulations_df=simulation_file_path,\n", - ")" + "petab_problem_with_measurements = Problem.from_yaml(\n", + " example_dir / \"Isensee.yaml\"\n", + ")\n", + "petab_problem_with_measurements.measurement_df = None\n", + "plot_problem(\n", + " petab_problem_with_measurements,\n", + " simulations_df=example_dir / \"Isensee_simulationData.tsv\",\n", + ");" ] }, { "cell_type": "markdown", - "metadata": {}, + "source": [ + "If the measurement file contains replicates, the replicates can also be visualized individually:" + ], + "metadata": { + "collapsed": false + } + }, + { + "cell_type": "code", + "execution_count": null, + "outputs": [], + "source": [ + "petab_problem = Problem.from_yaml(example_dir / \"Isensee.yaml\")\n", + "petab_problem.visualization_df = petab.get_visualization_df(\n", + " example_dir / \"Isensee_visualizationSpecification_replicates.tsv\"\n", + ")\n", + "plot_problem(\n", + " petab_problem, simulations_df=example_dir / \"Isensee_simulationData.tsv\"\n", + ");" + ], + "metadata": { + "collapsed": false + } + }, + { + "cell_type": "markdown", "source": [ "If both measurements and simulated data are available, they can be visualized using scatter plot:" - ] + ], + "metadata": {} }, { "cell_type": "code", "execution_count": null, - "metadata": {}, "outputs": [], "source": [ - "visualization_file_scatterplots = (\n", - " folder + \"Isensee_visualizationSpecification_scatterplot.tsv\"\n", + "petab_problem_scatterplot = Problem.from_yaml(example_dir / \"Isensee.yaml\")\n", + "petab_problem_scatterplot.visualization_df = petab.get_visualization_df(\n", + " example_dir / \"Isensee_visualizationSpecification_scatterplot.tsv\"\n", ")\n", - "ax = plot_with_vis_spec(\n", - " visualization_file_scatterplots,\n", - " condition_file_path,\n", - " data_file_path,\n", - " simulation_file_path,\n", - ")" - ] + "plot_problem(\n", + " petab_problem_scatterplot,\n", + " simulations_df=example_dir / \"Isensee_simulationData.tsv\",\n", + ");" + ], + "metadata": {} }, { "cell_type": "markdown", - "metadata": {}, "source": [ "We can also call the plotting routine without the visualization specification file, but by passing a list of lists as `dataset_id_list`. Each sublist corresponds to a plot, and contains the datasetIds which should be plotted.\n", "In this simply structured plotting routine, the independent variable will always be time." - ] + ], + "metadata": {} }, { "cell_type": "code", "execution_count": null, - "metadata": {}, "outputs": [], "source": [ "datasets = [\n", @@ -147,21 +168,26 @@ " \"JI09_160201_Drg453-452_CycNuc__Sp8_Br_cAMPS_AM\",\n", " ],\n", "]\n", - "ax_without_sim = plot_without_vis_spec(\n", - " condition_file_path, datasets, \"dataset\", data_file_path\n", - ")" - ] + "petab_problem = Problem.from_yaml(example_dir / \"Isensee.yaml\")\n", + "plot_without_vis_spec(\n", + " petab_problem.condition_df,\n", + " measurements_df=petab_problem.measurement_df,\n", + " grouping_list=datasets,\n", + " group_by=\"dataset\",\n", + ");" + ], + "metadata": {} }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Let's look more closely at the plotting routines, if no visualization specification file is provided. If such a file is missing, PEtab needs to know how to group the data points. For this, three options can be used:\n", + "Let's look more closely at the plotting routines if no visualization specification file is provided. If such a file is missing, PEtab needs to know how to group the data points. For this, three options can be used:\n", " * dataset_id_list\n", " * sim_cond_id_lis\n", " * observable_id_list\n", "\n", - "Each of them is a list of lists. Again, each sublist is a plot and its content are either simulation condition IDs or observable IDs or the dataset IDs.\n", + "Each of them is a list of lists. Again, each sublist is a plot, and its content are either simulation condition IDs or observable IDs or the dataset IDs.\n", "\n", "We want to illustrate this functionality by using a simpler example, a model published in 2010 by Fujita et al." ] @@ -172,9 +198,8 @@ "metadata": {}, "outputs": [], "source": [ - "data_file_Fujita = \"example_Fujita/Fujita_measurementData.tsv\"\n", - "condition_file_Fujita = \"example_Fujita/Fujita_experimentalCondition.tsv\"\n", - "\n", + "example_dir_fujita = Path(\"example_Fujita\")\n", + "petab_problem_fujita = Problem.from_yaml(example_dir_fujita / \"Fujita.yaml\")\n", "# Plot 4 axes objects, plotting\n", "# - in the first window all observables of the simulation condition 'model1_data1'\n", "# - in the second window all observables of the simulation conditions 'model1_data2', 'model1_data3'\n", @@ -188,13 +213,13 @@ " [\"model1_data6\"],\n", "]\n", "\n", - "ax = plot_without_vis_spec(\n", - " condition_file_Fujita,\n", + "plot_without_vis_spec(\n", + " petab_problem_fujita.condition_df,\n", " sim_cond_id_list,\n", " \"simulation\",\n", - " data_file_Fujita,\n", + " petab_problem_fujita.measurement_df,\n", " plotted_noise=\"provided\",\n", - ")" + ");" ] }, { @@ -204,20 +229,20 @@ "outputs": [], "source": [ "# Plot 3 axes objects, plotting\n", - "# - in the first window the observable 'pS6_tot' for all simulation conditions\n", - "# - in the second window the observable 'pEGFR_tot' for all simulation conditions\n", - "# - in the third window the observable 'pAkt_tot' for all simulation conditions\n", + "# - in the first window, the observable 'pS6_tot' for all simulation conditions\n", + "# - in the second window, the observable 'pEGFR_tot' for all simulation conditions\n", + "# - in the third window, the observable 'pAkt_tot' for all simulation conditions\n", "\n", "observable_id_list = [[\"pS6_tot\"], [\"pEGFR_tot\"], [\"pAkt_tot\"]]\n", "\n", "\n", - "ax = plot_without_vis_spec(\n", - " condition_file_Fujita,\n", + "plot_without_vis_spec(\n", + " petab_problem_fujita.condition_df,\n", " observable_id_list,\n", " \"observable\",\n", - " data_file_Fujita,\n", + " petab_problem_fujita.measurement_df,\n", " plotted_noise=\"provided\",\n", - ")" + ");" ] }, { @@ -235,13 +260,13 @@ "observable_id_list = [[\"pS6_tot\"], [\"pEGFR_tot\"]]\n", "\n", "\n", - "ax = plot_without_vis_spec(\n", - " condition_file_Fujita,\n", + "plot_without_vis_spec(\n", + " petab_problem_fujita.condition_df,\n", " observable_id_list,\n", " \"observable\",\n", - " data_file_Fujita,\n", + " petab_problem_fujita.measurement_df,\n", " plotted_noise=\"provided\",\n", - ")" + ");" ] }, { @@ -257,7 +282,7 @@ "metadata": {}, "outputs": [], "source": [ - "simu_file_Fujita = \"example_Fujita/Fujita_simulatedData.tsv\"\n", + "simu_file_Fujita = example_dir_fujita / \"Fujita_simulatedData.tsv\"\n", "\n", "sim_cond_id_list = [\n", " [\"model1_data1\"],\n", @@ -266,13 +291,13 @@ " [\"model1_data6\"],\n", "]\n", "\n", - "ax = plot_without_vis_spec(\n", - " condition_file_Fujita,\n", + "plot_without_vis_spec(\n", + " petab_problem_fujita.condition_df,\n", " sim_cond_id_list,\n", " \"simulation\",\n", " simulations_df=simu_file_Fujita,\n", " plotted_noise=\"provided\",\n", - ")" + ");" ] }, { @@ -283,13 +308,13 @@ "source": [ "observable_id_list = [[\"pS6_tot\"], [\"pEGFR_tot\"], [\"pAkt_tot\"]]\n", "\n", - "ax = plot_without_vis_spec(\n", - " condition_file_Fujita,\n", + "plot_without_vis_spec(\n", + " petab_problem_fujita.condition_df,\n", " observable_id_list,\n", " \"observable\",\n", " simulations_df=simu_file_Fujita,\n", " plotted_noise=\"provided\",\n", - ")" + ");" ] } ], diff --git a/doc/example/example_visualization_with_visspec.ipynb b/doc/example/example_visualization_with_visspec.ipynb index 403fca1c..fc2949ee 100644 --- a/doc/example/example_visualization_with_visspec.ipynb +++ b/doc/example/example_visualization_with_visspec.ipynb @@ -7,7 +7,7 @@ "# Visualization with visualization specification file\n", "\n", "\n", - "As described in the [PEtab documentation](https://petab.readthedocs.io/en/latest/documentation_data_format.html), the visualization specification file (VS) is a tab-separated value file containing the specification of the visualization routines which come with the PEtab repository. In this example, we will discuss how to specify different visualization settings by means of the VS.\n", + "As described in the [PEtab documentation](https://petab.readthedocs.io/en/latest/documentation_data_format.html), the visualization specification file (VS) is a tab-separated value file containing the specification of the visualization routines which come with the PEtab repository. In this example, we will discuss how to specify different visualization settings by means of the VS.\n", "\n", "Let's plot measurements corresponding to the ones of the models from the Benchmark collection [Fujita_SciSignal2010](https://github.com/Benchmarking-Initiative/Benchmark-Models-PEtab/tree/master/Benchmark-Models/Fujita_SciSignal2010)." ] @@ -18,13 +18,12 @@ "metadata": {}, "outputs": [], "source": [ + "from petab.visualize import plot_problem\n", + "from petab import Problem\n", + "from pathlib import Path\n", "import petab\n", - "from petab.visualize import plot_data_and_simulation\n", "\n", - "folder = \"example_Fujita/\"\n", - "data_file_path = folder + \"Fujita_measurementData.tsv\"\n", - "condition_file_path = folder + \"Fujita_experimentalCondition.tsv\"\n", - "observables_file_path = folder + \"Fujita_observables.tsv\"" + "example_dir = Path(\"example_Fujita\")" ] }, { @@ -40,22 +39,15 @@ "metadata": {}, "outputs": [], "source": [ - "visualization_file_path = folder + \"/visuSpecs/Fujita_visuSpec_empty.tsv\"\n", - "\n", - "pp = petab.Problem.from_files(\n", - " measurement_file=data_file_path,\n", - " condition_file=condition_file_path,\n", - " observable_files=observables_file_path,\n", - " visualization_files=visualization_file_path,\n", - ")\n", - "petab.visualize.plot_problem(petab_problem=pp);" + "petab_problem = Problem.from_yaml(example_dir / \"Fujita.yaml\")\n", + "petab.visualize.plot_problem(petab_problem);" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "First of all, let us create a visualization specification file with only mandatory columns. In fact, there is only one mandatory column: `plotId`.\n", + "First of all, let us create a visualization specification file with only mandatory columns. In fact, there is only one mandatory column: `plotId`.\n", "Resulting plot using the VS\n", "\n", "| plotId |\n", @@ -71,16 +63,11 @@ "metadata": {}, "outputs": [], "source": [ - "visualization_file_path = folder + \"/visuSpecs/Fujita_visuSpec_mandatory.tsv\"\n", - "\n", - "pp = petab.Problem.from_files(\n", - " measurement_file=data_file_path,\n", - " condition_file=condition_file_path,\n", - " observable_files=observables_file_path,\n", - " visualization_files=visualization_file_path,\n", + "petab_problem.visualization_df = petab.get_visualization_df(\n", + " example_dir / \"visuSpecs\" / \"Fujita_visuSpec_mandatory.tsv\"\n", ")\n", "\n", - "petab.visualize.plot_problem(petab_problem=pp);" + "petab.visualize.plot_problem(petab_problem);" ] }, { @@ -100,16 +87,11 @@ "metadata": {}, "outputs": [], "source": [ - "visualization_file_path = folder + \"/visuSpecs/Fujita_visuSpec_1.tsv\"\n", - "\n", - "pp = petab.Problem.from_files(\n", - " measurement_file=data_file_path,\n", - " condition_file=condition_file_path,\n", - " observable_files=observables_file_path,\n", - " visualization_files=visualization_file_path,\n", + "petab_problem.visualization_df = petab.get_visualization_df(\n", + " example_dir / \"visuSpecs\" / \"Fujita_visuSpec_1.tsv\"\n", ")\n", "\n", - "petab.visualize.plot_problem(petab_problem=pp);" + "petab.visualize.plot_problem(petab_problem);" ] }, { @@ -137,16 +119,11 @@ }, "outputs": [], "source": [ - "visualization_file_path = folder + \"/visuSpecs/Fujita_visuSpec_2.tsv\"\n", - "\n", - "pp = petab.Problem.from_files(\n", - " measurement_file=data_file_path,\n", - " condition_file=condition_file_path,\n", - " observable_files=observables_file_path,\n", - " visualization_files=visualization_file_path,\n", + "petab_problem.visualization_df = petab.get_visualization_df(\n", + " example_dir / \"visuSpecs\" / \"Fujita_visuSpec_2.tsv\"\n", ")\n", "\n", - "petab.visualize.plot_problem(petab_problem=pp);" + "petab.visualize.plot_problem(petab_problem);" ] }, { @@ -171,18 +148,11 @@ "metadata": {}, "outputs": [], "source": [ - "visualization_file_path = (\n", - " folder + \"/visuSpecs/Fujita_visuSpec_individual_datasets.tsv\"\n", - ")\n", - "\n", - "pp = petab.Problem.from_files(\n", - " measurement_file=data_file_path,\n", - " condition_file=condition_file_path,\n", - " observable_files=observables_file_path,\n", - " visualization_files=visualization_file_path,\n", + "petab_problem.visualization_df = petab.get_visualization_df(\n", + " example_dir / \"visuSpecs\" / \"Fujita_visuSpec_individual_datasets.tsv\"\n", ")\n", "\n", - "petab.visualize.plot_problem(petab_problem=pp);" + "petab.visualize.plot_problem(petab_problem);" ] }, { @@ -193,16 +163,11 @@ }, "outputs": [], "source": [ - "visualization_file_path = folder + \"/visuSpecs/Fujita_visuSpec_datasetIds.tsv\"\n", - "\n", - "pp = petab.Problem.from_files(\n", - " measurement_file=data_file_path,\n", - " condition_file=condition_file_path,\n", - " observable_files=observables_file_path,\n", - " visualization_files=visualization_file_path,\n", + "petab_problem.visualization_df = petab.get_visualization_df(\n", + " example_dir / \"visuSpecs\" / \"Fujita_visuSpec_datasetIds.tsv\"\n", ")\n", "\n", - "petab.visualize.plot_problem(petab_problem=pp);" + "petab.visualize.plot_problem(petab_problem);" ] }, { @@ -213,8 +178,17 @@ } }, "source": [ - "As you can see, with the VS file you have an opportunity to plot each dataset individually or groups of datasets. Refer to the [PEtab documentation](https://petab.readthedocs.io/en/latest/documentation_data_format.html) for descriptions of all possible settings. If you have any questions or encounter some problems, please create an issue. We will be happy to help!" + "As you can see, with the visualization file, you have an opportunity to plot each dataset individually or groups of datasets." ] + }, + { + "cell_type": "markdown", + "source": [ + "Refer to the [PEtab documentation](https://petab.readthedocs.io/en/latest/documentation_data_format.html) for descriptions of all possible settings. If you have any questions or encounter some problems, please create a GitHub [issue](https://github.com/PEtab-dev/libpetab-python/issues). We will be happy to help!" + ], + "metadata": { + "collapsed": false + } } ], "metadata": { diff --git a/doc/example/example_visualization_without_visspec.ipynb b/doc/example/example_visualization_without_visspec.ipynb index 5bbbbeb0..3e602707 100644 --- a/doc/example/example_visualization_without_visspec.ipynb +++ b/doc/example/example_visualization_without_visspec.ipynb @@ -11,7 +11,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "In this example let us consider some visualisation possibilities of PEtab. In particluar, let us focus on the options that do not require detailed specifications. If you want to have more control over what will be plotted, refer to this [example](https://github.com/PEtab-dev/PEtab/blob/pl_visualization/doc/example/example_visualization_with_visspec.ipynb), describing usage of the visualization table.\n", + "In this example, let us consider some visualization possibilities of PEtab. In particular, let us focus on the options that do not require detailed specifications. If you want to have more control over what will be plotted, refer to this [example](https://github.com/PEtab-dev/PEtab/blob/pl_visualization/doc/example/example_visualization_with_visspec.ipynb), describing usage of the visualization table.\n", "\n", "Let's plot measurements corresponding to the ones of the models from the Benchmark collection [Fujita_SciSignal2010](https://github.com/Benchmarking-Initiative/Benchmark-Models-PEtab/tree/master/Benchmark-Models/Fujita_SciSignal2010)." ] @@ -22,13 +22,13 @@ "metadata": {}, "outputs": [], "source": [ + "from pathlib import Path\n", + "\n", "import petab\n", + "from petab import Problem\n", "from petab.visualize import plot_data_and_simulation\n", "\n", - "folder = \"example_Fujita/\"\n", - "data_file_path = folder + \"Fujita_measurementData.tsv\"\n", - "condition_file_path = folder + \"Fujita_experimentalCondition.tsv\"\n", - "observables_file_path = folder + \"Fujita_observables.tsv\"" + "example_dir = Path(\"example_Fujita\")" ] }, { @@ -36,7 +36,7 @@ "metadata": {}, "source": [ "## Plotting PEtab problem directly\n", - "For plotting a PEtab problem directly you can use the `plot_problem()` function." + "For plotting a PEtab problem directly, you can use the `plot_problem()` function." ] }, { @@ -45,17 +45,11 @@ "metadata": {}, "outputs": [], "source": [ - "# load PEtab problem from files\n", - "pp = petab.Problem.from_files(\n", - " measurement_file=data_file_path,\n", - " condition_file=condition_file_path,\n", - " observable_files=observables_file_path,\n", - ")\n", - "# Alternatively, from yaml file\n", - "# pp = petab.Problem.from_yaml(folder + \"Fujita.yaml\")\n", + "# load PEtab problem\n", + "petab_problem = Problem.from_yaml(example_dir / \"Fujita.yaml\")\n", "\n", "# plot measurements\n", - "ax = petab.visualize.plot_problem(petab_problem=pp)" + "petab.visualize.plot_problem(petab_problem);" ] }, { @@ -64,7 +58,7 @@ "source": [ "As nothing was specified regarding what should be plotted, the defaults were used. Namely, it was assumed that measurements are time series data, and they were grouped by observables.\n", "\n", - "You can specify how many subplot there should be and what should be plotted on each of them. It can easily be done by providing `grouping_list`, which by default specifies, which observables should be plotted on a paricular plot. The value of `grouping_list` should be a list of lists, each sublist corresponds to a separate plot." + "You can specify how many subplots there should be and what should be plotted on each of them. It can easily be done by providing `grouping_list`, which by default specifies, which observables should be plotted on a particular plot. The value of `grouping_list` should be a list of lists, each sublist corresponds to a separate plot." ] }, { @@ -73,9 +67,9 @@ "metadata": {}, "outputs": [], "source": [ - "ax = petab.visualize.plot_problem(\n", - " petab_problem=pp, grouping_list=[[\"pEGFR_tot\"], [\"pAkt_tot\", \"pS6_tot\"]]\n", - ")" + "petab.visualize.plot_problem(\n", + " petab_problem, grouping_list=[[\"pEGFR_tot\"], [\"pAkt_tot\", \"pS6_tot\"]]\n", + ");" ] }, { @@ -91,22 +85,22 @@ "metadata": {}, "outputs": [], "source": [ - "ax = petab.visualize.plot_problem(\n", - " petab_problem=pp,\n", + "petab.visualize.plot_problem(\n", + " petab_problem,\n", " grouping_list=[\n", " [\"model1_data1\"],\n", " [\"model1_data2\", \"model1_data3\"],\n", " [\"model1_data4\", \"model1_data5\", \"model1_data6\"],\n", " ],\n", " group_by=\"simulation\",\n", - ")" + ");" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Finally, measurements can be grouped by datasetIds. " + "Finally, measurements can be grouped by datasetIds." ] }, { @@ -115,8 +109,8 @@ "metadata": {}, "outputs": [], "source": [ - "ax = petab.visualize.plot_problem(\n", - " petab_problem=pp,\n", + "petab.visualize.plot_problem(\n", + " petab_problem,\n", " grouping_list=[\n", " [\n", " \"model1_data1_pEGFR_tot\",\n", @@ -144,14 +138,14 @@ " ],\n", " ],\n", " group_by=\"dataset\",\n", - ")" + ");" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "To summarize, measurements can be grouped by observables, simulation conditions and datasets with the `plot_problem()` function. This can be specified by setting the value of `group_by` parameter to `'observable'` (default), `'simulation'` or `'dataset'` and by providing corresponding ids in `grouping_list`, which is a list of lists. Each sublist specifies a separate plot and its elements are either simulation condition IDs or observable IDs or the dataset IDs." + "To summarize, measurements can be grouped by observables, simulation conditions and datasets with the `plot_problem()` function. This can be specified by setting the value of `group_by` parameter to `'observable'` (default), `'simulation'` or `'dataset'` and by providing corresponding ids in `grouping_list`, which is a list of lists. Each sublist specifies a separate plot and its elements are either simulation condition IDs or observable IDs or the dataset IDs." ] } ],