diff --git a/.github/workflows/build_environments.yml b/.github/workflows/build_environments.yml
index 29a3a0b1..eb006761 100644
--- a/.github/workflows/build_environments.yml
+++ b/.github/workflows/build_environments.yml
@@ -33,6 +33,7 @@ jobs:
"jupyter-book/surface_protein/surface_protein.yml",
"jupyter-book/air_repertoire/air_repertoire.yml",
"jupyter-book/multimodal_integration/multimodal_integration.yml",
+ "jupyter-book/deconvolution/bulk_deconvolution.yml",
]
steps:
- uses: actions/checkout@v7
diff --git a/jupyter-book/deconvolution/bulk_deconvolution.bib b/jupyter-book/deconvolution/bulk_deconvolution.bib
index 0d0e1142..946f441b 100644
--- a/jupyter-book/deconvolution/bulk_deconvolution.bib
+++ b/jupyter-book/deconvolution/bulk_deconvolution.bib
@@ -325,6 +325,23 @@ @Article{bd:Cobos2020
url={https://doi.org/10.1038/s41467-020-19015-1}
}
+
+@article{bd:Cobos2023,
+ title = {Effective methods for bulk {RNA}-seq deconvolution using {scnRNA}-seq transcriptomes},
+ volume = {24},
+ issn = {1474-760X},
+ url = {https://genomebiology.biomedcentral.com/articles/10.1186/s13059-023-03016-6},
+ doi = {10.1186/s13059-023-03016-6},
+ language = {en},
+ number = {1},
+ urldate = {2026-10-22},
+ journal = {Genome Biology},
+ author = {Cobos, Francisco Avila and Panah, Mohammad Javad Najaf and Epps, Jessica and Long, Xiaochen and Man, Tsz-Kwong and Chiu, Hua-Sheng and Chomsky, Elad and Kiner, Evgeny and Krueger, Michael J. and Di Bernardo, Diego and Voloch, Luis and Molenaar, Jan and Van Hooff, Sander R. and Westermann, Frank and Jansky, Selina and Redell, Michele L. and Mestdagh, Pieter and Sumazin, Pavel},
+ month = aug,
+ year = {2023},
+ pages = {177},
+}
+
@Article{bd:WangXuran2019,
author={Wang, Xuran
and Park, Jihwan
@@ -459,3 +476,163 @@ @article{bd:Dong2020
eprint = {https://academic.oup.com/bib/article-pdf/22/1/416/35934954/bbz166.pdf},
}
+@article{bd:Dietrich2026,
+ title = {omnideconv: a unifying framework for using and benchmarking single-cell-informed deconvolution of bulk {RNA}-seq data},
+ volume = {27},
+ issn = {1474-760X},
+ shorttitle = {omnideconv},
+ url = {https://link.springer.com/10.1186/s13059-026-03955-w},
+ doi = {10.1186/s13059-026-03955-w},
+ language = {en},
+ number = {1},
+ urldate = {2026-10-23},
+ journal = {Genome Biology},
+ author = {Dietrich, Alexander and Merotto, Lorenzo and Pelz, Konstantin and Eder, Bernhard and Zackl, Constantin and Reinisch, Katharina and Edenhofer, Frank and Marini, Federico and Sturm, Gregor and List, Markus and Finotello, Francesca},
+ month = jan,
+ year = {2026},
+ pages = {6},
+}
+
+
+@article{bd:Sturm2019,
+ title = {Comprehensive evaluation of transcriptome-based cell-type quantification methods for immuno-oncology},
+ volume = {35},
+ copyright = {http://creativecommons.org/licenses/by-nc/4.0/},
+ issn = {1367-4803, 1367-4811},
+ url = {https://academic.oup.com/bioinformatics/article/35/14/i436/5529146},
+ doi = {10.1093/bioinformatics/btz363},
+ language = {en},
+ number = {14},
+ urldate = {2026-10-23},
+ journal = {Bioinformatics},
+ author = {Sturm, Gregor and Finotello, Francesca and Petitprez, Florent and Zhang, Jitao David and Baumbach, Jan and Fridman, Wolf H and List, Markus and Aneichyk, Tatsiana},
+ month = jul,
+ year = {2019},
+ pages = {i436--i445},
+}
+
+
+@article{bd:Tran2023,
+ title = {Performance of tumour microenvironment deconvolution methods in breast cancer using single-cell simulated bulk mixtures},
+ volume = {14},
+ copyright = {2023 The Author(s)},
+ issn = {2041-1723},
+ url = {https://www.nature.com/articles/s41467-023-41385-5},
+ doi = {10.1038/s41467-023-41385-5},
+ language = {en},
+ number = {1},
+ urldate = {2026-10-23},
+ journal = {Nature Communications},
+ publisher = {Nature Publishing Group},
+ author = {Tran, Khoa A. and Addala, Venkateswar and Johnston, Rebecca L. and Lovell, David and Bradley, Andrew and Koufariotis, Lambros T. and Wood, Scott and Wu, Sunny Z. and Roden, Daniel and Al-Eryani, Ghamdan and Swarbrick, Alexander and Williams, Elizabeth D. and Pearson, John V. and Kondrashova, Olga and Waddell, Nicola},
+ month = sep,
+ year = {2023},
+ keywords = {Breast cancer, Cancer microenvironment, Computational models, Software, Tumour heterogeneity},
+ pages = {5758},
+}
+
+
+@article{bd:Amblard2025,
+ title = {A robust workflow to benchmark deconvolution of multi-omic data},
+ volume = {26},
+ issn = {1474-760X},
+ url = {https://doi.org/10.1186/s13059-025-03897-9},
+ doi = {10.1186/s13059-025-03897-9},
+ language = {en},
+ number = {1},
+ urldate = {2026-10-23},
+ journal = {Genome Biology},
+ author = {Amblard, Elise and Bertrand, Vadim and Barbot, Hugo and Martin Peña, Luis and Karkar, Slim and Chuffart, Florent and Ayadi, Mira and Baurès, Aurélia and Armenoult, Lucile and Kermezli, Yasmina and Causeur, David and Cros, Jérôme and Blum, Yuna and Richard, Magali},
+ month = dec,
+ year = {2025},
+ pages = {429},
+}
+
+@article{bd:Jew2020,
+ title = {Accurate estimation of cell composition in bulk expression through robust integration of single-cell information},
+ volume = {11},
+ copyright = {2020 The Author(s)},
+ issn = {2041-1723},
+ url = {https://www.nature.com/articles/s41467-020-15816-6},
+ doi = {10.1038/s41467-020-15816-6},
+ language = {en},
+ number = {1},
+ urldate = {2026-10-23},
+ journal = {Nature Communications},
+ publisher = {Nature Publishing Group},
+ author = {Jew, Brandon and Alvarez, Marcus and Rahmani, Elior and Miao, Zong and Ko, Arthur and Garske, Kristina M. and Sul, Jae Hoon and Pietiläinen, Kirsi H. and Pajukanta, Päivi and Halperin, Eran},
+ month = apr,
+ year = {2020},
+ keywords = {Computational biology and bioinformatics, Gene expression, RNA sequencing},
+ pages = {1971},
+}
+
+@article{bd:Chu2022,
+ title = {Cell type and gene expression deconvolution with {BayesPrism} enables {Bayesian} integrative analysis across bulk and single-cell {RNA} sequencing in oncology},
+ volume = {3},
+ copyright = {2022 The Author(s), under exclusive licence to Springer Nature America, Inc.},
+ issn = {2662-1347},
+ url = {https://www.nature.com/articles/s43018-022-00356-3},
+ doi = {10.1038/s43018-022-00356-3},
+ abstract = {Inferring single-cell compositions and their contributions to global gene expression changes from bulk RNA sequencing (RNA-seq) datasets is a major challenge in oncology. Here we develop Bayesian cell proportion reconstruction inferred using statistical marginalization (BayesPrism), a Bayesian method to predict cellular composition and gene expression in individual cell types from bulk RNA-seq, using patient-derived, scRNA-seq as prior information. We conduct integrative analyses in primary glioblastoma, head and neck squamous cell carcinoma and skin cutaneous melanoma to correlate cell type composition with clinical outcomes across tumor types, and explore spatial heterogeneity in malignant and nonmalignant cell states. We refine current cancer subtypes using gene expression annotation after exclusion of confounding nonmalignant cells. Finally, we identify genes whose expression in malignant cells correlates with macrophage infiltration, T cells, fibroblasts and endothelial cells across multiple tumor types. Our work introduces a new lens to accurately infer cellular composition and expression in large cohorts of bulk RNA-seq data.},
+ language = {en},
+ number = {4},
+ urldate = {2026-10-23},
+ journal = {Nature Cancer},
+ publisher = {Nature Publishing Group},
+ author = {Chu, Tinyi and Wang, Zhong and Pe’er, Dana and Danko, Charles G.},
+ month = apr,
+ year = {2022},
+ keywords = {Cancer, Cancer genomics, Statistical methods},
+ pages = {505--517},
+}
+
+@misc{bd:Eder2026,
+ title = {Rectangle: robust and scalable multiscale deconvolution informed by single-cell {RNA} sequencing data},
+ copyright = {http://creativecommons.org/licenses/by/4.0/},
+ shorttitle = {Rectangle},
+ url = {http://biorxiv.org/lookup/doi/10.64898/2026.07.07.736950},
+ doi = {10.64898/2026.07.07.736950},
+ abstract = {Abstract
+ Bulk RNA-seq enables effective profiling of large cohorts and complex experimental designs, but current single-cell-informed deconvolution methods incompletely resolve closely related cell phenotypes, do not scale efficiently to large single-cell datasets, or fail to account for cellular content not represented in the reference. Here, we present Rectangle, an scverse Python framework for single-cell-informed deconvolution of bulk RNA-seq data. Rectangle combines multiscale deconvolution, capturing cellular composition across multiple resolution levels, with explicit modeling of unknown cellular content. In a diverse, cross-method benchmark, Rectangle achieved consistently strong performance across all evaluated metrics, demonstrating high accuracy, high resolution, low spillover, strong scalability and efficiency, and robustness to unknown cellular content. By bridging the resolution of single-cell transcriptomics with the scale and cost-efficiency of bulk RNA-seq, Rectangle enables cell-type and cell-state profiling at scale, supporting population-scale cellular biomarker discovery and tracking of cellular dynamics in settings impractical for comprehensive single-cell sequencing.},
+ language = {en},
+ urldate = {2026-10-23},
+ author = {Eder, Bernhard and Rigato, Irene and Dietrich, Alexander and Merotto, Lorenzo and Sturm, Gregor and Treis, Tim and List, Markus and Theis, Fabian J. and Finotello, Francesca},
+ month = jul,
+ year = {2026},
+}
+
+@article{bd:Becht2016,
+ title = {Estimating the population abundance of tissue-infiltrating immune and stromal cell populations using gene expression},
+ volume = {17},
+ issn = {1474-760X},
+ url = {https://doi.org/10.1186/s13059-016-1070-5},
+ doi = {10.1186/s13059-016-1070-5},
+ abstract = {We introduce the Microenvironment Cell Populations-counter (MCP-counter) method, which allows the robust quantification of the absolute abundance of eight immune and two stromal cell populations in heterogeneous tissues from transcriptomic data. We present in vitro mRNA mixture and ex vivo immunohistochemical data that quantitatively support the validity of our method’s estimates. Additionally, we demonstrate that MCP-counter overcomes several limitations or weaknesses of previously proposed computational approaches. MCP-counter is applied to draw a global picture of immune infiltrates across human healthy tissues and non-hematopoietic human tumors and recapitulates microenvironment-based patient stratifications associated with overall survival in lung adenocarcinoma and colorectal and breast cancer.},
+ language = {en},
+ number = {1},
+ urldate = {2026-10-23},
+ journal = {Genome Biology},
+ author = {Becht, Etienne and Giraldo, Nicolas A. and Lacroix, Laetitia and Buttard, Bénédicte and Elarouci, Nabila and Petitprez, Florent and Selves, Janick and Laurent-Puig, Pierre and Sautès-Fridman, Catherine and Fridman, Wolf H. and de Reyniès, Aurélien},
+ month = oct,
+ year = {2016},
+ keywords = {Deconvolution, Gene signatures, Transcriptomic markers, Tumor microenvironment},
+ pages = {218},
+}
+
+
+@article{bd:Schulte-Schrepping2020,
+ title = {Severe {COVID}-19 {Is} {Marked} by a {Dysregulated} {Myeloid} {Cell} {Compartment}},
+ volume = {182},
+ issn = {00928674},
+ url = {https://linkinghub.elsevier.com/retrieve/pii/S0092867420309922},
+ doi = {10.1016/j.cell.2020.08.001},
+ language = {en},
+ number = {6},
+ urldate = {2026-11-05},
+ journal = {Cell},
+ author = {Schulte-Schrepping, Jonas and Reusch, Nico and Paclik, Daniela and Baßler, Kevin and Schlickeiser, Stephan and Zhang, Bowen and Krämer, Benjamin and Krammer, Tobias and Brumhard, Sophia and Bonaguro, Lorenzo and De Domenico, Elena and Wendisch, Daniel and Grasshoff, Martin and Kapellos, Theodore S. and Beckstette, Michael and Pecht, Tal and Saglam, Adem and Dietrich, Oliver and Mei, Henrik E. and Schulz, Axel R. and Conrad, Claudia and Kunkel, Désirée and Vafadarnejad, Ehsan and Xu, Cheng-Jian and Horne, Arik and Herbert, Miriam and Drews, Anna and Thibeault, Charlotte and Pfeiffer, Moritz and Hippenstiel, Stefan and Hocke, Andreas and Müller-Redetzky, Holger and Heim, Katrin-Moira and Machleidt, Felix and Uhrig, Alexander and Bosquillon De Jarcy, Laure and Jürgens, Linda and Stegemann, Miriam and Glösenkamp, Christoph R. and Volk, Hans-Dieter and Goffinet, Christine and Landthaler, Markus and Wyler, Emanuel and Georg, Philipp and Schneider, Maria and Dang-Heine, Chantip and Neuwinger, Nick and Kappert, Kai and Tauber, Rudolf and Corman, Victor and Raabe, Jan and Kaiser, Kim Melanie and Vinh, Michael To and Rieke, Gereon and Meisel, Christian and Ulas, Thomas and Becker, Matthias and Geffers, Robert and Witzenrath, Martin and Drosten, Christian and Suttorp, Norbert and Von Kalle, Christof and Kurth, Florian and Händler, Kristian and Schultze, Joachim L. and Aschenbrenner, Anna C. and Li, Yang and Nattermann, Jacob and Sawitzki, Birgit and Saliba, Antoine-Emmanuel and Sander, Leif Erik and Angelov, Angel and Bals, Robert and Bartholomäus, Alexander and Becker, Anke and Bezdan, Daniela and Bonifacio, Ezio and Bork, Peer and Clavel, Thomas and Colome-Tatche, Maria and Diefenbach, Andreas and Dilthey, Alexander and Fischer, Nicole and Förstner, Konrad and Frick, Julia-Stefanie and Gagneur, Julien and Goesmann, Alexander and Hain, Torsten and Hummel, Michael and Janssen, Stefan and Kalinowski, Jörn and Kallies, René and Kehr, Birte and Keller, Andreas and Kim-Hellmuth, Sarah and Klein, Christoph and Kohlbacher, Oliver and Korbel, Jan O. and Kurth, Ingo and Landthaler, Markus and Li, Yang and Ludwig, Kerstin and Makarewicz, Oliwia and Marz, Manja and McHardy, Alice and Mertes, Christian and Nöthen, Markus and Nürnberg, Peter and Ohler, Uwe and Ossowski, Stephan and Overmann, Jörg and Peter, Silke and Pfeffer, Klaus and Poetsch, Anna R. and Pühler, Alfred and Rajewsky, Nikolaus and Ralser, Markus and Rieß, Olaf and Ripke, Stephan and Nunes Da Rocha, Ulisses and Rosenstiel, Philip and Saliba, Antoine-Emmanuel and Sander, Leif Erik and Sawitzki, Birgit and Schiffer, Philipp and Schulte, Eva-Christina and Schultze, Joachim L. and Sczyrba, Alexander and Stegle, Oliver and Stoye, Jens and Theis, Fabian and Vehreschild, Janne and Vogel, Jörg and Von Kleist, Max and Walker, Andreas and Walter, Jörn and Wieczorek, Dagmar and Ziebuhr, John},
+ month = sep,
+ year = {2020},
+ pages = {1419--1440.e23},
+}
\ No newline at end of file
diff --git a/jupyter-book/deconvolution/bulk_deconvolution.ipynb b/jupyter-book/deconvolution/bulk_deconvolution.ipynb
index 91a808fc..0ada94e8 100644
--- a/jupyter-book/deconvolution/bulk_deconvolution.ipynb
+++ b/jupyter-book/deconvolution/bulk_deconvolution.ipynb
@@ -9,6 +9,7 @@
"authors:\n",
" - name: Hananeh Aliee\n",
" - name: Amit Frishberg\n",
+ " - name: Seo H. Kim\n",
"---\n"
]
},
@@ -23,84 +24,217 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "_TL;DR We provide a brief overview over basic concepts of cell type deconvolution including input structure, data preprocessing and analysis of the output data._"
+ "(deconvolution-bulk-deconvolution-key-takeaway-1)=\n",
+ "## Introduction"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
- "(deconvolution-bulk-deconvolution-key-takeaway-1)=\n",
- "## Background"
+ "Imagine tasting a fruit smoothie and trying to work out how much banana, strawberry and mango went into it.\n",
+ "You can't see the individual pieces anymore, everything has been blended into one average flavor.\n",
+ "But if you know what each fruit tastes like on its own, you can make a good guess at the recipe.\n",
+ "\n",
+ "Bulk RNA-seq is the smoothie.\n",
+ "A tissue sample contains many different cell types, and sequencing it in bulk blends all their transcripts into one average expression profile.\n",
+ "Information about which cells contributed what is lost, which creates a real interpretation problem.\n",
+ "Let's say a gene goes up in diseased tissue compared to healthy tissue.\n",
+ "Two very different things could explain that {cite:p}`ShenOrr2013`:\n",
+ "\n",
+ "- each cell is expressing more of the gene, or\n",
+ "- the cells that express the gene have become more common.\n",
+ "\n",
+ "\n",
+ "From the bulk profile alone, you can't tell these apart.\n",
+ "**Cell type deconvolution** recovers the recipe.\n",
+ "Given a bulk expression profile and a description of what each cell type \"tastes like\" (its typical expression profile, the *reference*), deconvolution estimates how much each cell type contributes to the sample {cite:p}`bd:Cobos2020`."
]
},
{
- "attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
- "Studying differences in cell type compositions within a bulk tissue is important for several reasons. First, interactions between cell types play a major role in disease progression and recovery. Second, molecular patterns (such as gene expression and protein abundance) are often directly associated with the cell types compositions within the tissue. Understanding these compositions is crucial for studying the underlying molecular mechanisms of a biological condition such as disease. Third, uncovering disease-specific cell type patterns allow for better therapeutic targeting, providing an important clinical utility.\n",
- "\n",
- "Cell type deconvolution is a computational framework designed for inferring the compositions of cell populations within a bulk heterogeneous tissue {cite:p}`bd:Kuhn2012,bd:Schwartz2010,bd:Du2019,bd:Zaitsev2019`. As measuring these compositions experimentally is time-consuming and expensive, deconvolution methods allow large scale analysis of cell populations based on molecular data. Deconvolution methods usually follow linear regression defined as: \n",
- "\n",
- "$y = bX$ \n",
+ "### Why not just use single-cell data?\n",
"\n",
- "where, $y$ refers to a mixture of heterogeneous gene expression profile using common molecular pipelines (e.g. microarray or RNA-seq), $X$ is a signature matrix containing homogeneous cell type-specific profiles, and $b$ is the vector of cellular proportions in the mixture data inferred by the deconvolution method {cite:p}`bd:Baron2016`. To select an optimal deconvolution method suitable for the targeted biological conditions, the impact of several technical and biological factors should be considered including: the deconvolution method, reference data with missing or rare cell types, data normalization and the selection of features (markers).\n",
+ "You may start thinking: \"We've been talking about single-cell analysis the whole time, why are we going back to bulk now?\"\n",
+ "Although single-cell RNA-seq measures cell types directly, the bulk data already exists, and there is a lot of it.\n",
+ "Bulk RNA-seq is cheaper, easier to run in clinical settings, and decades of cohorts, biobanks and patient archives were profiled this way {cite:p}`bd:Cobos2023`.\n",
+ "Deconvolution lets you reuse a relatively small single-cell dataset as a reference to read cell composition out of thousands of bulk samples you could never afford to re-profile at single-cell resolution.\n",
"\n",
- "The signature matrix $X$, used to infer cellular compositions, reflects our best knowledge of cellular heterogeneity within the tissue and highly influences the success of the deconvolution process {cite:p}`bd:Aliee2021`. Originally, signature matrices were generated by profiling sorting cells from a heterogeneous tissue (using FACS or CyTOF), suffering from internal biases due to the pre-selection of cell type panels and the absence of appropriate antibodies {cite:p}`bd:Monaco2019,bd:Aran2017`. Today, these matrices are mainly generated as unbiased profiles using single cell technologies, allowing the generation of signature matrices across different organisms, tissues and biological conditions {cite:p}`bd:Aliee2021,bd:Newman2019`."
+ "Single-cell data has also changed deconvolution itself.\n",
+ "Reference profiles used to come from physically sorted cell populations, which covered only the cell types someone thought to sort for, and only those with good antibodies {cite:p}`bd:Monaco2019,bd:Aran2017`.\n",
+ "Single-cell atlases now provide references for many tissues, organisms and conditions without that pre-selection {cite:p}`bd:Aliee2021,bd:Newman2019`."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
- "## Approaches"
+ "### What makes it hard\n",
+ "\n",
+ "The smoothie picture also shows where deconvolution breaks:\n",
+ "\n",
+ "- **A missing ingredient.** If the smoothie contains kiwi but your list of fruits doesn't, its flavour gets wrongly attributed to whatever fruits *are* on the list.\n",
+ "A cell type absent from the reference distorts every other estimate {cite:p}`bd:Cobos2020, bd:Jin2021`.\n",
+ "- **Strong flavours dominate.** A small amount of a strong-tasting fruit can outweigh a lot of a mild one.\n",
+ "Likewise, cells differ in how much RNA they contain, so the estimated contribution to the *RNA* is not the same as the fraction of *cells* {cite:p}`bd:Monaco2019`.\n",
+ "\n",
+ "\n",
+ "These caveats are the reason for the practical recommendations that follow."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
- "Bulk deconvolution approaches can be divided into linear regression based methods, enrichment based methods, non-linear deep-learning based methods and others.\n",
+ "(deconvolution-bulk-deconvolution-key-takeaway-2)=\n",
+ "## What makes deconvolution work: four rules of thumb\n",
+ "\n",
+ "Going back to the smoothie: the quality of your recipe guess depends less on how clever you are and more on what you know about the fruit.\n",
+ "The same holds for deconvolution.\n",
+ "A large benchmark that systematically varied each step of the pipeline found that the choices that matter most are not the method itself but how the data and reference are prepared: keeping data on a linear scale, using a reference that covers every cell type in the mixture, and choosing marker genes sensibly {cite:p}`bd:Cobos2020`.\n",
+ "We restate these findings as four rules of thumb:\n",
+ "\n",
+ "1. Include every cell type present in the sample in the reference.\n",
+ "2. Use a resolution at which cell types are actually distinguishable.\n",
+ "3. Keep the data in linear scale, and don't rescale it.\n",
+ "4. Choose marker genes carefully.\n",
+ "\n",
+ ":::{dropdown} Four rules of thumb for deconvolution based on {cite:p}`bd:Cobos2020`\n",
+ "### 1. Include every cell type present in the sample in the reference\n",
+ "\n",
+ "If an ingredient is missing from your list, its flavour does not disappear: it gets blamed on whatever fruits *are* on the list.\n",
+ "Leaving a cell type out of the reference that is present in the bulk sample made results substantially worse, no matter which method, transformation or normalization was used.\n",
+ "When you cannot be sure your reference is complete, prefer methods that explicitly estimate an \"unknown\" or \"other\" fraction (see the method table below).\n",
"\n",
- "The most common type of cell type deconvolution methods are linear regression-based. These methods try to directly solve the $y = bX$ equation using different regularizations and relying on a relatively high number of features.\n",
+ "### 2. Use a resolution at which cell types are actually distinguishable\n",
"\n",
- "```{admonition} What the linear model assumes\n",
- ":class: dropdown\n",
+ "Banana and strawberry are easy to tell apart in a smoothie; two kinds of raspberry are not.\n",
+ "Closely related cell types share most of their expression, so estimates for one leak into the other.\n",
+ "Benchmarks observe exactly this: signal is wrongly assigned to cell types that are absent from a mixture, likely because related cell types share signatures or because their marker genes are not specific enough.\n",
+ "More recent benchmarks likewise find that accuracy depends on how similar the cell types in the reference are {cite:p}`bd:Dietrich2026`.\n",
+ "In practice, start with broad cell types (T cells, B cells, monocytes) and only split them further if the finer types have clearly distinct expression.\n",
"\n",
- "$y = bX$ treats a bulk sample as a weighted sum of cell type profiles, with $X$ one reference profile per cell type, $b$ the proportions to recover, and $y$ the measured mixture.\n",
+ "### 3. Keep the data in linear scale, and don't rescale it\n",
"\n",
- "The first assumption, that the expression of a tissue is the sum of the contributions of its cells, holds well enough for transcript counts.\n",
- "The second is where it usually breaks: the reference has to describe those cell types as they occur in your sample, and a cell type profiled in a healthy donor or on another platform need not express the same genes there.\n",
- "Read the proportions as conditioned on the reference you chose.\n",
+ "Mixing is additive: if a sample is 30% T cells and 70% monocytes, the T cells contribute 30% of the transcripts.\n",
+ "That additivity only holds for counts (or count-like values), not for log-transformed data, where adding two values no longer corresponds to mixing two samples.\n",
+ "Keeping the data in linear scale consistently gave the lowest errors, while log and variance-stabilizing transformations gave two- to four-fold higher median errors.\n",
+ "\n",
+ "The same logic applies to scaling.\n",
+ "Rescaling genes or samples into a fixed range (0 to 1, or z-scores) throws away the actual amounts that deconvolution relies on, like setting every smoothie's strongest flavour to \"maximum\".\n",
+ "In the benchmark, these scalings and quantile normalization performed poorly, while standard library-size normalizations mattered little for most methods.\n",
+ "\n",
+ "```{important}\n",
+ "**Do:** keep counts in linear scale and use a standard library-size normalization.\n",
+ "**Avoid:** log or variance-stabilizing transformation, row scaling, column min-max, column z-score and quantile normalization.\n",
"```\n",
- " Examples of such tools are **CIBERSORTx** {cite:p}`bd:Newman2019`, **MuSiC** {cite:p}`bd:WangXuran2019`, **dtangle** {cite:p}`bd:Hunt2018` and **DWLS** {cite:p}`bd:Tsoucas2019`.\n",
"\n",
- "Enrichment based tools on the other hand calculate an enrichment score for each cell type separately, based on a gene set that represents this cell type. The enrichment scores for all cell types are then combined and transformed to compositions by a method-specific transformation function. As these methods only consider a single cell type at a time, tend to provide meaningful insights in simple cases, but are less accurate when reference data includes many cell types. **xCell** {cite:p}`bd:Aran2017` is an example of an enrichment based tool.\n",
+ "### 4. Choose marker genes carefully\n",
"\n",
- "The third option pose non-linear deep learning methods that emerged with the promise of improving deconvolution accuracy, while still attempting to maintain high biological interpretability. It is still early to say whether these methods can be better than other types of methods. **Scaden** {cite:p}`bd:Menden2020` is an example of such a deep-learning based method."
+ "Not every fruit is useful for telling a recipe apart: water content tastes the same in all of them.\n",
+ "Genes expressed at similar levels in every cell type carry no information about composition and only add noise.\n",
+ "Marker selection was one of the three most influential factors for classical (non-single-cell) deconvolution methods.\n",
+ "A useful marker is not just high in its own cell type; it is clearly higher than in the *runner-up*, the cell type with the second-highest expression.\n",
+ "The benchmark recommends a stringent selection built on exactly this comparison, in line with earlier findings that markers work best when expressed mainly in one cell type {cite:p}`bd:Hunt2018` and when genes with a small fold change between the top two cell types are removed {cite:p}`bd:Monaco2019`.\n",
+ "Within such a marker set, using all markers worked best, and picking only a handful per cell type (e.g. the top two) could be worse than random for some methods.\n",
+ "Good marker genes are high in one cell type and low in the others; feature-selection tools such as AutoGeneS pick genes that make cell types as distinguishable as possible {cite:p}`bd:Aliee2021`.\n",
+ ":::"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
- "Bulk deconvolution methods have been benchmarked extensively and the results are overall quite consistent {cite:p}`ShenOrr2013,bd:Cobos2020,bd:Jin2021,bd:Nadel2021`. Methods using single-cell RNA-seq data show good performance whereas semi-supervised approaches show higher error rates. Failing to include cell types in the reference that are present in the bulk mixture lead to worse results in any case {cite:p}`bd:Cobos2020`. Cobos et al. recommend that (1) the input data should be in linear scale, (2) Avoid row scaling, column min-max, column z-score or quantile normalization, (3) regression bulk deconvolution methods like CIBERSORTx or FARDEEP {cite:p}`bd:Hao2019` perform well and if scRNA-seq data is available DWLS, MuSiC or SCDC {cite:p}`bd:Dong2020` should also be applied for result comparisons, (4) a stringent marker selection strategy that focuses on the differences between the first and second cell types with highest expression values should be used, (5) a comprehensive reference matrix that includes all relevant cell types that are present in the mixture should be used {cite:p}`bd:Cobos2020`.\n",
- "The effect of the normalization strategy is unclear with Li et al. {cite:p}`bd:Li2016` suggesting that it has a strong effect on the results which was not confirmed by Cobos et al. {cite:p}`bd:Cobos2020`."
+ "(deconvolution-bulk-deconvolution-key-takeaway-3)=\n",
+ "## What the benchmarks say\n",
+ "\n",
+ "Deconvolution methods have been compared many times, on immune cells {cite:p}`bd:Sturm2019`, on pseudo-bulk mixtures built from single-cell data {cite:p}`bd:Cobos2020`, under varied simulation settings {cite:p}`bd:Jin2021`, in tumours {cite:p}`bd:Tran2023`, on paired bulk and single-cell data {cite:p}`bd:Cobos2023`, and across transcriptomic and methylation data {cite:p}`bd:Amblard2025`.\n",
+ "\n",
+ "A few lessons hold across them:\n",
+ "\n",
+ "- **No method wins everywhere.** The most recent large benchmark of single-cell-informed methods found substantial differences in accuracy, scalability and robustness that depended on cell-type similarity, reference composition and where the data came from {cite:p}`bd:Dietrich2026`.\n",
+ "- **Single-cell references are competitive.** Methods that use scRNA-seq references performed comparably to the best classical methods, while semi-supervised approaches had higher errors {cite:p}`bd:Cobos2020`.\n",
+ "- **Fine-grained types are where methods diverge.** In breast tumours, most methods mistook normal epithelial cells for cancer cells as tumour purity rose; BayesPrism and DWLS made the fewest false calls and did best on granular immune lineages {cite:p}`bd:Tran2023`.\n",
+ "- **The reference matters as much as the method.** Profiling bulk and single-cell data from the same samples improved both single-cell preprocessing and deconvolution accuracy {cite:p}`bd:Cobos2023`.\n",
+ "\n",
+ "The practical takeaway: run more than one method, check whether they agree, and validate against any measured proportions you have (for example, blood counts or histology)."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
- "Since many bulk deconvolution tools, including the well-performing CIBERSORTx, are only available as web tools, we opt to demonstrate a use-case with MuSiC."
+ "## Method families\n",
+ "\n",
+ "Most methods differ in *how* they turn the reference and the bulk profile into proportions.\n",
+ "The table groups them by that idea; expand each family for details and examples.\n",
+ "\n",
+ "| Family | Core idea (smoothie version) | Needs a full reference? | Output | Examples |\n",
+ "|---|---|---|---|---|\n",
+ "| Regression | Find the mix of reference fruits whose blend tastes closest to the smoothie | Yes | Proportions | CIBERSORTx, MuSiC, DWLS, FARDEEP, Bisque, SCDC |\n",
+ "| Enrichment / marker scores | Score how strongly each fruit's signature flavour comes through, one fruit at a time | Marker lists only | Scores (not always proportions) | xCell, MCP-counter |\n",
+ "| Bayesian | Treat each fruit's taste as uncertain and infer the most probable recipe, plus how each fruit tasted in *this* smoothie | Yes (used as a prior) | Proportions + per-cell-type expression | BayesPrism |\n",
+ "| Deep learning | Train a model on thousands of smoothies with known recipes, then predict | Yes (to simulate training data) | Proportions | Scaden |\n",
+ "| Reference-free | Recover both the ingredients and the recipe from many smoothies at once | No | Proportions + inferred profiles | Linseed |\n",
+ "\n",
+ ":::{dropdown} Methods-Citations\n",
+ "Here are the citations for the examples in the table above:\n",
+ "\n",
+ "Regression:\n",
+ "- **CIBERSORTx** {cite:p}`bd:Newman2019`}\n",
+ "- **MuSiC** {cite:p}`bd:WangXuran2019`}\n",
+ "- **DWLS** {cite:p}`bd:Tsoucas2019`}\n",
+ "- **FARDEEP** {cite:p}`bd:Hao2019`}\n",
+ "- **Bisque** {cite:p}`bd:Jew2020`}\n",
+ "- **SCDC** {cite:p}`bd:Dong2020`}\n",
+ "- **dtangle** {cite:p}`bd:Hunt2018`}\n",
+ "- **SQUID** {cite:p}`bd:Cobos2023`}\n",
+ "\n",
+ "Enrichment / marker scores:\n",
+ "- **xCell** {cite:p}`bd:Aran2017`}\n",
+ "- **MCP-counter** {cite:p}`bd:Becht2016`}\n",
+ "\n",
+ "Bayesian:\n",
+ "- **BayesPrism** {cite:p}`bd:Chu2022`\n",
+ "\n",
+ "Deep learning:\n",
+ "- **Scaden** {cite:p}`bd:Menden2020`}\n",
+ "\n",
+ "Reference-free:\n",
+ "- **Linseed** {cite:p}`bd:Zaitsev2019`}\n",
+ ":::\n",
+ "\n",
+ ":::{dropdown} Strengths and weaknesses of method families\n",
+ "| Family | Strengths | Weaknesses |\n",
+ "|---|---|---|\n",
+ "| Regression | Interpretable and fast | Sensitive to missing cell types and to highly similar cell types |\n",
+ "| Enrichment / marker scores | Robust; need only marker lists | Scores are not proportions; accuracy drops when many related cell types are scored |\n",
+ "| Bayesian | Can model uncertainty and per-cell-type expression | Slower and more complex |\n",
+ "| Deep learning | Can learn complex relationships | Needs a lot of training data; may not generalize well |\n",
+ "| Reference-free | No reference needed | Needs many samples; components must be labelled as cell types afterwards |\n",
+ ":::"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
- "It is important to note that MuSiC requires multiple single-cell samples including the same cell types. In practice, our reference profile might not include more than a single sample or some cell types might be missing across the samples. In these cases, MuSiC fails and another deconvolution method should be selected. "
+ "Among the many available deconvolution tools, we use **Rectangle** {cite:p}`bd:Eder2026` to demonstrate a use case.\n",
+ "Rectangle is a Python framework from the scverse ecosystem that learns cell-type signatures directly from an annotated single-cell reference.\n",
+ "\n",
+ ":::{admonition} Input requirements\n",
+ ":class: note\n",
+ "\n",
+ "- **Single-cell reference:** an `AnnData` object with **unnormalized counts** (cells × genes) and cell-type labels in `adata.obs[\"cell_type\"]` (or another column, set with `cell_type_col`).\n",
+ "- **Bulk data:** a `pandas.DataFrame` with **samples as rows and genes as columns**, in **TPM**. Note that this is the transpose of the common genes × samples layout, so you may need `bulks.T`.\n",
+ "- **Gene names** must use the same naming scheme in both datasets (e.g. both gene symbols).\n",
+ "\n",
+ "Both inputs stay in linear scale, in line with rule 3.\n",
+ ":::\n",
+ "\n",
+ "The output is a samples × cell types table of estimated proportions, with an additional `Unknown` column."
]
},
{
@@ -114,7 +248,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "In the following use-case we deconvolve 49 bulk whole blood RNA-seq samples collected from 39 COVID-19 patients and 10 healthy controls {cite:p}`bd:Aschenbrenner2020` using MuSiC. As single-cell reference dataset we'll use whole blood single-cell RNA-seq data of patients with COVID-19 {cite:p}`de:Schulte-Schrepping2020`."
+ "In the following use case we deconvolve 49 bulk whole blood RNA-seq samples from 39 patients with COVID-19 and 10 healthy controls {cite:p}`bd:Aschenbrenner2020` using Rectangle {cite:p}`bd:Eder2026`.\n",
+ "As single-cell reference, we use whole blood scRNA-seq data of patients with COVID-19 and controls {cite:p}`bd:Schulte-Schrepping2020`.\n",
+ "For most of the patients, neutrophil and lymphocyte counts were measured in the clinic, which lets us check the estimates against an independent measurement."
]
},
{
@@ -127,139 +263,359 @@
{
"cell_type": "code",
"execution_count": 1,
- "metadata": {},
- "outputs": [],
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-09T12:26:01.402309Z",
+ "iopub.status.busy": "2026-11-09T12:26:01.402208Z",
+ "iopub.status.idle": "2026-11-09T12:26:05.641083Z",
+ "shell.execute_reply": "2026-11-09T12:26:05.640537Z"
+ },
+ "tags": [
+ "hide-output"
+ ]
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[92m→\u001b[0m connected lamindb: theislab/sc-best-practices\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[93m!\u001b[0m It looks like you are running jupyter lab but don't have jupyter-server module installed. Please install it via pip install jupyter-server\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[92m→\u001b[0m loaded Transform('HsJRsKmLcB2Q0002', key='bulk_deconvolution.ipynb'), started new Run('8POULixJNZAVUB4P') at 2026-11-09 12:26:05 UTC\n"
+ ]
+ }
+ ],
"source": [
- "import numpy as np\n",
+ "import lamindb as ln\n",
+ "import matplotlib.pyplot as plt\n",
"import pandas as pd\n",
+ "import rectanglepy as rectangle\n",
"import scanpy as sc\n",
- "import scipy as sci"
+ "import seaborn as sns\n",
+ "from scipy import stats\n",
+ "\n",
+ "ln.connect(\"theislab/sc-best-practices\")\n",
+ "\n",
+ "ln.track(\"HsJRsKmLcB2Q\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
- "### Loading Data"
+ "### Loading the data"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
- "We start by reading the single-cell and bulk data. We do not scale the data as it has been shown that deconvolution methods using scRNA-seq data as reference, perform best when applied to data in linear scale with improved accuracy after library size normalization {cite:p}`bd:Jin2021,bd:Cobos2020`. "
+ "All three datasets are stored in the lamindb instance of this book.\n",
+ "The bulk expression is already converted to TPM, with one row per sample and one column per gene, which is the layout Rectangle expects."
]
},
{
"cell_type": "code",
- "execution_count": 45,
- "metadata": {},
+ "execution_count": 2,
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-09T12:26:05.643314Z",
+ "iopub.status.busy": "2026-11-09T12:26:05.643109Z",
+ "iopub.status.idle": "2026-11-09T12:26:11.293337Z",
+ "shell.execute_reply": "2026-11-09T12:26:11.291431Z"
+ }
+ },
"outputs": [
{
"data": {
+ "text/html": [
+ "
"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "order = (\n",
+ " fractions.mean()\n",
+ " .sort_values(ascending=False)\n",
+ " .index.drop(\"Unknown\")\n",
+ " .append(pd.Index([\"Unknown\"]))\n",
+ ")\n",
+ "samples = metadata.sort_values(\"status\").index\n",
+ "colors = sns.color_palette(\"tab20\", len(order) - 1) + [(0.8, 0.8, 0.8)]\n",
+ "\n",
+ "ax = fractions.loc[samples, order].plot.bar(\n",
+ " stacked=True, width=0.9, figsize=(12, 4), color=colors\n",
+ ")\n",
+ "n_covid = (metadata[\"status\"] == \"covid\").sum()\n",
+ "ax.axvline(n_covid - 0.5, color=\"black\")\n",
+ "ax.set_xticks([])\n",
+ "ax.set_xlabel(\"COVID-19 (left) and healthy (right) samples\")\n",
+ "ax.set_ylabel(\"Estimated fraction\")\n",
+ "ax.legend(bbox_to_anchor=(1, 1), loc=\"upper left\", frameon=False)\n",
+ "plt.show()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Neutrophils make up the largest part of most patient samples.\n",
+ "Two other columns need a closer look.\n",
+ "\n",
+ "The `Megakaryocytes` cluster of the reference mostly captures platelets, fragments of megakaryocytes that circulate in large numbers in the blood.\n",
+ "Platelets far outnumber white blood cells but carry little RNA, so their estimated fraction depends strongly on the correction for RNA content.\n",
+ "Clinical blood counts, in contrast, only cover white blood cells.\n",
+ "\n",
+ "The `Unknown` column is the part of each sample that the reference does not explain.\n",
+ "Whole blood contains cell types that are missing from the single-cell reference, for example red blood cell precursors, which contribute globin transcripts to the bulk RNA.\n",
+ "Without an `Unknown` column, their expression would be assigned to the cell types in the reference (rule 1).\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Validating against blood counts"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "If the true proportions are known, we can check the estimates against them.\n",
+ "The patients' neutrophil and lymphocyte counts were measured in the clinic, for the healthy controls they are missing.\n",
+ "The counts are absolute numbers per mm³ of blood, while deconvolution estimates relative fractions, so we compare the share of neutrophils among neutrophils and lymphocytes.\n",
+ "This ratio is also unaffected by platelets and by the `Unknown` fraction, which the blood counts do not include."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 12,
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-09T12:26:57.356603Z",
+ "iopub.status.busy": "2026-11-09T12:26:57.356526Z",
+ "iopub.status.idle": "2026-11-09T12:26:57.415357Z",
+ "shell.execute_reply": "2026-11-09T12:26:57.414440Z"
+ }
+ },
+ "outputs": [
+ {
+ "name": "stdout",
"output_type": "stream",
"text": [
- "C:\\Users\\Shennor\\AppData\\Roaming\\Python\\Python38\\site-packages\\numpy\\lib\\function_base.py:2691: RuntimeWarning: invalid value encountered in true_divide\n",
- " c /= stddev[:, None]\n",
- "C:\\Users\\Shennor\\AppData\\Roaming\\Python\\Python38\\site-packages\\numpy\\lib\\function_base.py:2692: RuntimeWarning: invalid value encountered in true_divide\n",
- " c /= stddev[None, :]\n"
+ "Pearson r = 0.68 (p = 2.2e-05, n = 32 samples)\n"
]
},
{
"data": {
+ "image/png": "iVBORw0KGgoAAAANSUhEUgAAAjwAAAGxCAYAAABmyWwBAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjIsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvgI3uAAAAAAlwSFlzAAAPYQAAD2EBqD+naQAAcxhJREFUeJzt3XdYk+f+P/B32HtIZAmIA8WBIOIWqBMHKqjV2rraeqy189hh7TltT2t7tPPY+u2wtbWt1mO1iqi40bq1IijiFkUElCFIwobk/v3hjxwjwxBCAuH9ui6vy9zP8+T5JEby4R6fWyKEECAiIiIyYiaGDoCIiIioqTHhISIiIqPHhIeIiIiMHhMeIiIiMnpMeIiIiMjoMeEhIiIio8eEh4iIiIweEx4iIiIyemaGDsAQlEolsrKyYG9vD4lEYuhwiIiISANCCMjlcnh6esLEpGF9Nq0y4cnKyoK3t7ehwyAiIiIt3Lp1C15eXg26plUmPPb29gDuv2EODg4GjoaIiIg0IZPJ4O3trfoeb4hWmfBUD2M5ODgw4SEiImphtJmOwknLREREZPSY8BAREZHRY8JDRERERo8JDxERERk9JjxERERk9JjwEBERkdFjwkNERERGr1kkPLdv38aRI0dQWFio8TW3bt1CQkICZDJZE0ZGREREzUFFRUWjrjdowpOQkIApU6YgMDAQoaGhSEpKeuQ1ZWVlmDx5Mrp27YqZM2fC3d0dK1as0EO0REREpG9CCCQlJWH58uW4c+eO1s9j0IQnJSUF06ZNw8mTJzW+5v3338dff/2F1NRUXLx4EevWrcPLL7/coOcgIiKi5q+4uBgbNmzA1q1bUVpaisTERK2fy6BbS8yZMwcAkJGRofE1q1evxvPPPw8PDw8AQFRUFHr27InVq1ejf//+TREmERFRq1NYUoG8ogrIyirhYG0Oqa0FHG0s9Hb/K1euYOvWrSguLoaJiQmGDRuGHj16aP18LWovraysLGRnZ6NPnz5q7f369at3OKy8vBzl5eWqx5z3Q0REVLese6V4NzYF/h4O6O3thNuFZcixMYdPGxu0c7Zp0ntXVFRg9+7dqt6ctm3bYtKkSXB3d2/U93eLSnjy8/MBAC4uLmrtLi4uqmO1Wbp0Kd5///0mjY2IiMgYFJZU4N3YFDzRzwerj97A/+2/pjo2pLMLlk3qBa82TZf0nDt3TpXsDBgwAMOHD4eZWePTlWaxSktT5ubmAO5PXH5QaWkpLCzq7mZbvHgxCgsLVX9u3brVpHESERG1VHlFFfD3cMDqozdw9NpdtWNHrt3F4phzKCxp3Iqp+gQHByMwMBCzZs1CRESETpIdoIX18Hh7e8PExASZmZlq7ZmZmfDx8anzOktLS1haWjZ1eERERC2erKwSvb2d1Hp2HnT4ah7yiipqnc+jzbyfvLw8/Pnnn5gwYQIsLCwgkUgQFRWli5eiptknPNeuXYNcLkfv3r1hY2ODQYMGYevWrZgxYwaA+zO49+3bh3/961+GDZSIiMgIOFiZ43ZhWb3nyMsqa7Rl3SvFok3JOHw1T9UW5ifFssm94OlkXeN8IQROnTqFvXv3oqqqCnZ2dhg9enTjX0AdDJrw5OTk4MqVK8jNzQVwf9zOzMwMPj4+qh6bZcuW4cSJE0hJSQEAfPjhhxg5ciQWL16MgQMHYsWKFXB1dcW8efMM9jqIiIiMhdTOAtky83rPsbdSP15YUlEj2QGAQ1fz8NamZKyY3lutp0culyM2NhapqakAgI4dO2LQoEE6egW1M2jCc/r0aXz00UcAgMGDB+P333/H77//jmeeeQbPPPMMAMDPz0+tumJ4eDgOHDiAr7/+Gn/99RcCAgKwZs0a2NnZGeQ1EBERGRNHGwu0d7HBkM4uOPLQHB7gfq+N1E59mCqvqKJGslPt0ENDYOfPn0dcXBxKS0thZmaGESNGoF+/fpBIJLp/MQ+QCCFEk96hGZLJZHB0dERhYSEcHBwMHQ4REVGzk5FfgsUx52oMUX08uRc8HhqiSkovQPQ3x+p8ri0LBiHIxxnHjx/Hnj17AAAeHh6Ijo5G27ZtNY6pMd/fzX4ODxEREemfVxsb/N/03sgrqoC8rBL2VuaQ2tU+CdnBSrMhsJ49e+Lo0aMIDg5GeHg4TE1NmyT22jDhISIiolo52mhWXVlqZ4EwPykOPTSsZQolRrVTqIbA7O3t8dJLLxlk5XSLqsNDRETUWhSWVCA1pwhJ6QVIzS1q0to32t6/+py0u8X4YGJPhPlJVcecJSWY5nAF7vlncTv9uqrdUGVi2MNDRETUzDR0ibch7v/wOTYWpngnsjsWj+mKlKQEXEpMgrJSAVtbW70OXdWFk5Y5aZmIiJqRwpIKvPjfpFpXPYX5SWss8TbE/QHUeo6dpByRDhmwrigAAHTt2hXjx4+Hra2tTmLjpGUiIiIj0ZAl3oa6P4Aa5/ia5mOweRosKpQwMzfH2DFjEBQU1OTLzTXFhIeIiKgZkdVSxfhBtVU51vf9axsaUggTWEiUyFbY4qkpU9C7h2+TxKctTlomIiJqRjRd4m3I+1efY4n/JUe3lE7YW94ZOyv84d5WWtflBsOEh4iIqBmpXuJdm9qqHBvi/o4WwCRpDiZZpcAG/1u9laF0Qqhf2yaPURtMeIiIiJoRRxsLLJvcq0bSUV3luCnn72hy/6KCXKxf+zMci9NhJVHAy7RQ7zFqg6u0uEqLiIiaocKSCo2qHOvr/m1szHA24QQOHToEIQTs7e0xcvQ42Ejb6S1GrtIiIiIyMppWOdbH/e/evYtN69cjMzMTwP0tIsaOHQtr66avCaQrTHiIiIioXgkJCcjMzISVlRXGjh2LgIAAQ4fUYEx4iIiIqF7Dhg1DeXk5wsPD4ejoaOhwtMJJy0RERKTm4sWL2LBhA5RKJQDA3NwcEyZMaLHJDsAeHiIiIoOpnhgsK6uEg7U5pLaGnbdTXl6OXbt24cyZMwCAM2fOIDg42GDx6BITHiIiIgMw9AahD7t58yZiYmJQWFgIiUSCwYMHIzAwsNZzm1uipgkmPERERHpWWFJRI9kB7u9V9dam5CbfIPRBVVVVOHDgAI4dOwYAcHJyQnR0NHx8fGo9v7klapriHB4iIiI903SDTn3YunWrKtkJCgrC/Pnz60x2HpWoFZboL+6GYg8PERGRnhl6g9AHDR48GGlpaRg7diz8/f3rPdfQO7k3BhMeIiIiPTPkBqGFhYVIT09X1dJxc3PDyy+/DDOzR6cEzSlRaygmPERERHpWvUHnoVp6S5pqg1AhBM6dO4cdO3agsrISLi4u8PT0BACNkh3A8Du5Nwbn8BAREemZvjcILS0txaZNmxATE4Py8nJ4eHjAysqqwc9j6J3cG4Obh3LzUCIiMhB9bBCampqK2NhYyOVySCQShIeHIzQ0FCYm2vV5ZN0rxVubktV6p6oTNY8mXqXFzUOJiIhaoKbeIHTv3r2qFVguLi6Ijo5Gu3btGvWcnk7WWDG9t0F3ctcGEx4iIiIjVd0L0rdvX4wcORLm5rqZY2Pondy1wYSHiIjISBQUleFWdj4U5tZwsDZH155BaNeuHby8vAwdmsEx4SEiIjIQXW7RcCktCz//dyMqy0oRW94dVTBVVUAmJjxEREQGoastGoQQOHriFPbu3QNroYCpxBTOJqXIVdoZZKuK5orL0omIiPRMV1s0FBUVYf369YjfsxMmQoHbCntsKe+OXKWd2nPqc6uK5oo9PERERHqmiy0aLl26hG3btqGkpAQmJiY4Ue6J81VuACQ1zm2KCsgtbcd0JjxERER61tgtGoQQSExMRElJCdzc3BASHoEff7lQ5/m6roDcEndM55AWERGRnmm7RUN1rWCJRIIJEyYgLCwMc+fOhV/7dnqrgNxSd0xnwkNERKRnDd2iQaFQID4+Hlu3blW12dnZYejQoTAzM9PrVhWaDMc1RxzSIiIi0rPqBKWuLRoeTFByc3OxefNm3LlzBwAQEhJSa7VkfVVAbqk7pjPhISIiMoBHJShCCPz111/Yt28fqqqqYG1tjcjIyHq3htBHBeSWumM6Ex4iIiIDqStBkclkiI2NxfXr1wEAnTt3xoQJE2Bvb6/vEGuoHo47VMuwVnPeMd3gc3ji4uIQERGBoKAgzJw5U/WPW5eysjJ8/PHHGDZsGIKDg7FgwQLk5OToKVoiIqKmJYTAmjVrcP36dZiZmWHs2LF48sknm0WyA0Cv84V0SSKqp3wbwI4dOzBx4kQsXboUAwcOxH/+8x8cP34cKSkpcHZ2rvWa6OhonD9/Hv/5z38glUrx5ZdfIikpCUlJSbCystLovo3ZXp6IiKipXblyBYcOHUJUVBSk0tonNxtadR0efe6Y3pjvb4MmPP369UO3bt3wyy+/AAAqKirg7u6ON954A4sXL65x/q1bt+Dj44O4uDiMHTsWAFBZWQl3d3csXboU8+bN0+i+THiIiKg5uX79OioqKuDv769qE0JAIqlZRLA1a8z3t8GGtIqKipCQkIDRo0er2iwsLDBixAgcOHCg1mtkMhkAwMXFRdVmbm4OBwcHxMfHN23AREREOlZZWYldu3ZhzZo12LJlCwoLC1XHmOzolsESnoyMDAgh4OHhodbu7u6OjIyMWq/p0qULvL298Z///Afl5eUAgPXr1yMtLQ23bt2q817l5eWQyWRqf4iIiAzp9u3b+OGHH3Dy5EkAQM+ePWFt3TyrFBsDg63SUigUAO736jzI0tISVVVVtV5jbm6OzZs345lnnoFUKoW9vT18fX0xduxY5OXVXgQJAJYuXYr3339fd8ETERFpSalU4tixYzhw4ACUSiVsbW0xceJE+Pn5GTo0o2awhKd6WOrhRCUvL09tyOphISEhSE5Oxt27d1FaWgovLy+Eh4fD29u7zmsWL16MhQsXqh7LZLJ6zyciImoKCoUCv/76K9LT0wEA/v7+GD9+PGxsbAwcmfEz2JCWu7s7vLy8cOLECbX248ePIyQk5JHXu7i4wMvLC9nZ2Th+/LjaXKCHWVpawsHBQe0PERGRvpmamsLd3R0WFhaYOHEipk6dymRHTwxah+e5557DqlWrcPXqVQDATz/9hGvXruFvf/ub6px33nkHEyZMUD1es2YNUlNTAQD37t3D008/DX9/f8ycOVO/wRMREWmguLhYbe7oiBEj8PzzzyMoKIgTk/XIoJWW33rrLaSnp6Nnz55wdHREVVUVfv75Z/Tq1Ut1zu3bt9WKEXbr1g0TJkyAXC7H3bt3MXz4cOzZsweWlpaGeAlERER1unLlCrZu3QoXFxfMnj0bJiYmMDc3h5OTk6FDa3UMWoenmkwmw927d+Hl5QVzc/U9OO7cuYPS0lJ06NBBrT0zMxP29vZaDU+xDg8RETWliooK7N69G4mJiQCAtm3bYubMmc2mWnJL1Zjv72axl1Z982rc3d1rba9v8zQiIiJDycjIQExMDPLz8wEAAwYMwPDhw2Fm1iy+clstvvtEREQ6oFAocOjQIRw+fBhCCDg4OCAqKqrGCAUZBhMeIiIiHRBC4NKlSxBCoFevXhgzZozGezxS02PCQ0REBlW9CaWsrBIO1uaQ2jb9JpS6IoSAEAImJiYwMzPDpEmTkJeXhx49ehg6NHoIEx4iIjKYrHulWLQpGYev/q8IbZifFMsm94KnU/PeZkEulyM2Nhbe3t4IDw8HALi5ucHNzc3AkVFtDFqHh4iIWq/CkooayQ4AHLqah7c2JaOwpMJAkT3a+fPn8c033yA1NRXHjh1DaWmpoUOiR2APDxERGUReUUWNZKfaoat5yCuqaHZDW2VlZdi5cyeSk5MBAB4eHoiOjuamny0AEx4iIjIIWVllvcfljziub2lpadiyZQsKCwshkUgwZMgQhIeHw9TU1NChkQaY8BARkUE4WJnXe9z+EccbqqGTox8831JShZh161BVWQlnZ2dER0frfBPqljx5uyVgwkNERAYhtbNAmJ8Uh2oZ1grzk0Jqp7sv+4ZOjq7t/EiPzgj1Mkf0+HGwsNBtItKSJ2+3FJy0TEREBuFoY4Flk3shzE+q1h7mJ8XHk3vprHejoZOjC0sqsOiPsyi4kQJXkyJV+/bbtoi754nSKp2EpXV8pB328BARkcF4OlljxfTeyCuqgLysEvZW5pDa6XYop6GTo9OycmGXfhSdzYsgU1piS3l3KGBa5/mNHYpqiZO3WyImPEREZFCONk07V0XTydFCCCQnJ2N7XBzcTStRKUyQXOUOxUODIQ9OptbFUFRLm7zdUnFIi4iIjJomk6NLSkqwceNGbNmyBVWVlchW2CK2vDuuKtoCkNQ4H9DdUJS+J2+3Vkx4iIjIqFVPjq5NmJ8UlsoyfPvtt7h48SJMTEwwKDQcRT5DIBc198F6cDK1JkNRuohPl5O3WzMmPEREZNQeNTm6nZsLPD09IZVKMXfuXIwc9hiWTQl85GRqXQ1F6WvydmsnEUIIQwehbzKZDI6OjigsLISDg4OhwyEiIj2onlwsL6tEuewufD1d4dbm/ndAaWkpzMzMYG5uXuv5tU2mTs0pwvAvDtZ5v/iF4ejkaqdVfE0xedsYNOb7W+senpycHKxcuRKLFi1StR09ehRVVTper0dERKQDjjYW8HWxxr3rZ7F78zocOxivOmZtba2W7FSf38nVDkE+zujkalcj+dD1UNSj7keNo1XCk5iYiG7duuHrr7/GJ598omr/7bff8PPPP+sqNiIiIp25e/cuVq9ejYMHD0IIAYVCAYVCofXzcSiqZdFqSGvo0KEYO3Ys3njjDUgkElQ/xdmzZ/HUU08hJSVF54HqEoe0iIhaDyEETp8+jT179qCyshKWlpYYN24cAgICdPL8HIrSn8Z8f2uV8Dg4OCAzMxP29vYwMTGBUqkEABQXF8PZ2RkVFc27KiQTHiKi1qG4uBhbtmzBtWvXAAAdOnTAxIkT4ejoaODISBuN+f7WqvCgubk5ZDIZ7O3t1dovXrwIqbT28UwiIiJ9k0gkuHPnDkxNTTFixAj0798fEonk0ReS0dEq4Rk3bhzee+89rFy5UvXBuX79OubPn48JEyboNEAiIqKGqKyshJmZGSQSCWxsbDB58mTY2NjA1dXV0KGRAWk1afnzzz9HQkIC3NzcoFQq0a1bN3Tp0gUKhQJLly7VdYxEREQauXnzJr7++mucO3dO1ebr68tkh7Tr4Wnbti0SEhKwbds2JCQkQKlUIjg4GFFRUTWW9RERETW1qqoqHDhwAMeOHQMAHD9+HAEBARy+IhUWHuSkZSKiFi0nJwebN29GdnY2ACAoKAijR4+GpaWlgSMjXdPLpOU///xT4yd97LHHGhQEERFRQwkhcOLECcTHx0OhUMDGxgaRkZHo1q1bjXOrl47LyirhYG0OqS2Xjrc2Gic8Q4cO1fhJW2GnERER6VlWVhb27NkDAPDz88OECRNgZ1dzK4ese6U1djUP85Ni2eRe8HSy1lu8ZFgaJzyVlZptgkZERKQP7dq1w5AhQ+Dk5ITg4OBa5+sUllTUSHaA+7uZv7UpGSum925UTw97jloOjRMeMzOt5jcTERHpRGlpKfbs2YOwsDA4OzsDAIYPH17vNXlFFTWSnWqHruYhr6hC6wSFPUcti1ZZzK5du+o8ZmlpiY4dO6J9+/ZaB0VERPSg1NRUxMbGQi6X4969e5g1a5ZGK7BkZfWPTsgfcbwuTd1zRLqnVcITFRWF8vJy1eMH99MyNTWFQqHA0KFDsWnTJlUWTkRE1FCVlZXYt28f/vrrLwCAi4sLRowYofFycwer+kul2D/ieF2asueImoZWhQe/+uor9O3bF8eOHUNZWRlKS0tx9OhR9OnTBytWrMCZM2dQUlKCN998U9fxEhFRK5GVlYXvv/9elez07dsXzz33HNq1a6fxc0jtLGrsZl4tzE8KqZ12SUlT9RxR09GqDo+/vz+2bdsGPz8/tfYrV65g4sSJuHjxIs6dO4dx48YhPT1dZ8HqCuvwEBE1bzdu3MDatWuhVCphZ2eHiRMnonPnzlo9V9a9Ury1KRmHHppr8/HkXvDQcq5Nak4Rhn9xsM7j8QvD0cm15ooxahy9bx6alpZW606zjo6OSEtLA3C/lLdcLtfm6YmIqJXz9vZG27Zt4eLignHjxsHGxkbr5/J0ssaK6b2RV1QBeVkl7K3MIbVr3Gqq6p6jQ7UMazWm54iajlZDWkFBQXj99dfVEhq5XI7XXnsNQUFBAO6X9R40aJBOgiQiIuMmhMCFCxegUCgA3F8ZPGfOHEyZMqVRyU41RxsLdHK1Q5CPMzq52jV6fo2jjQWWTe5VY7isuueI83eaH616eL7//nuMHz8eHh4e6Nq1K4QQuHLlClxcXLBt2zYAQFJSEr744gudBktERManqKgI27Ztw5UrVxAeHq6q1m9lZWXYwB6hKXqOqOlolfD06tULV69eRUxMDC5evAiJRAJ/f39ER0fDwuL+P/SiRYs0eq6SkhLExcUhOzsbAQEBCA8Pf+Q1d+7cwf79+1FQUAAfHx9ERESo7ktERC3H5cuXsXXrVpSUlMDU1LTZJzkPc7RhgtNSGHTz0Nu3byMsLAy2trbo3bs34uLiMGrUKKxdu7bOazZt2oQZM2Zg2LBh8PX1xcGDB1FcXIzDhw/Dy8tLo/ty0jIRkWGVl5dj9+7dSEpKAgC4ubkhOjoabm5uBo6MmrPGfH9rnfDcuXMHiYmJyM/Pr3FsxowZGj3HrFmzkJKSguPHj8PS0hIpKSkIDAzEpk2bEBUVVes1AQEB6N+/P1atWgUAKCsrQ6dOnfDMM89gyZIlGt2XCQ8RkeFkZWXhjz/+QEFBAQBg0KBBGDp0KCv60yPpfZXWhg0bMHv2bACodbWWJgmPQqHA5s2b8dFHH8HS0hIA0LNnTwwZMgQbNmyoM+GxtLSEra2t6rG5uTksLCxgbc0y3kRELYGFhQXkcjkcHR0RFRUFX19fQ4dErYBWCc/bb7+NDz/8EAsXLtS42uXDbt26heLiYnTt2lWt3d/fX1VkqjYrV67E3Llz8be//Q3t27fHwYMHERISgpdeeqnOa8rLy9UqQ8tkMq1iJiIi7ZSUlKhWW0mlUkyfPh2enp4tbs4OtVxaLUvPzs7G888/r3WyA0C1pN3JyUmt3cnJqd76PQqFAgqFAunp6cjKysKdO3cAAEqlss5rli5dCkdHR9Ufb29vreMmIiLNCSFw8uRJLF++XK0QbceOHZnskF5plfAEBATgwoULjbpxdab/cG9LYWGh2pDVg6qqqhAdHY3Ro0dj9+7d+Oabb5CYmIiLFy/Wuyps8eLFKCwsVP25detWo2InIqJHk8lkWLt2LXbt2oXKykqcPXu2Se5TWFKB1JwiJKUXIDW3CIUlFU1yH2rZtBrSeuKJJ/Dkk0/i/fffR+fOnWv09ISEhDzyOdq3bw9LS0ukpqaqtaemptbYsqLa7du3kZWVhREjRqjazM3NERoaWu8wmKWlpWqeEBERNb2UlBTExcWhrKwMZmZmGDVqlEbfDQ2Vda+0xq7lYX5SLJvcC55abhtBxkmrVVqPGsrS9CknT56M7OxsHDp0CCYmJkhLS0OXLl2wevVqPPXUUwCAPXv2ICsrC3PmzIFCoYC9vT0WL16Md955R3Wvfv36oWPHjvj99981ui9XaRERNY3S0lLs3LkT586dAwB4enoiOjoaUmntG3g2RmFJBV78b1Ktu5aH+UmxYnpv1sgxMnpfpVW9lLCxPvnkEwwaNAijRo1Cv379sH79egwdOhRPPPGE6pwNGzbgxIkTmDNnDkxNTfHpp59i4cKFSE1NRceOHbFv3z6kpqbil19+0UlMRESkvStXruDcuXOQSCQICwtDaGgoTE1Nm+ReeUUVtSY7AHDoah7yiiqY8JCKVgnPwxONtdWpUyekpKTgv//9L7Kzs/Hvf/8bjz/+uNp/joiICHTr1k31+IUXXsBjjz2GvXv34u7du5g1axamTJmis5iIiEh7vXr1QlZWFgICAjQuBqstWVllvcfljzhOrYtBKy0bCoe0iIh04/bt29i/fz8mT56s91VXqTlFGP7FwTqPxy8MRydXOz1GRE2tMd/fWq3SKi0txT/+8Q906dIFVlZWMDMzU/tDRETGTalU4siRI1i1ahWuXbuG/fv36z0GqZ1Fjd3Kq4X5SSG143AW/Y9WCc8///lPxMXF4YMPPkB5eTn++OMPvPnmm7C0tMQ//vEPXcdIRETNSEFBAX7++WfEx8dDqVTC399fo42fdc3RxgLLJveqkfSE+Unx8eRenL9DarQa0vLx8UFcXBwCAgIgkUigVCohkUiwceNGLF++HEePHm2KWHWGQ1pERA0nhMCZM2ewa9cuVFRUwMLCAmPGjEFgYGCjCtE2VmFJBfKKKiAvq4S9lTmkdtrtYF79PLKySjhYm0Nqy53Qmxu9bx5qYmKCyspKmJqaws7ODhkZGXByckJxcTGkUilKS0sb+pR6xYSHiKjhjh8/jj179gC4/4tvVFQUnJ2dDRyVbrCeT8ug9zk8QgjVSio/Pz/s3r0bAPDXX3/VupkoERG1fIGBgXB0dMTw4cMxe/Zso0l2CksqaiQ7wP2l7W9tSmblZiOhVcLj4uKi+vvChQsxe/ZsBAUFYezYsZg/f77OgiMiIsOpqKjA6dOnVcVkbWxs8OKLL2LIkCEwMdHq66NZ0qSeD7V8Wi2pysv73wdj5syZ8PPzw4kTJ+Dv74/Ro0frLDgiIjKMjIwMxMTEID8/H2ZmZggMDAQAo1yJy3o+rYNWn9yePXsiJSVF9XjAgAEYMGBArceIiKjlUCgUOHToEA4fPgwhBBwcHIx+rqODlXm9x+0fcZxaBq0SnvPnz9farlAocPny5UYFREREhpGXl4fNmzfj9u3bAICAgACMHTtW7wUF9a26ns+hOvbkYj0f49CghOfIkSO1/h24X4Tq+PHjaN++vW4iIyIivTl79iy2b9+OqqoqWFlZYdy4cejZs6ehw9KL6no+b21KVkt6WM/HuDQo4QkNDa3178D9HdTbtWuH5cuX6yQwIqLmzNhqtjg4OKCqqgodO3bExIkTjX4Y62GeTtZYMb23Tur5UPPUoDo8ZWVlAACpVKo2cRlAi9pWgnV4iKgxjKVmy71799Q2Xk5PT4e3t7dBiwgS1UdvdXisrKxgZWWFoqIi1d+r/7SUZIeIqDGMoWZLWVkZYmJi8M033yA/P1/V7uPjw2SHjJZWhRRycnLw7bff1mj/9ttvkZub2+igiIiaq5ZesyUtLQ3fffcdkpOTUVVVhbS0NEOHRKQXWiU8r7zySq0VNp2dnfHqq682NiYiomarpdZsqaqqwp49e/DLL7+gsLAQzs7OePrppxEcHGzo0Ij0QqtxqB07duC7776r0T5mzBgsWLCg0UERETVXLbFmS3Z2NjZv3oycnBwAQHBwMCIiImBhwQm51HpolfBYWFggIyOjxr5Zt27dMqpy40RED2uJNVvOnz+PnJwc2NraYvz48ejatauhQyLSO62yk3HjxuGFF17AnTt3VG23b9/GggULMG7cOJ0FR0TU3FTXbAnzk6q1N7eaLQ8uwA0PD8fAgQPx/PPPM9mhVqtBy9Kr5eTkYPjw4bhy5Qr8/PwghMC1a9fQpUsXxMfHw9XVtSli1RkuSyeixqquw9PcarYIIZCcnIyzZ8/iqaeegqmpqaFDItKZxnx/azWk5erqitOnTyM2NhaJiYmQSCTo3bs3oqKiYG7e/MaviYh0zdGmeSQ4DyopKcH27dtx8eJFAEBSUhJCQkIMHFXzZWzFI6l+WvXwtHTs4SEiY3Pt2jXExsaiqKgIJiYmeOyxxzB48GDOq6yDsRSPbG30VnjwQTk5OVi5ciUWLVqkajt69Ciqqqq0fUoiImqgyspKxMXF4bfffkNRURGkUinmzp2L0NBQJjt1MIbikdRwWg1pJSYmYuTIkWjXrh3OnTuHjz/+GADw22+/4eLFi5g7d65OgyQiotpt27YN586dAwD0798fw4cP59SCR9CkeCSHtoyPVun/a6+9hrfeegvJyclq7c899xw3DyUi0qPw8HC4uLhg5syZGD16NJMdDbTU4pHUOFr18Jw+fRpbt24FALV9Vzp37owrV67oJjIiolZGk0m0d+/exY0bN1STkV1cXLBgwQIOXzVASyweSY2nVcJjbm4OmUwGe3t7tfaLFy9CKpXWcRUREdXlUZNohRA4ffo09uzZg8rKSrRt2xbt27cHACY7DdQSi0dS42ldePC9996DQqFQ9fBcv34d8+fPx4QJE3QaIBGRsXvUJNqsnHysW7cOcXFxqKysRIcOHeDk5GSYYI1ASykeSbql1bL03NxcjBw5EhkZGbh79y78/f1x9epVBAQEYP/+/bVuLNqccFk6ETUnqTlFGP7FwVqP+ZgUYKxjJsrLymBqaooRI0agf//+atMJSDvNtXgk1U3vhQfbtm2LhIQEbNu2DQkJCVAqlQgODmbhQSIiLdQ1iba/eTq6m+WgvAxwd3dHdHR0s69k35I0x+KR1HS0SngAwMzMDNHR0YiOjla1CSGwbt06PPnkkzoJjoioNahrEu1dpQ2EAHoG90P0uFHcJoKoERo8h6eyshLnzp1DQkKCWpHB+Ph49OnTB7Nnz9ZpgERExq56Eq0JlHCUlKrarylckOE+GCNHDGeyQ9RIDUp4Ll26BH9/f/Tq1Qt9+/ZFz549cevWLTzzzDMYMWIEOnbsiPPnzzdVrERERsnRxgJvhnvgCYeriLC8Agvc/2UyzK8tljwxmMMuzUxhSQVSc4qQlF6A1NwiVmZuIRo0pLVo0SL4+Phg5cqVAIAlS5Zg8ODBsLCwwJEjRzB48OAmCZKIyFgJIXDixAnEx8fDUqGAg7U1vhvfBe29vTmJthniHlwtV4NWabm6uuKvv/6Cr68vgPtL0Tt16oQzZ84gMDCwqWLUOa7SIqLmoLCwEFu2bEFaWhoAwM/PDxMmTICdnZ1hA6NaFZZU4MX/JtW6LUWYnxQrpvdmgtrE9LZKKzc3V5XsAECHDh0AAAEBAQ26KRFRayaEwLlz57Bjxw6Ul5fD3NwcERERCA4O5nLzZox7cLVsDV6lVVRUVKOtpKRE7TF/OyEiqt+VK1dQXl6Odu3aYdKkSWjTpo2hQ6JH4B5cLVuDE56Ht5OorU2LWoYoKyuDlZXVI88rLCys9fktLS1hbW248VNN9sAhotZNqVTCxMQEEokE48aNg6enJwYMGMCtIVoI7sHVsjUo4dm4caPOA3jvvffw5ZdfoqioCB06dMCKFSswevToOs/v0aOHWi+TEAIymQyvvPKKwXZq5yQ2IqpPZWUl9u3bB7lcjscffxwSiQTW1tYYNGiQoUOjBuAeXC1bgxKeKVOm6PTmK1aswPLlyxEXF4d+/frhs88+Q1RUFFJSUtC5c+dar8nIyFB7vGvXLowZMwZPPPGETmPT1KP2wOEkNqLWLSsrCzExMcjLu/8zIjMzE15eXgaOirRRvQfXW5uS1ZIe7sHVMmi1l5audOrUCVFRUfj8889Vbb6+vpgyZQo+++wzjZ7j8ccfx6VLl3Du3DmN76vLVVr17YEDAPELw9HJlXOaiFobpVKJI0eO4ODBg1AqlbCzs8PEiRPr/GWOWg7uwWU4et9LSxfy8vJw/fp1hIaGqrWHhYXh5MmTGj/H1q1bNU6OmgInsRHRw/Lz8xETE6Pqke7WrRsiIyNhY2Nj4MhIF7gHV8tksIQnJycHACCVStXaXV1dNU541qxZAxMTE8yYMaPe88rLy1FeXq56LJPJGhht3TiJjYgeJITA+vXrkZubC0tLS4wZMwa9evXicnMiAzP40gClUqn2uKqqSuMfDD/++COmTJkCZ2fnes9bunQpHB0dVX+8vb21jvdh1ZPYasNJbEStj0QiwdixY+Hr64v58+cjMDCQyU4tuD0D6ZtOe3h+/vlnDBkyRKMxak9PTwBAdna2WntOTo7qWH1OnjyJ8+fP45tvvnnkuYsXL8bChQtVj2Uymc6SHk5iI6JLly6hoqICvXr1AnB/LmL79u2Z6NSBK1vJEHQ6aVkikcDCwgIvvfSSRvNqAgICMHjwYHz33XcA7vf2eHp6Yt68efjggw8AAKWlpaiqqqpR62fevHk4ePAgLl++3OA4m2JrCU5iI2p9ysvLsXv3biQlJcHc3Bzz589nAcFH4PYM1BjNZtJyQUEBbty4gbi4OI3Of/vttzFnzhyEhoZi4MCB+PTTT1FeXo7nn39edc5LL72EEydOICUlRdVWXFyM9evX491339Vl+I3CSWxErUt6ejq2bNmCgoICAEDfvn25N58GuD0DGYpOEx4nJyf07t0bvXv31uj86dOno7S0FB9//DGys7MREBCA/fv3w8PDQ3WOjY1NjR8i27Ztg4WFBWbPnq3L8ImIHkmhUODPP//E0aNHIYSAo6MjoqKi1PYZpLpxZSsZSqOGtEpLS5GWloZu3brpMqYmx93SiUgbCoUCP/30E7KysgAAgYGBGD16tEbb4tB9rF1GjdGY72+tVmkVFRVhxowZsLOzQ/fu3VXtU6dOxenTp7V5SiKiZs/U1BSdOnWCtbU1Hn/8cURFRTHZaSCubCVD0SrhWbx4MTIzM3Hq1Cm19jlz5uD999/XSWBERM2BTCZDfn6+6nF4eDief/55tV/2SHPVK1sfTnq4spWamlZDWl5eXjh06BA6duwIiUSi2r08Pz8f7du3h1wu13mgusQhLSLSREpKCuLi4uDs7Ixnn30Wpqamhg7JaHBlK2lD76u08vLy4OrqCgBqdSZKS0thwK25iIh0orS0FDt37lTt0SeRSFBSUlKjPAZpjytbSd+0SniCgoKwY8cOTJ06VS3h+fLLL9G/f3+dBUdEpCvVPQqysko4WJtDalv7F+7169cRGxsLmUwGiUSCsLAwhIaGsneHqIXTKuH58MMPMWnSJBw7dgwA8PHHH2PXrl04evQo9u/fr9MAiYgaS5PKvlVVVYiPj8eJEycAAG3atEF0dDS8vLwMEjMR6ZZWk5ZHjBiB3bt348aNG3B3d8fy5cthY2ODgwcPYsiQIbqOkYhIa4UlFTWSHeB+kbu3NiWr9nAyMTFR7W7ep08fPPfcc0x2iIyIVj08a9euxYwZMxAbG6vreIiIdKq+yr6Hr+Yiu7AUjjYWMDExQVRUFO7evYsuXbroOUoiampa9fA8/fTTNXY5JyJqjuqq7GsnKcdoi8s4deyQqs3FxYXJDpGR0irh6dq1K86ePavrWIiIdM7ByvyhFoHOpnmIsjwPd9Mi3LxyHiUlJQaJjYj0R6shrRdeeAFPPvkklixZgu7du8PCQn2lQ+fOnXUSHBFRY1VX9j10NQ+WqMRgi5tob3oPAFBq4YynZz8BGxsbwwZJRE1Oq8KDDy5Fr01zr8XDwoNErUvWvVJ8sHYfnPKSYS2pgkJIcM/RD4tmT0C7NraGDo+INKT3woM3btzQ5jIiIoNwtgTay8+jQlIFe6c2CB05Dl18vVj4jpoNTetEkfa0Snh8fX11HAYRUdOxtrbG2LFjcOfOHQwfPhxmZlr96CNqEprUiaLG02rSMhFRc6ZQKHDgwAGkpqaq2gIDAxEREcFkh5oVTetEUeNp9T+/srISy5cvx8aNG5Geno6qqiq143l5tde8ICJqanl5eYiJiUFWVhbs7e3x4osv1lhYQdRc1Fcn6tDVPOQVVXBoS0e06uH54IMP8MMPP+CZZ55BdnY2PvvsM0ydOhVyuRxz587VdYxERI8khMBff/2FlStXIisrC1ZWVhg1ahSTHWrW6qoTVU3+iOOkOa0rLW/atAnBwcF4/vnnMXv2bMyZMwcDBgzA6tWrdR0jEVG95HI5YmNjVUNYHTt2xMSJE7kKk5q9mnWi1Nk/4jhpTqsenvT0dPTq1QsAYGNjA5lMBgCIjo7GyZMndRcdEdEjyGQyfPvtt0hNTYWZmRlGjx6NGTNmMNmhFqG6TlRtwvykkNqxh1JXtEp4lEqlauJfx44dcfDgQQDA+fPnYWvLmhZEpD8ODg7o1KkTPDw8MG/ePPTv3/+RtcKImgtHGwssm9yrRtIT5ifFx5N7cf6ODmk1pGVqaqr6+4svvognn3wSISEhSExMxLx583QWHBFRbdLS0tC2bVvVL1iRkZEwMzNT+9lE1FJ4OlljxfTeyCuqgLysEvZW5pDasQ6PrmlVaflhu3fvxvHjx+Hv749p06Y1+9+uWGmZqGWqqqrC/v37VT9vpk6d2ux/3hCR7ui90vLDIiIiEBERoYunIiKqVXZ2NjZv3oycnBwA9+cPKpVK9uoQkUa0TnhkMhlSUlKQn59f41hkZGSjgiIiqqZUKnH8+HEcOHAACoUCtra2GD9+PLp27Wro0IioBdEq4YmLi8NTTz2FwsJCWFpa1jheVlbW6MCIiORyOTZt2oSbN28CALp27Yrx48dzcQQRNZhWq7Ree+01vPLKKyguLkZZWVmNP0REumBhYYF79+7B3Nwc48ePx7Rp05jsEJFWtJq0bGdnh+zs7Bb7g4eTlomar7KyMlhaWqomI1dXTW7Tpo2BIyMiQ2vM97dWPTzdu3dX25SPiEgXrl27hq+//hqnT59WtXl6ejLZIaJG03gOz7Vr11R/f/bZZzFz5kwsW7YMnTt3rrEstHPnzrqLkIiMXkVFBfbu3YuEhAQAQFJSEvr06cMl50SkMxonPH5+fjXaxo4dW+u5OijtQ0StRGZmJmJiYnD37l0AQP/+/TF8+HAmO0SkUxonPDdu3GjKOIiolVEoFDh8+DAOHToEIQTs7e0RFRWFjh07Gjo0IjJCGic8vr6+dR4TQuDy5cvw8PCAo6OjLuIiIiOXk5OjSnZ69OiBcePGwdra2tBhEZGR0mrS8smTJ7FgwQLV42nTpqFbt27w9PRUbSRKRFQfDw8PDB8+HJMmTcKUKVOY7BBRk9Iq4XnjjTcwY8YMAMDZs2exd+9enDlzBu+99x7++c9/6jRAIjIORUVF2LBhA3Jzc1VtgwcPRkBAgAGjIqLWQqtKy4mJiejduzcAYO/evZg0aRICAwPRuXNnfPjhhzoNkIhavosXL2Lbtm0oLS2FXC7HM888w0nJRKRXWvXwODg4qOrwbN26FcOGDQMAFBQUcA4PEamUl5cjNjYWGzZsQGlpKdzc3DB+/HgmO0Skd1r18DzxxBMYO3Ys/P39ceHCBYwbNw4AsHPnTtXfiah1u3nzJrZs2YJ79+4BuD989dhjj8HMTOs9i4mItKbVT55PP/0UXbt2xc2bN/HFF1/AyckJwP0fcO+++26DnuvSpUv44YcfkJ2djYCAALzwwguws7Or9xqFQoHff/8d+/fvh42NDZ5++mnVEBsRGd6NGzfw66+/AgCcnJwQFRWF9u3bGzgqImrNtNpLS1cSExMRGhqKqVOnYsCAAVi1ahWqqqpw4sSJWndhB+53kY8bNw43b97Eyy+/DBsbG/z000/4+uuvERQUpNF9uZcWUdNSKpX4+eef4eLigtGjR9f5/5mIqCEa8/1t0IQnIiICZmZmiIuLAwDcvXsX3t7e+OKLLzB//vxar/nggw/w5Zdf4sKFC3BzcwMAVFVVobi4WOP5Q0x4iHRLCIEzZ84gICBANWRVWVkJc3NzA0dGRMZE75uH6kJ5eTn279+PKVOmqNpcXFwwfPhw7Nixo87rfvzxR8yYMUOV7ACAmZkZJ0sTGUhhYSF+/fVXbN26Ffv371e1M9khoubEYLMH09PTUVVVBR8fH7V2Hx+fOosXFhQUID09HSEhIVi+fDlOnz4NT09PzJgxo95aHuXl5SgvL1c9lslkunkRRK2YEALnzp3Djh07UF5eDnNzc7i4uBg6LCKiWhm0hwcAbGxs1Nrt7OxQVlZW6zXFxcUAgLfffhsXLlzAyJEjUVRUhODgYOzcubPOey1duhSOjo6qP97e3jp6FUStU2lpKTZt2oSYmBiUl5ejXbt2eO6559CnTx9Dh0ZEVCuNe3jOnDmj8ZNqMnm4egiqoKBArf3u3buqVV8Pq24PDg7G999/DwCYNWsW8vLy8OGHH2LMmDG1Xrd48WIsXLhQ9VgmkzHpIdJSRkYGNmzYALlcDolEgvDwcISGhsLExGC/PxERPZLGCU9Dln1rMg/ay8sLzs7OSE5OxtixY1XtycnJ6NWrV63X2NnZoWPHjujSpYtau5+fH06dOlXnvSwtLblKhEhH7OzsUFFRARcXF0RHR6Ndu3aGDomI6JE0/pUsNzdX4z+akEgkeOqpp/Djjz+qCpMdPHgQp06dUu3TBQDfffedWu/MnDlzEBcXpxreKi0txfbt2zFo0CBNXwoRNdCD896cnJwwY8YMPPfcc0x2iKjF0LiHRyqV6vzmH330ERITE9GtWzd069YNJ0+exNtvv63aqgIAEhIScOLECdXjN998EwkJCfDz80NQUBCSk5Ph5eWFL774QufxEbV2SqUSR44cwcGDBzF9+nR07twZwP0eWiKilkTjOjzVc3iCgoIeOZ9H0wKAwP3hr1OnTiE7Oxs9e/ZEhw4d1I6fPn0a+fn5GDlypFr7uXPncPPmTfj4+CAgIKBBe/OwDg/Ro+Xn5yMmJgYZGRkAgL59+6oNPxMR6ZteCg9WJxRCiEcmFwasZagRJjxEdRNCIDExEbt370ZlZSUsLS0xZswY9OrVi5t+EpFBNeb7W+MhrQfn5mg6T4eIWpbi4mJs27YNly9fBgC0b98eUVFRda6cJCJqKbSaw9MU83mIyPBu3ryJy5cvw9TUFMOGDcPAgQPZq0NERkHrSssymQwpKSnIz8+vcSwyMrJRQRGR/jw4TN29e3eEhYWhe/fuatu3EBG1dFolPHFxcXjqqadQWFhYa32buiolE1HzcuvWLezZswdPPPEEbG1tAQBDhw41cFRERLqnVWnU1157Da+88gqKi4tRVlZW4w8RNW8KhQLx8fFYvXo1MjIy1Db9JCIyRlr18GRkZODNN9+ssQ8WETV/ubm5iImJwe3btwEAgYGBNco+EBEZG60Snu7duyM1NbXOLSCIqPkRQuCvv/7Cvn37UFVVBWtra0RGRqJ79+6GDo2IqMlpnPBcu3ZN9fdnn30WM2fOxLJly9C5c+caqziqq7ESUfNx4sQJ7NmzB8D9/6MTJkyAvb29gaOiplBYUoG8ogrIyirhYG0Oqa0FHG0sDB0WkUFpnPD4+fnVaKur6mpzLzxI1BoFBwfjzJkzCAkJQUhICJebG6mse6VYtCkZh6/mqdrC/KRYNrkXPJ2sDRgZkWFpXGk5LS1N4yf19fXVMhz9YKVlag1KS0uRmJiIQYMGqZIbpVIJExOt1ipQC1BYUoEX/5ukluxUC/OTYsX03uzpoRZNL5WWm3sSQ0T/c/36dcTGxkImk8HCwgJ9+/YFACY7Ri6vqKLWZAcADl3NQ15RBRMearW0Ljx4+/ZtfPfdd7h48SKA+xOZ58+fD3d3d50FR0QNU1VVhfj4eJw4cQIA0KZNG3h4eBg4KtIXWVllvcfljzhOZMy0+nVv79696NSpEzZs2ABLS0tYWlri999/R6dOnVjPg8hAbt++je+//16V7PTp0wfPPfccvLy8DBwZ6YuDlXm9x+0fcZzImGnVw/PKK6/gtddewwcffKC2i/q7776Ll156CefPn9dpkERUv8TERMTFxUGpVMLW1hYTJkxAly5dDB0W6ZnUzgJhflIcqmMOj9SOw1nUemk8aflBNjY2yMrKqrGDckFBAby8vFBcXKyr+JoEJy2TscnMzMSPP/6Irl27IjIyUrVNBLU+WfdK8damZLWkJ8xPio8n94IHV2lRC6eXScsP8vf3x6VLlzBgwAC19kuXLsHf31+bpySiBhBCIC8vD23btgUAtGvXDvPmzYObmxuXm7dynk7WWDG9N/KKKiAvq4S9lTmkdqzDQ6RVwvPss89iypQpePfdd9G3b18IIZCQkIAPPvgAb7/9tlqRQhYhJNKt4uJibN++HVevXsW8efPg6uoKAFwwQCqONkxwiB6m1ZBWQ36DbI5FCDmkRS3VlStXsHXrVhQXF8PExAQTJkxAYGCgocMiItILvQ9p3bhxQ5vLiEhLFRUV2LNnD06fPg0AaNu2LSZNmsReHSIiDWmV8LAIIZH+ZGRkICYmBvn5+QCAAQMGYPjw4TAz07qMFhFRq9Oon5gpKSm4ePEihBDo3r07evbsqau4iOj/u3HjBvLz8+Hg4ICoqCh06NDB0CEREbU4WiU8+fn5mDlzJnbs2AELi/sT4yoqKjB27FisWbMGbdq00WmQRK2NEEI1V27w4MEQQqBfv36wsrIycGRERC2TVpWWX3nlFWRnZ+PUqVMoKytDWVkZTp06hezsbLz66qs6DpGo9RBC4K+//sKqVatQVVUF4P7+V2FhYUx2iIgaQatVWs7Ozjh58mSNSq5XrlxB//79UVBQoLMAmwJXaVFzJJfLERsbi9TUVADA2LFjVZt+EhGRAVZplZeX16iyDACOjo4oLy/X5imJWrULFy5g+/btKC0thZmZGUaMGIGQkBBDh0VEZDS0SngGDx6MRYsW4ZtvvoG19f1S5SUlJXjzzTcxePBgnQZIZMzKysqwc+dOJCcnAwA8PDwQHR2tqqBMRES6oVXCs3z5ckRERKBdu3aqlVnnzp2DnZ0ddu3apdMAiYxZdbIjkUgwZMgQhIeHw9TU1NBhEREZHa0Snh49euDKlStYt24dzp8/D4lEglmzZuHJJ5+EjY2NrmMkMlrDhg1Dbm4uxowZA29vb0OHQ0RktLSatDxlyhT88ccfTRGPXnDSMhlKdnY2rl27pjb0++ASdCIiqpveJy3v3LkTpaWlqvk7RFQ/pVKJ48eP48CBA1AoFHBzc1NtrMtkh4io6WlVh2fYsGGIjY3VdSxERunevXv49ddfsW/fPigUCnTt2hUeHh6GDouIqFXRqoenU6dOmDVrFrZv347u3burqi1Xe/3113USHFFLJoRAcnIyduzYgYqKCpibm2P06NHo3bs3e3WIiPRMqzk8QUFB9R4/c+aMluHoB+fwkD5s27YNiYmJAAAvLy9ER0dz2xUiokbQ+xyeffv2QSqV1nosLy9Pm6ckMjqdOnXCmTNnEB4ejiFDhsDERKsRZCIi0gGtEp62bduiro6h+o4RGbPKykrk5eWp5ud0794dHh4ecHZ2NnBkRESk0185S0tLucEhtUqZmZlYuXIl1q5di6KiIlU7kx0iouahQT08H374Ya1/B+4vu01ISECvXr0aHMTVq1eRnZ0Nf3//OofKql26dAkZGRlqbXZ2dhgwYECD70vUWEqlEocPH8bBgwchhIC9vT1kMhns7OwMHRoRET2gQQnP9u3ba/07AJibm8PX1xdLly7V+PlKSkowZcoUHD16FB07dsSlS5ewZMmSeld5LV++HDExMQgICFC1dejQgQkP6d3du3cRExODzMxMAPcrkI8bN471qYiImqEGJTwnTpwAAERGRtZIeLTx3nvv4fz587h69SpcXV2xY8cOjBs3DoMGDcKgQYPqvC40NLRFV3qmli8hIQF79uxBZWUlLC0tMW7cOLUknIiImhet5vDoItkBgF9++QVz586Fq6srAGDs2LEICgrCzz//XO91JSUlOHbsGM6fP4+KigqdxELUEFlZWaisrESHDh3w/PPPM9khImrmtFql9dZbb9V7fNmyZY98jszMTOTm5iI4OFitPTg4+JF1fA4cOIC8vDzcvn0bVVVV+PbbbxEVFVXn+eXl5SgvL1c9lslkj4yP6GFVVVUwM7v/XyYiIgKenp7o06cPiwgSEbUAWiU8CQkJao+VSiVSU1ORnp6O0NBQjZ6joKAAAGoUYnNxcVEdq01kZCSWLl0KZ2dnCCHw7rvvYvr06Th79iy6dOlS6zVLly7F+++/r1FcRA8rLy/Hrl27IJfL8dRTT0EikcDS0hIhISGGDo2IiDSkdeHBhymVSrzxxhs1tpmoS/V5paWlau0lJSX1PkdkZKTq7xKJBO+//z7+7//+D9u2bcNrr71W6zWLFy/GwoULVY9lMhm8vb01ipNat5s3b2LLli24d+8eACAjI4OfHSKiFkirhKc2JiYmePvttxESEqLRSi1vb2+YmJjUWGKekZEBX1/fBt23TZs2uH37dp3nWFpawtLSUuPnJKqqqsKff/6Jo0ePAgCcnJwQHR3NZIeIqIXSaeFBuVyO/Px8jc61trZGaGgotmzZonZ9fHw8Ro0apWq7ePGianWYUqmEXC5Xe56LFy8iLS0NgYGBjX8BRABycnKwatUqVbITFBSE+fPnw8fHx8CRERGRtrTq4altFVVBQQF++uknjBgxQuPn+fe//42hQ4fi73//OwYOHIivv/4a7dq1w9y5c1XnfP755zhx4gRSUlKgUCjQr18/zJw5Ez169EB6ejo++eQTDBw4ENOmTdPmpRCpEUJg8+bNyM7Oho2NDSIjI9GtWzdDh0VERI2k1W7pXl5eNdqcnZ0RGhqKJUuWwMXFRePnSkhIwDfffIPs7GwEBATg9ddfV6u2/MUXX+DixYv44YcfAAC5ubn49ttvkZSUpLrnrFmzYGpqqvE9uVs61SczMxOHDx9GZGQkKyYTETUjjfn+1irhaemY8FA1IQRSUlJQVlaGvn37GjocIiKqR2O+v3U2aZmopSktLUVcXBzOnz8PU1NT+Pr6om3btoYOi0hnCksqkFdUAVlZJRyszSG1tYCjjWYraYmMjdYJz969e/HTTz/h+vXrOHnyJADgq6++wqxZs+Dk5KSr+IiaRGpqKmJjYyGXyyGRSBAaGtqgoVii5i7rXikWbUrG4at5qrYwPymWTe4FTyfu90atj1artH7//XdMnjwZbdu2xV9//aVqr6iowCeffKKz4Ih0rbKyEjt37sTatWshl8vh4uKCZ599FuHh4TAx0emiRSKDKSypqJHsAMChq3l4a1MyCku4JQ+1Plr9hP/oo4+wYcMGfPXVV2rt0dHRWLNmjU4CI9I1pVKJH3/8UZWk9+3bF8899xzatWtn4MiIdCuvqKJGslPt0NU85BUx4aHWR6shratXryI8PBwA1PYRcnV1RU5Ojm4iI9IxExMT9OzZE8XFxZg4cSI6d+5s6JCImoSsrLLe4/JHHCcyRlolPG3btsW1a9cQEBCglvDs378f7du311lwRI2Vn5+PqqoquLq6AgAGDRqEPn36wNqacxjIeDlYmdd73P4Rx4mMkVZDWk8//TTmzZuHM2fOQCKRIDs7G7/88gv+9re/qRUNJDIUIQQSExPx3XffYePGjaisvP8brYmJCZMdMnpSOwuE+UlrPRbmJ4XUjiu1qPXRqofnnXfeQV5eHkJCQqBQKODu7g4TExM8//zzeP3113UdI1GDFBUVYdu2bbhy5QoAwNbWFuXl5TA352+11Do42lhg2eReeGtTMg49tErr48m9uDSdWqVGFR7Mzc3FmTNnoFQqERgYCHd3d13G1mRYeNB4Xb58GVu3bkVJSQlMTU0xbNgwDBw4UG3olai1qK7DIy+rhL2VOaR2rMNDLZveCg9WVVWpPXZ2dsbQoUNrHDczYz1D0q+qqirs2LEDSUlJAO5PoJ80aRLc3NwMHBmR4TjaMMEhqtagzETTIYFWuFsFGZipqSnu3bsH4P7E5KFDhzLxJiIilQZ9I8TExNR57Pjx4/jqq6+gUCgaHRSRJhQKBZRKJczNzSGRSBAVFYX8/Hz4+voaOjQiImpmGpTwREVF1Wi7fPky3n77bcTExGDq1Kn497//ravYiOqUm5uLzZs3o127doiMjAQAODg4cE4WERHVSuta+nfu3MH8+fPRs2dPFBYW4tSpU1i/fj06duyoy/iI1AghcPLkSXz//fe4c+cOLly4gOLiYkOHRUREzVyDJznI5XJ8+umn+OKLL+Dn54ft27cjIiKiKWIjUiOTyRAbG4vr168DADp16oSJEyfC1tbWwJEREVFz16CEZ8WKFViyZAns7OywcuVKPPnkk1zuS3qRkpKCuLg4lJWVwczMDKNGjUJISAg/f0REpJEG1eGRSCSwsrLC+PHjYWFR91LHtWvX6iS4psI6PC1LWVkZvvrqK5SWlsLT0xPR0dGQSmuvIktERMZLb3V4xo0bBwAoKSlBSUlJg25EpK3qJDs7OxuhoaEwNTU1dEhERNTCNKrSckvFHp7mraqqCvHx8fDx8UG3bt0MHQ4RETUTeuvhIWpqt2/fRkxMDHJzc5GcnIyOHTvC0tLS0GEREVELx4SHmgWlUoljx47hwIEDUCqVsLW1xYQJE5jsEBGRTjDhIYMrKChATEwMbt26BQDw9/dHZGQkl5sTEZHOMOEhg5LL5fjuu+9QUVEBCwsLjBkzBoGBgVxuTkREOsWEhwzK3t4ePXv2RF5eHqKiouDs7GzokIiIyAgx4SG9u3r1Ktzc3FQz7MeMGQMTExOYmGi90wkREVG9+A1DelNRUYHt27dj3bp1iI2NRXVFBDMzMyY7RETUpNjDQ3qRkZGBmJgY5OfnAwBcXV2hVCpZRJCIiPSCCQ81KYVCgUOHDuHw4cMQQsDBwQFRUVHo0KGDoUMjIqJWhAkPNRmZTIbff/8dWVlZAICAgACMHTsWVlZWBo6MiIhaGyY81GSsra1RUVEBKysrjBs3Dj179jR0SERE1Eox4SGdKioqgo2NDUxMTGBubo7HH38cVlZW3LOMiIgMiktjSGcuXLiAb775BsePH1e1ubq6MtkhIiKDY8JDjVZWVoaYmBhs3LgRpaWluHTpEpRKpaHDIiIiUuGQFjVKWloatmzZgsLCQkgkEgwZMgTh4eGsq0NERM0KEx7SSlVVFfbv368avnJ2dkZ0dDS8vb0NHBkREVFNTHhIK/n5+fjrr78AAMHBwYiIiICFhYWBoyIiIqodEx7SiqurK0aPHg17e3t07drV0OEQERHVy+ATLTZt2oTw8HD4+/vj8ccfx+XLlzW+9quvvoKvry8++OCDJoyQAODevXtYs2aNqoggAISEhDDZISKiFsGgCU9sbCyeeOIJPP744/jtt99gYWGBsLAw5OXlPfLa06dP44svvgAA1f5MpHtCCJw9exbfffcdrl+/jri4ONWmn0REhSUVSM0pQlJ6AVJzi1BYUmHokIhqZdAhrQ8++AAzZ87Eiy++CAD4+eef4eHhge+++w7//Oc/67xOLpdj+vTp+P777/Hmm2/qK9xWp6SkBNu3b8fFixcBAF5eXoiOjoZEIjFwZETUHGTdK8WiTck4fPV/v6SG+UmxbHIveDpZGzAyopoM1sMjl8uRmJiIiIgIVZu5uTmGDx+OP//8s95r58+fj3HjxmHUqFFNHGXrde3aNXz77be4ePEiTExMMGzYMDz99NNo06aNoUMjomagsKSiRrIDAIeu5uGtTcns6aFmx2A9PBkZGQAAd3d3tXZ3d3ckJyfXed3q1atx7tw5nDp1SuN7lZeXo7y8XPVYJpM1MNrW5caNG/jtt98AAFKpFJMmTYKHh4eBoyKi5iSvqKJGslPt0NU85BVVwNGGKzep+TBYwlNdidfMTD0Ec3NzKBSKWq+5fPky3njjDfz555+wtLTU+F5Lly7F+++/r32wrYyvry86deoEqVSK4cOHw9zc3NAhEVEzIyurrPe4/BHHifTNYAmPVCoFANy9e1etPS8vD23btq31mr1796K4uBiRkZGqtqysLFy/fh1btmxBamoqTE1Na1y3ePFiLFy4UPVYJpOxQN4DlEolTp48iT59+sDCwgISiQRPPvkkqyUTUZ0crOr/Rcj+EceJ9M1gCY+bmxt8fHxw7NgxTJgwQdV+9OhRjBs3rtZrZs+erZbsAMDYsWMxYMAAvPvuu7UmOwBgaWnZoB6h1uTu3buIiYlBZmYm8vLyMH78eABgskNE9ZLaWSDMT4pDtQxrhflJIbXjcBY1Lwb9VluwYAFWrVqFlJQUCCHwzTffIC0tDX/7299U57z11luqic329vbw9fVV+2NhYQEHBwf4+voa6FW0TEIIJCQkYOXKlcjMzISlpSXat29v6LCIqIVwtLHAssm9EOYnVWsP85Pi48m9OH+Hmh2DLkt/4403kJmZiZCQEFhaWsLKygrr1q1Djx49VOfk5eUhMzPTgFEan6KiImzduhVXr14FAHTo0AETJ06Eo6OjgSMjopbE08kaK6b3Rl5RBeRllbC3MofUzoLJDjVLEtEMqsiVlpbi3r17cHNzqzGUcvfuXZSXl8PT07PWa7OysmBlZdWg5dIymQyOjo4oLCyEg4NDo2JvadLT0/H777+jpKQEpqamGDFiBPr378/aOkRE1Ow15vu7WeylZW1tDWvr2otUubi41HttXYkQ1a46MXR3d0d0dDRcXV0NHBEREVHTaxYJDzWtvLw81ao4Ozs7zJo1C1KptM5J3kRERMaGS3GMWFVVFfbt24evv/4aFy5cULW7ubkx2SEiolaFPTxGKicnB5s3b0Z2djYA4NatW+jevbuBoyIiIjIMJjxGRgiBEydOID4+HgqFAjY2NoiMjES3bt0MHRoREZHBMOExIoWFhdiyZQvS0tIAAH5+fpgwYQLs7OwMGxgREZGBMeExIjk5OUhLS4O5uTlGjRqFPn36cLk5ERERmPC0eEIIVVLj5+eHUaNGoUuXLo9czk9ERNSacJVWC5aamopvv/0WhYWFqraBAwcy2SEiInoIE54WqLKyEjt37sTatWuRm5uLgwcPGjokIiKiZo1DWi1MVlYWYmJikJd3f4fivn37YuTIkQaOioiIqHljwtNCKJVKHDlyBAcPHoRSqYSdnR0mTpyIzp07Gzo0IiKiZo8JTwtx8uRJHDhwAADQrVs3REZGwsbGxsBRERERtQxMeFqIkJAQXLhwASEhIejVqxeXmxMRETUAJy03U0VFRYiPj4dSqQQAmJub45lnnkFgYCCTHSIiogZiD08zdPnyZWzduhUlJSWwtLTEkCFDAICJDhERkZaY8DQj5eXl2L17N5KSkgAArq6u8PPzM3BURERELR8Tnmbi1q1biImJQUFBAQBg0KBBGDp0KMzM+E9ERETUWPw2bQYSEhKwY8cOCCHg6OiIqKgo+Pr6GjosIiIio8GEpxnw9vaGiYkJevTogTFjxsDKysrQIRERERkVJjwGIIRAVlYW2rVrBwBwc3PDggUL0KZNGwNHRkREZJy4LF3PZDIZ1q5dix9//BGZmZmqdiY7RERETYc9PHqUkpKCuLg4lJWVwczMDPn5+apeHiIiImo6THj0oLS0FDt37sS5c+cAAJ6enoiOjoZUKjVwZERERK0DE54mduPGDWzZsgUymQwSiQShoaEICwuDqampoUMjIiJqNZjwNLHc3FzIZDK0adMG0dHR8PLyMnRIRERErQ4TniagUChUPTh9+/aFEAK9e/eGhYWFgSMjIiJqnbhKS4eUSiWOHDmC7777DuXl5QDu73/Vv39/JjtEREQGxB4eHSkoKMCWLVuQnp4OAEhOTkbfvn0NHBUREREBTHgaTQiBM2fOYNeuXaioqICFhQXGjBmDwMBAQ4dGRERE/x8TnkYoLi7G9u3bcenSJQCAj48PoqKi4OzsbODIiIiI6EFMeBph3759uHTpEkxMTDB06FAMGjQIJiacFkVERNTcMOFphOHDh+PevXuIiIiAu7u7ocMhIiKiOrA7ogEyMjIQHx+vemxnZ4fZs2cz2SEiImrm2MOjAYVCgUOHDuHw4cMQQsDT0xPdunUzdFhERESkISY8j5CXl4eYmBhkZWUBAAICAtChQwcDR0VEREQNwYSnDkIInDp1Cnv37kVVVRWsrKwwbtw49OzZ09ChERERUQMZPOGRy+XYsmULsrOzERAQgIiIiEdec/PmTezfvx9FRUXo0aMHhg4dColEotO4tm7dijNnzgAAOnbsiIkTJ8LBwUGn96DmobCkAnlFFZCVVcLB2hxSWws42rAyNhGRMTFowpORkYEhQ4bA1dUVffr0wRdffIHBgwdjw4YNdSYwS5Yswfr16zFkyBCYmZlh2bJl6Ny5M3bt2gVra2udxdajRw+kpKRgxIgR6Nevn84TKmoesu6VYtGmZBy+mqdqC/OTYtnkXvB00t3niYiIDEsihBCGuvlTTz2FK1eu4NixYzA3N8fly5fRo0cPrF+/HlOmTKn1mpMnT6olIJmZmfD29sb69esxdepUje4rk8ng6OiIwsJCVa9NWVkZcnJy4OPjozqvqKgIdnZ2jXyV1FwVllTgxf8mqSU71cL8pFgxvTd7eoiImpHavr81ZbBl6QqFAlu2bMGsWbNgbm4OAOjatStCQ0Pxxx9/1Hld//791XpbLCwsIJFIYGlpqXUsaWlp+O6777Bu3ToUFhaq2pnsGLe8oopakx0AOHQ1D3lFFXqOiIiImorBhrTS09NRUlKCLl26qLV36dIFJ0+erPfa69evY926dZDJZNi9ezdeffVVTJgwoc7zy8vLVbuXA/czRACoqqrCnj17cPz4cQCAs7MzSkpK4OjoqO3LohZEVlZZ73H5I44TEVHLYbCEp6ioCABqJBdOTk6qY3VRKBQoKyuDTCZDfn4+7t69i/LyclhZWdV6/tKlS/H+++/XaP/5558hl8sBAL1790ZERESjeoqoZXGwMq/3uP0jjhMRUcthsITH1tYWwP96W6oVFhaqjtXFz88PH374IQAgJycH3bp1Q8+ePfH666/Xev7ixYuxcOFC1WOZTAZvb2/k5uaiTZs2mDBhArp27dqYl0MtkNTOAmF+UhyqYw6P1I7zd4iIjIXB5vD4+PjA2toa165dU2u/evVqg5IPV1dXBAQEqJaQ18bS0hIODg5qfwCgc+fOeP7555nstFKONhZYNrkXwvykau1hflJ8PLkXJywTERkRg/XwmJmZYfz48VizZg3mzZsHMzMzpKam4tChQ1izZo3qvLi4OGRmZmLevHmorKzElStX0KNHD9XxO3fu4OzZsxrV73nYlClTODG5lfN0ssaK6b2RV1QBeVkl7K3MIbVjHR4iImNj0GXpaWlpGDx4MDp27Ii+ffvijz/+QGBgIGJjY2Ficr/zae7cuThx4gRSUlJQUVGB0NBQeHh4oHv37rh37x42bdqEHj16YOvWrRonL41Z1kZERESG0Zjvb4MmPABQUFCAjRs3qiotT5gwQZXsAMCWLVtw69YtvPTSSwDub/mwd+9eJCUlwdbWFr1798bgwYMbdE8mPERERC1Pi054DIEJDxERUcvTIgsPEhEREekLEx4iIiIyekx4iIiIyOgx4SEiIiKjx4SHiIiIjB4THiIiIjJ6THiIiIjI6BlsawlDqi499PDGpURERNR8VX9va1NCsFUmPHK5HADg7e1t4EiIiIiooeRyORwdHRt0TaustKxUKpGVlQV7e3vI5XJ4e3vj1q1brLr8AJlMxvflIXxPasf3pSa+J7Xj+1IT35Pa1fW+CCEgl8vh6emptg2VJlplD4+JiQm8vLwAABKJBADg4ODAD1st+L7UxPekdnxfauJ7Uju+LzXxPaldbe9LQ3t2qnHSMhERERk9JjxERERk9Fp9wmNpaYn33nsPlpaWhg6lWeH7UhPfk9rxfamJ70nt+L7UxPekdk3xvrTKSctERETUurT6Hh4iIiIyfkx4iIiIyOgx4SEiIiKj1yrq8BQWFuLq1atwc3PTuLpyfn4+0tLS0K5dO7i5uTVxhIZx5coVFBUVoUePHg2aGHb79m2kpqbCz8/P6N4bmUyGK1euwNXVFT4+PvWeW1hYiHPnztVo79OnD6ytrZsqRIO4evUq5HI5unfvDisrK42uKSsrw8WLF+Hu7g4PD48mjlD/5HI5Ll++DKlUCl9f33rPTU1Nxe3bt2u0m5iYYNCgQU0UoWFcu3YNhYWF6N69u0b/D6qqqnD9+nUUFxfD19cXzs7OeohSv4qKinDp0iWNPivV7t69i7S0NHh6ehrl/x8ASEtLQ0ZGBkJCQjT+uZKamop79+6hW7dusLGxadgNhZH76quvhLW1tejWrZuwtrYWkyZNEmVlZXWef/XqVTFu3Djh6uoqgoODha2trRg9erTIz8/XY9RN6/bt26Jfv37CyclJdOzYUbRp00Zs375do2uLi4tF9+7dBQDxww8/NHGk+vX1118La2tr4e/vL2xsbMTEiRNFSUlJnefv3btXABCDBw9W+3Pz5k09Rt20srOzxYABA4STk5Po3LmzcHZ2FrGxsY+8bvny5cLBwUF0795ddO7cWcycOVOUl5frIWL9+OGHH4SNjY3o2rWrsLW1FWPGjBFFRUV1nv/pp5/W+Jw4ODgIb29vPUbdtHJzc8WgQYOEo6Oj6Ny5s3B0dBSbN2+u95rdu3cLLy8v4ePjI4KCgoSVlZV44YUXhFKp1FPUTW/16tXC1tZW9VmJiIgQcrm8zvNLSkrEE088IWxtbUVQUJBwdHQUTz31lKioqNBj1E0rPj5eRERECBcXFwFAXL169ZHX5Ofni/DwcGFvby/8/PyEg4ODWL9+fYPua9QJz4kTJ4REIhFbt24VQgiRmZkpPD09xeLFi+u8Zs+ePeLAgQOqx3l5eaJDhw7ihRdeaOpw9SYyMlL0799f9WW+ZMkSYWdnJ7Kzsx957dNPPy1ee+01YWpqalQJz6lTp4REIlH9gL59+7bw8vISb7zxRp3XVCc8xiwqKkqEhISI4uJiIYQQS5cuFTY2NuL27dt1XrNq1SphaWkp4uPjVW3r1q0zml8akpOThYmJiVi3bp0QQoicnBzh6+srXnrpJY2fo7i4WNjb24t33nmnqcLUuylTpojg4GBV4vfpp58Ka2trkZGRUec1bm5uYv78+aoE59SpUwKAiImJ0UfITe78+fPC1NRU/Prrr0KI+98nnTp1Es8//3yd17zxxhvC09NTZGZmCiGEuHv3rujWrZt477339BGyXnz55Zdix44d4ujRoxonPDNmzBA9e/YUhYWFQgghVqxYISwsLMSNGzc0vq9R/7SeN2+eCAoKUmv75z//Kdzc3Br0PBMmTBBRUVG6DM1g7ty5IyQSifjjjz9UbSUlJcLW1lasWLGi3mvXrVsnAgMDRVlZmdElPAsWLBA9e/ZUa/vXv/4lpFJpnb9tVic8ly5dEmfPnq23N6glys3NFSYmJmq/RZWWlgp7e3vxn//8p9ZrFAqFaNeunXj55Zf1FKX+LVy4UHTu3FmtbdmyZcLR0VFUVVVp9ByrV68WJiYmDfph3Zzl5+cLU1NTsXbtWlVbeXm5cHR0FJ9++mmt11RWVgoLCwvx888/q9oUCoWwsbER33//fZPHrA9vvvmm8PX1VWv77LPPhJ2dXZ09NsHBwWLBggVqbR988IHw8PBosjgN5fjx4xolPHK5XFhYWIhVq1ap2qqqqoRUKhVLlizR+H5GPYcnKSkJffr0UWvr168fPvzwQ9y+fbvecdFjx46hrKwMx48fx/Hjx7Fly5YmjlY/zp49CyGE2vtibW2NHj16ICkpqc7rUlNT8eqrr2L//v1GWSCrrs9KXl4eMjIy6p37NWbMGJiZmSE9PR0LFy7ERx99pNqjrSVLTk6GUqlUe1+srKwQEBBQ52fl8uXLyMzMxPjx45GXl4f09HS0b98eLi4u+gq7ydX1WSksLMT169fh5+f3yOf48ccfMXLkSI3nczR3586dg0KhUHtfLCwsEBgYWOdnxczMDB988AE++ugjWFhYwMXFBWvXrkW3bt3wxBNP6Cv0JlXXZ6WoqAjXrl1Dt27dalzTpk0bZGZmqrVlZmbi9u3bj/zeMlYXLlxARUWF2ntpamqK4ODger+3HmbUCU9+fn6NH7TVj/Pz8+v94LzzzjsoKCjA5cuXMWvWLAQGBjZprPqSn58PALW+L9XHHlZZWYnp06fjnXfeQY8ePZo8RkN41GeltoTHzc0NR48eVU06/fPPPzF69Gh4eHjgpZdeavqgm5g2n5WsrCwAwLZt2zBjxgx4eHjg0qVLmDp1KlatWgVzc/OmDVoP8vPza3xRPfhZeZQrV67gyJEj+OOPP5okPkPQ5rMCANHR0YiLi8Obb76JNm3aICsrC5999hns7e2bNF59yc/PR4cOHdTaHvVZeeWVVzBhwgS8/fbbeOyxx3D69GnExMSormmNCU99n6/aFgPUxaiXpZubm6OsrEytrbS0FMD93z7qEx8fj8TERNy4cQNHjhzB3LlzmyxOfar+wqntfanrPfn0008hk8kQFBSEI0eO4MiRIwDur8ZITExs2oD1RJvPSkBAgNoKm8ceewxPPPEE1q9f33SB6pE2n5Xqa5KSknD9+nUkJSUhOTkZsbGx+OKLL5o2YD1pzM8V4H7vjqurKyZMmNAk8RmCNp+VoqIihIeHo0+fPkhPT8fZs2exe/duzJ8/36j+DzX0sxIZGYmDBw8iKysLn3zyCbKysvDVV18BgNGt/tSUNp+v2hh1wtO+fftauwZNTEzg5eWl0XO4urpizpw52LlzZ1OEqHft27cHgFrfl7qWYVtYWEAqleKtt95S/VEoFNi0aRM+//zzJo9ZH+r6rEgkEo1LGQD3e30efp6WSpvPSvUQzcyZM1VLRv38/DB8+HAcPny46YLVo7o+KwAeWcqgqqoKv/76K+bMmWMUvV3VtPmsnD59Gnfu3MGCBQtUQ8DBwcEYNGgQtm7d2rQB64m2n5XQ0FD8/PPP2LdvH1asWIHU1FTY2dmp3ufWRpvPV22MOuEZOXIk9u3bh5KSElVbbGwsBg8erMqUCwoKcOTIEVXmWFxcXON5rl27ZjRzEIKCgiCVStV+oFy8eBFXr17FyJEjVW3Jycm4fPkyAOD1119X9exU/zE1NcWiRYvw22+/6f01NIWRI0di//79av/+sbGxGDBgAOzs7AAA9+7dw5EjR1S/oT38WVEqlYiPj0fPnj31F3gTCggIgJubm9pn5cqVK7h48aLaZ+XcuXO4dOkSgPs/xP39/Wv9wdS2bVv9BN7ERo4ciUOHDqGwsFDVFhsbi969e6t+ThQWFuLIkSM1PiPbt2/HnTt3jKbHuFr37t3h6emp9lm5fv06zp07V+OzcvHiRQBQfR4yMjJUx4UQRvdZOXLkCAoKClRtsbGxqv9bwP3aX0eOHEFRURGA+70Y4oEtLsvKyrB69Wo89dRTMDU11e8LMKDz58/j/PnzAIDOnTujQ4cOap+vjIwMnD59Wu3z9Ujaza1uGWQymejYsaMYNWqUiI2NFYsWLRJmZmbi4MGDqnO2bdumNkv8ySefFK+//rqIiYkR27dvF3//+9/VlhUag5UrVwpLS0uxfPlysXHjRtGjRw8xbNgwtXP69+8vpk2bVudzGNsqraKiIuHn5yeGDx8utmzZIhYvXizMzMzE/v37Vefs3LlTABAXL14UQggxZ84c8eqrr4qYmBixefNmMW7cOGFnZycSEhIM9TJ07scffxQWFhbiiy++EH/88YcICAgQ4eHhaivXBg8eLCZPnqx6vG3bNuHg4CCWL18udu/eLRYsWCAsLS1FUlKSAV6B7pWWloru3buLsLAwsWXLFvHuu+8KU1NTsXPnTtU5Bw4cEABqvObIyEjx2GOP6Tli/fjll1+Eubm5+Oyzz8SmTZtEUFCQGDJkiFAoFKpzwsPDxcSJE4UQQiiVSjFixAjRsWNHsWbNGrFz504xY8YMYWVlJZKTkw30KnSrrKxM9OzZUwwZMkTExMSIf/3rX8LU1FRs27ZNdc7hw4cFAHHq1CkhhBApKSli1KhRYuPGjWLz5s0iNDRUdO/e3WjKOgghRHp6ujh8+LBYuXKlACDWr18vDh8+LO7cuaM6JyIiQkRERKger1+/XpiZmYmlS5eKzZs3i5CQENG3b1+NV0YKYeSrtOzt7XH06FEsW7YMX375Jdzc3PDnn39i8ODBqnPatGmj1uOzevVq/Pjjj1izZg3KysrQqVMnJCYmolevXoZ6GTo3b948SKVSrFmzBkVFRZg6dSpee+01tXMCAwPrnRw3ZMgQuLu7N3WoemNra4sjR45g2bJl+Oqrr+Dq6or9+/cjNDRUdY6zszMGDx6sGqr5/vvv8dNPP2Ht2rWoqKhAQEAAfvjhB6OaVPjMM8+gTZs2+PXXXyGXyzFp0iS88cYbaqvQevXqpdYDGhkZidjYWKxcuRLbt2+Hn58fzpw5A39/f0O8BJ2zsrLCwYMH8fHHH2PFihVwcXHB3r17MXToUNU5jo6OGDx4sKp3ELjfIyiXy7Fw4UJDhN3kZs2aBScnJ/zyyy/YtWsXxo8fjzfeeAMmJv8bSAgICFBNSJZIJNi6dSu+++47xMTEoKioCH5+fkhKSjKaz4qlpSUOHjyIZcuWqT4ru3fvxvDhw1XnVH9Wqt+XHj164O2338a3336LwsJCjBkzBi+++KLRTOQGgAMHDuD7778HAAwePBgrVqwAALz11luIjIwEgBo95dOmTYODgwN+/PFH7Nu3D6NGjcKbb77ZoF4viRAP9J0RERERGSGjnsNDREREBDDhISIiolaACQ8REREZPSY8REREZPSY8BAREZHRY8JDRERERo8JDxERERk9JjxEBAA4efIkTpw4Ue85iYmJqs1ja3us6/sZ2ubNm9W2PqjN1q1bcePGDb3Es2PHDqSmpurlXkTGhgkPkQYKCgqwfv16HDhwoMax3bt349y5czq93507d7BhwwadPuejfPvtt/i///u/es/56aef8Nlnn9X5WNf3M7RnnnnmkUnZggULcPDgQb3Es3DhQuzdu1cv92qs2NhY3Lx509BhEKkw4SHSQGpqKqZPn47Ro0fj+vXrascWLVqE33//Xaf3O3PmDJ588kmdPqcu9OnTR227DaK6PPfcczh8+LChwyBSMeq9tIh0zcvLC//4xz/w3//+t97z7ty5g1OnTsHOzg7BwcFwdHRUHbt+/TrOnz+P8ePHq9ry8vKwb98+TJ06FYWFhTh48CCEEFi/fj0AoEuXLnBzc8OJEycwadIknDx5Erdu3cKoUaPg6OgIhUKBkydPIjs7G35+fjX2oTl58iSEEOjZsyeSkpIgl8sRFhamttdTtZKSEiQlJaGoqAj9+/eHk5OT6lhgYCBKSkoa9J7dvHkTKSkpcHFxQXBwMCwsLDS+34ULF5CcnAzg/p5DAQEB8PLyqvW19ejRA8ePH0dlZSXGjRsHAKioqMDx48chl8vRvXt3dOzYsUGxV8vMzERycjIcHR0xcOBAtb3EaiOTyXDs2DFUVFSgf//+qp2xG3rOnTt3cPLkSbRr1w6BgYEaxVpZWYmTJ0/i3r176Nu3b43nre++Qgj8/vvvGDZsGFxdXVXtcXFx8Pf3R6dOnQDcH+rr168fzMzMcObMGTg4OGDAgAGqfbN27dqFsrIynDhxAmZmZjA3N8fkyZMBAKdPn0ZmZia6du2Krl27avSaiHRCR5ufEhm1U6dOCQDit99+EyYmJmo7ogcGBop//OMfqsf//ve/haOjo4iIiBBhYWFCKpWKXbt2qY7/8MMPon379mrPX71jcmlpqUhNTRXh4eFCIpGIadOmiWnTpomffvpJxMTECEtLSzFixAjRt29fMW3aNHHr1i1x584dERQUJLy9vcXo0aOFk5OTePzxx9V2EZ49e7YICgoSHTp0ECNGjBD+/v7Cw8NDnD9/vsY5/v7+IiIiQgQGBgpXV1fV7vBCCPHCCy+odruu7fHDlixZIuzt7cWYMWNEaGioCAwMFNeuXdP4fps3b1a9ByNHjhQ2NjZi2bJlaveofh4/Pz8REREhXnnlFSGEEKdPnxbe3t4iODhYREZGChcXF7FgwYI6Y62No6OjGDlypGjXrp0YM2aMcHFxEaNGjRLl5eWqc9q1aydWr16terx7927h6OgoQkJCRHh4uLC2thbff/+92vNqck5sbKywtrYWAwcOFIMHDxbBwcHCzc1NfPvtt3XGe+rUKeHj4yM6deokxo4dK3x9fcW6des0vm9lZaUAIA4cOKD2vJ06dVK7r6Ojoxg9erTo1KmTiIyMFO7u7uKxxx5TfeZef/11YWVlJQYMGCCmTZsmZs+eLUpLS0VYWJjw8fEREydOFD169BBTpkx59D8CkY4w4SHSQHXCc/XqVTF58mQxfPhw1bEHE54dO3YIqVQqbty4oTr+888/C1dXV1FcXCyEeHTCI4QQO3fuFKampmrnxMTECABiyZIlau1z5swRffr0EUVFRUIIIa5fvy4cHBzEypUrVefMnj1bABD79+8XQghRVVUlJkyYIIYNG6Z2jrW1tbhw4YIQQgilUimGDRsmnnnmGdU5DUl4KioqhIWFhdizZ4+q7cqVK+LcuXMa3+9hiYmJwsLCQqSmpqrFbWZmJpKSklRtZWVlwtvbW6xYsULVdufOHeHm5iY2btxY5/M/zNHRUXTo0EHcvXtXCCFEZmamaNu2rfjqq69U5zyY8BQXF4t27dqJt956S3V81apVwsrKSqSlpTXoHHd3d7V/66VLlwoAdSY8paWlwtPTUzz77LOqxKOkpETs3r1b4/s2JOEZOHCgKCkpEUIIcfv2bWFtbS22bt2qOsfNzU2sWbNG9XjLli1CKpWq/h8IIcSmTZtqfS1ETYFzeIga6N///jcOHjyI3bt31zi2evVqdO/eHQkJCdi4cSM2bNgAU1NT5OTk4Pz58zq5/8svv6z6uxACGzZswCuvvAJbW1sAQIcOHfDkk0+qhsOqhYSEYOjQoQAAU1NTvP7669i/fz/u3r2rOuexxx5Dt27dAAASiQRhYWG4fPmyVnGamJjA0tIS586dg1KpBIAaw22a3E8mk+HgwYPYuHEjLl++DAcHB5w+fVrtnNDQUAQFBakex8fHIzMzE1KpFH/88Qc2btyIgwcPomPHjrVOPK/Ps88+izZt2gAAPD09MXPmzDonlB8+fBhZWVl46623VG3PPPMM2rRpg9jYWI3POXToEHJzc7Fw4ULVOa+++mqN4cAH7d27F1lZWfj4449hamoKALC2tsaoUaM0vm9DzJkzB9bW1gAAd3d3dO3atd7PirW1NUpLS3HlyhVV26RJkxp8XyJtcQ4PUQN16dIFc+fOxaJFizBy5Ei1Y2lpaSgqKsIff/yh1j5t2jSYmTX+v5uNjQ0cHBxUj3Nzc1FSUlJjbkqnTp2wZ88etTZfX1+1xx06dABwf46Ni4sLAKi+2KtZWlqirKxMq1hNTU2xZs0aLFy4EEuXLkV4eDieeOIJTJkyRXXOo+63adMmPPvss+jUqRN8fHxgaWmJ8vJy5OTkqF3n4eGh9jgtLQ0WFhbYsmWLWruPjw/8/Pwa9Dpqe982btxY67nV7+WDc7YkEgk6dOigWrGkyTnp6elo27YtbGxsVOdYWVnVeJ0PSk9PR5s2bVT/ltrE1hAN/ayMHDkSCxYsQHh4ODw8PDB8+HA899xz6NWrV4PvTaQNJjxEWnjvvffQuXNn/Pbbb2rtDg4O6Ny5M9atW1fntSYmJqoej2qaJhUPT5Z1dnaGqakp8vPz1drz8/MhlUrV2goKCmp9/PB5ujRx4kRMnDgRV69exc6dOzF37lykp6er9VzU56WXXsKSJUvw0ksvqdqkUimEEGrnPfy+ODg4oKKiAj/99JNa0qCN2t63ut4zqVSKwsJCKJVK1QReQP3fQ5NzXFxccO/ePQgh1F7bw7E8yMnJCTKZDFVVVbUm15rct7pd289nfSQSCT755BN89NFHSEhIwNq1axESEoLk5GT4+/s3+vmJHoVDWkRacHd3x9///ne88847KC8vV7WPHj0a27ZtQ2Zmptr5Dz5u164dsrOzIZfLVW0PD7PY2dlBoVCgsrKy3jjMzc3Rr18/bN68WdWmUCgQExODIUOGqJ177Ngx5Obmqh5v3rwZ7du3r7HqSVdKS0tVX9B+fn54+eWXMXHiRI2LDSoUCuTl5amt5Pnzzz/VhuDqMmzYMJiammLVqlVq7VVVVcjOzlY9TkpKwrZt2+p9rgd7iYQQiImJweDBg2s9t1+/fpBIJGrPmZKSgkuXLqn+PTQ9R6FQqA2bxsfHQyaT1Rnn0KFDIZFIaiTb1f/mmtzXxMQE7u7uuHbtmuqcK1euICsrq8771sXOzk4tUbpz5w6USiXMzc0xcOBAfP3117C2tkZiYmKDn5tIG+zhIdLSm2++iZUrV6oNB7z44ovYtm0b+vfvjxdeeAEuLi5ISkpCfHy8au5CdZf+lClTMG3aNJw9e7bGEFj37t1hY2ODRYsWoV+/fujSpUudcXz++eeqL/h+/fphw4YNkMvlWLx4sdp5NjY2GD58OObPn4+0tDT85z//wa+//qr2274uyeVyDBo0CBMmTEBAQAAyMjKwadMm/PTTTxpdb2pqisjISLzyyiv4+9//jtzcXHz55Zca9dh4enriP//5D1599VVcuHABffv2xa1bt7Bp0yZ8+umnGD16NID7hRP37NmjViLgYWfPnsXUqVMxYsQIbN26Fenp6XUmSV5eXli0aBFmzZqFRYsWwcbGBp9//jkef/xxVf0iTc7x9vbGyy+/jKeeegqLFi2CiYkJvvzyS9U8rbpe87JlyzBv3jycOXMG3bp1w5EjR+Dh4YFly5ZpdF8AmDVrFt59912UlZVBoVBg1apVqrk6DRESEoJVq1bB0tISNjY2UCgUWLp0KSZPngxvb2/s27cPFhYWeOyxxxr83ETaYA8PkQbatGmDadOmwd7eXtVmb2+PFStWYNq0aap5CFZWVoiPj8fHH3+MtLQ0JCYmonfv3jh79qzqOisrKxw/fhwhISE4fvw4unTpgp07d2LatGmqyaZt2rTBvn37UFVVhdjYWJw9exZeXl5q81+qDRw4EKdPn0abNm1w5MgRPPbYY0hKSqox7DJ69Gh88cUXuHbtGgoKCrBjxw5Mnz5ddbx///4YOHCg2jXdu3dHRESE6vHDhQfrK0To6uqKhIQE+Pj44MiRIygsLMSePXswdepUje+3du1azJ07F8eOHUN+fj52796N+fPnqyWAtT0PALzwwgs4efIkHB0dcfjwYZiammLz5s2qZAcATpw4oTYJ/GGTJ0/Gli1bMHz4cCQkJKBbt244deoU2rVrpzpn4sSJqvlQAPDBBx/g119/xc2bN5GcnIwlS5bUGPrU5JxPPvkEn3/+OS5evIiCggLs3LkTzz33HDp37lxnvAsXLkR8fDyUSiX++usvjBw5EkuXLm3QfZcuXYolS5YgOTkZ+fn5iImJwd/+9je1+1YnLQ8aOXIkevTooXr89ddfY9y4cdi7dy+2bduGqVOnYs2aNSgvL8fBgwfRtWtXnDlzBp6ennW+HiJdkoiHB8OJyOjMmTMHVVVVWLt2raFDaTYqKirw0ksv4euvv9bJhHIiat74v5yIWiULCwusXLnS0GEQkZ4w4SFqBfr3719j5Q0RUWvCIS0iIiIyepy0TEREREaPCQ8REREZPSY8REREZPSY8BAREZHRY8JDRERERo8JDxERERk9JjxERERk9JjwEBERkdFjwkNERERG7/8BQCdq+PS8HV4AAAAASUVORK5CYII=",
"text/plain": [
- "NK_cells -0.511184\n",
- "Eosinophils -0.498070\n",
- "CD4_T_cells_1 -0.403485\n",
- "B_cells_1 -0.325301\n",
- "B_cells_2 -0.281896\n",
- "CD8_T_cells -0.281529\n",
- "pDC -0.264388\n",
- "CD4_T_cells_3 -0.180847\n",
- "CD16_Monocytes -0.165263\n",
- "CD14_Monocytes_2 -0.164895\n",
- "CD34+ GATA2+ cells -0.132763\n",
- "CD14_Monocytes_3 -0.063592\n",
- "Neutrophils_2 -0.058816\n",
- "Immature Neutrophils_1 -0.004655\n",
- "CD14_Monocytes_1 -0.002719\n",
- "Plasmablast 0.015157\n",
- "Neutrophils_3 0.057406\n",
- "Megakaryocytes 0.292929\n",
- "Immature Neutrophils_2 0.322763\n",
- "Neutrophils_1 0.446441\n",
- "Neutrophils_4 0.447348\n",
- "CD4_T_cells_2 NaN\n",
- "mDC NaN\n",
- "dtype: float64"
+ "
"
]
},
- "execution_count": 56,
"metadata": {},
- "output_type": "execute_result"
+ "output_type": "display_data"
}
],
"source": [
- "neutCounts = metadata[\"Total.neutrophil.count...mm3.\"].astype(float)\n",
- "subsetCorMuSiC = pd.Series(\n",
- " np.corrcoef(\n",
- " music_frac.to_numpy()[~np.isnan(neutCounts.to_numpy()), :].transpose(),\n",
- " neutCounts[~np.isnan(neutCounts.to_numpy())].astype(float),\n",
- " )[music_frac.shape[1], 0 : music_frac.shape[1]]\n",
+ "lymphocytes = [\"CD4 T cells\", \"CD8 T cells\", \"NK cells\", \"B cells\", \"Plasmablasts\"]\n",
+ "neutrophils = [\"Neutrophils\", \"Immature neutrophils\"]\n",
+ "\n",
+ "measured = metadata[\"Total.neutrophil.count...mm3.\"] / (\n",
+ " metadata[\"Total.neutrophil.count...mm3.\"]\n",
+ " + metadata[\"Total.lymphocyte.count...mm3.\"]\n",
")\n",
- "subsetCorMuSiC.index = music_frac.columns\n",
- "subsetCorMuSiC.sort_values()"
+ "estimated = fractions[neutrophils].sum(axis=1) / fractions[\n",
+ " neutrophils + lymphocytes\n",
+ "].sum(axis=1)\n",
+ "\n",
+ "validation = pd.DataFrame({\"measured\": measured, \"estimated\": estimated}).dropna()\n",
+ "r, p = stats.pearsonr(validation[\"measured\"], validation[\"estimated\"])\n",
+ "print(f\"Pearson r = {r:.2f} (p = {p:.1e}, n = {len(validation)} samples)\")\n",
+ "\n",
+ "ax = sns.scatterplot(data=validation, x=\"measured\", y=\"estimated\")\n",
+ "ax.axline((0.5, 0.5), slope=1, color=\"grey\", linestyle=\"--\")\n",
+ "ax.set_xlabel(\"Neutrophil share, blood counts\")\n",
+ "ax.set_ylabel(\"Neutrophil share, Rectangle\")\n",
+ "plt.show()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
- "We can also look for significant changes in cell compositions between disease patients and healthy controls. In this case, for each cell type, we calculate the p-value of this change based on student's t-test."
+ "The estimated and measured neutrophil shares agree well, with most samples close to the diagonal.\n",
+ "A few samples are off by more than 0.2, so the estimates of individual samples should be interpreted with care."
]
},
{
- "cell_type": "code",
- "execution_count": 57,
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Comparing COVID-19 patients and healthy controls"
+ ]
+ },
+ {
+ "cell_type": "markdown",
"metadata": {},
+ "source": [
+ "We can also look for changes in cell type composition between patients and healthy controls.\n",
+ "For each cell type, we compare the estimated fractions with a Mann-Whitney U test and correct the p-values for testing many cell types.\n",
+ "Keep in mind that the fractions of a sample sum to one, so an increase in one cell type forces others to decrease.\n",
+ "The chapter on [compositional analysis](../conditions/compositional.ipynb) explains how to test for changes in composition while taking this into account."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 13,
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-09T12:26:57.421603Z",
+ "iopub.status.busy": "2026-11-09T12:26:57.421530Z",
+ "iopub.status.idle": "2026-11-09T12:26:57.437151Z",
+ "shell.execute_reply": "2026-11-09T12:26:57.436301Z"
+ }
+ },
"outputs": [
{
"data": {
+ "text/html": [
+ "
\n",
+ "\n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
\n",
+ "
mean covid
\n",
+ "
mean healthy
\n",
+ "
p
\n",
+ "
p adj
\n",
+ "
\n",
+ " \n",
+ " \n",
+ "
\n",
+ "
CD4 T cells
\n",
+ "
0.032
\n",
+ "
0.177
\n",
+ "
0.000002
\n",
+ "
0.000023
\n",
+ "
\n",
+ "
\n",
+ "
Eosinophils
\n",
+ "
0.012
\n",
+ "
0.076
\n",
+ "
0.000004
\n",
+ "
0.000027
\n",
+ "
\n",
+ "
\n",
+ "
mDCs
\n",
+ "
0.001
\n",
+ "
0.012
\n",
+ "
0.000005
\n",
+ "
0.000027
\n",
+ "
\n",
+ "
\n",
+ "
CD16 monocytes
\n",
+ "
0.004
\n",
+ "
0.019
\n",
+ "
0.000053
\n",
+ "
0.000154
\n",
+ "
\n",
+ "
\n",
+ "
Immature neutrophils
\n",
+ "
0.011
\n",
+ "
0.001
\n",
+ "
0.000058
\n",
+ "
0.000154
\n",
+ "
\n",
+ "
\n",
+ "
Neutrophils
\n",
+ "
0.545
\n",
+ "
0.223
\n",
+ "
0.000062
\n",
+ "
0.000154
\n",
+ "
\n",
+ "
\n",
+ "
B cells
\n",
+ "
0.022
\n",
+ "
0.068
\n",
+ "
0.000076
\n",
+ "
0.000163
\n",
+ "
\n",
+ "
\n",
+ "
Plasmablasts
\n",
+ "
0.015
\n",
+ "
0.002
\n",
+ "
0.000208
\n",
+ "
0.000391
\n",
+ "
\n",
+ "
\n",
+ "
CD8 T cells
\n",
+ "
0.028
\n",
+ "
0.065
\n",
+ "
0.000539
\n",
+ "
0.000898
\n",
+ "
\n",
+ "
\n",
+ "
CD34+ GATA2+ cells
\n",
+ "
0.000
\n",
+ "
0.000
\n",
+ "
0.010665
\n",
+ "
0.015998
\n",
+ "
\n",
+ "
\n",
+ "
pDCs
\n",
+ "
0.001
\n",
+ "
0.001
\n",
+ "
0.051434
\n",
+ "
0.070137
\n",
+ "
\n",
+ "
\n",
+ "
Unknown
\n",
+ "
0.079
\n",
+ "
0.071
\n",
+ "
0.071532
\n",
+ "
0.089416
\n",
+ "
\n",
+ "
\n",
+ "
NK cells
\n",
+ "
0.030
\n",
+ "
0.046
\n",
+ "
0.109588
\n",
+ "
0.126448
\n",
+ "
\n",
+ "
\n",
+ "
Megakaryocytes
\n",
+ "
0.154
\n",
+ "
0.171
\n",
+ "
0.210296
\n",
+ "
0.225318
\n",
+ "
\n",
+ "
\n",
+ "
CD14 monocytes
\n",
+ "
0.067
\n",
+ "
0.067
\n",
+ "
0.664200
\n",
+ "
0.664200
\n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
"
+ ],
"text/plain": [
- "CD4_T_cells_1 3.535377e-08\n",
- "Eosinophils 2.174486e-07\n",
- "CD34+ GATA2+ cells 1.313440e-06\n",
- "B_cells_2 4.179994e-05\n",
- "Neutrophils_1 1.133780e-04\n",
- "B_cells_1 3.829060e-04\n",
- "Neutrophils_4 4.508343e-04\n",
- "CD14_Monocytes_2 1.010730e-02\n",
- "Megakaryocytes 1.307137e-02\n",
- "Plasmablast 1.902793e-02\n",
- "Neutrophils_2 6.436426e-02\n",
- "NK_cells 1.110367e-01\n",
- "Immature Neutrophils_1 1.321325e-01\n",
- "CD14_Monocytes_1 1.452041e-01\n",
- "CD4_T_cells_3 1.676061e-01\n",
- "Immature Neutrophils_2 1.806682e-01\n",
- "CD14_Monocytes_3 2.641251e-01\n",
- "CD8_T_cells 3.427982e-01\n",
- "pDC 3.571902e-01\n",
- "Neutrophils_3 4.002572e-01\n",
- "CD16_Monocytes 6.143465e-01\n",
- "CD4_T_cells_2 NaN\n",
- "mDC NaN\n",
- "dtype: float64"
+ " mean covid mean healthy p p adj\n",
+ "CD4 T cells 0.032 0.177 0.000002 0.000023\n",
+ "Eosinophils 0.012 0.076 0.000004 0.000027\n",
+ "mDCs 0.001 0.012 0.000005 0.000027\n",
+ "CD16 monocytes 0.004 0.019 0.000053 0.000154\n",
+ "Immature neutrophils 0.011 0.001 0.000058 0.000154\n",
+ "Neutrophils 0.545 0.223 0.000062 0.000154\n",
+ "B cells 0.022 0.068 0.000076 0.000163\n",
+ "Plasmablasts 0.015 0.002 0.000208 0.000391\n",
+ "CD8 T cells 0.028 0.065 0.000539 0.000898\n",
+ "CD34+ GATA2+ cells 0.000 0.000 0.010665 0.015998\n",
+ "pDCs 0.001 0.001 0.051434 0.070137\n",
+ "Unknown 0.079 0.071 0.071532 0.089416\n",
+ "NK cells 0.030 0.046 0.109588 0.126448\n",
+ "Megakaryocytes 0.154 0.171 0.210296 0.225318\n",
+ "CD14 monocytes 0.067 0.067 0.664200 0.664200"
]
},
- "execution_count": 57,
+ "execution_count": 13,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
- "healty_vs_covid = pd.Series(\n",
- " [\n",
- " sci.stats.ttest_ind(\n",
- " music_frac[cell].to_numpy()[metadata[\"status\"].to_numpy() == \"covid\"],\n",
- " music_frac[cell].to_numpy()[metadata[\"status\"].to_numpy() == \"healthy\"],\n",
- " )[1]\n",
- " for cell in music_frac.columns\n",
- " ]\n",
+ "covid = metadata[\"status\"] == \"covid\"\n",
+ "tests = pd.DataFrame(\n",
+ " {\n",
+ " \"mean covid\": fractions[covid].mean(),\n",
+ " \"mean healthy\": fractions[~covid].mean(),\n",
+ " \"p\": [\n",
+ " stats.mannwhitneyu(\n",
+ " fractions.loc[covid, ct], fractions.loc[~covid, ct]\n",
+ " ).pvalue\n",
+ " for ct in fractions.columns\n",
+ " ],\n",
+ " }\n",
")\n",
- "healty_vs_covid.index = music_frac.columns\n",
- "healty_vs_covid.sort_values()"
+ "tests[\"p adj\"] = stats.false_discovery_control(tests[\"p\"])\n",
+ "tests.sort_values(\"p adj\").round({\"mean covid\": 3, \"mean healthy\": 3})"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
- "Here is a boxplot presenting the differences between the two conditions"
+ "We plot four of the cell types that change significantly between the groups.\n",
+ "CD4⁺ T cells and eosinophils have the smallest p-values.\n",
+ "Neutrophils show the largest change and are the cell type we validated against the blood counts above.\n",
+ "Immature neutrophils increase the most relative to their level in healthy blood.\n",
+ "mDCs and CD16 monocytes also change significantly, but we leave them out because they make up less than 2% of the cells, and deconvolution is least reliable for rare cell types {cite:p}`bd:Tsoucas2019`.\n"
]
},
{
"cell_type": "code",
- "execution_count": 58,
- "metadata": {},
+ "execution_count": 14,
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-09T12:26:57.441936Z",
+ "iopub.status.busy": "2026-11-09T12:26:57.441858Z",
+ "iopub.status.idle": "2026-11-09T12:26:57.792722Z",
+ "shell.execute_reply": "2026-11-09T12:26:57.792148Z"
+ }
+ },
"outputs": [
{
"data": {
+ "image/png": "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JRw/fpxgMMjt27fnnIvMf4vCv3ueQP56X758oaGhgWfPnhETE4PT6aSgoMBoXtva2mhtbeXjx48cOnSIffv2UVdXR1dXFxaLBbfbTW9vLxaLhdLSUmPfH+Py8/Pp6enh5s2bfPr0iW3btrFu3ToaGxu5fv36nHIRWUimp6dpbm423kuenZ1NUVGRcTfqyZMnNDU18e7dO/bu3YvX6yUQCNDe3s6iRYvIy8tjcnKSoaEhysvLjX2jxQWDQa5cucL79+9JS0sjOzub6upqGhsbjUc+f5WLyELT0tJCR0cHk5OTZGZmUlxcjMViAb7N7qirqyMUCpGVlUVZWRnt7e3cu3ePqakpcnJysNlsdHd3U11dbewZLW5kZISamhqGhoZISUkhPz+fiooKrl69aryr/Fe5iCw0jx8/pq2tjdHRUVJTUzl8+DDLly8HoK+vjxs3bhAMBklOTqayspKnT5/S0NDAxMQEmzdvJikpiebmZuPcdLa4sbExfD4ffX19JCYmUlxczMmTJ40bRL/LReY3NckiIiIiIiIiERrcJSIiIiIiIhKhJllEREREREQkQk2yiIiIiIiISISaZBEREREREZEINckiIiIiIiIiEWqSRURERERERCLUJIuIiIiIiIhEqEkWERERERERiVCTLCIiIiIiIhKhJllEREREREQkQk2yiIiIiIiISISaZBEREREREZGIfwAtUs4gtwuatQAAAABJRU5ErkJggg==",
"text/plain": [
- ""
+ ""
]
},
- "execution_count": 58,
"metadata": {},
- "output_type": "execute_result"
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "selected = [\"Neutrophils\", \"Immature neutrophils\", \"CD4 T cells\", \"Eosinophils\"]\n",
+ "plot_df = (\n",
+ " fractions[selected]\n",
+ " .join(metadata[\"status\"])\n",
+ " .melt(id_vars=\"status\", var_name=\"cell type\", value_name=\"fraction\")\n",
+ ")\n",
+ "\n",
+ "g = sns.catplot(\n",
+ " data=plot_df,\n",
+ " x=\"status\",\n",
+ " y=\"fraction\",\n",
+ " col=\"cell type\",\n",
+ " kind=\"box\",\n",
+ " showfliers=False,\n",
+ " sharey=False,\n",
+ " height=3,\n",
+ " aspect=0.8,\n",
+ ")\n",
+ "g.map_dataframe(sns.stripplot, x=\"status\", y=\"fraction\", color=\"black\", size=3)\n",
+ "g.set_titles(\"{col_name}\")\n",
+ "plt.show()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Compared to the healthy controls, the patients have more neutrophils, including immature neutrophils, and fewer CD4⁺ T cells and eosinophils.\n",
+ "The table shows the same direction for B cells and CD8⁺ T cells.\n",
+ "Immature neutrophils are rare in healthy blood, and the single-cell study also found them in patients with severe COVID-19 {cite:p}`bd:Schulte-Schrepping2020`.\n",
+ "With 10 controls and fractions that depend on each other, these results describe the cohort rather than establish effects, and a dedicated compositional analysis would be the next step."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 15,
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-09T12:26:57.795981Z",
+ "iopub.status.busy": "2026-11-09T12:26:57.795907Z",
+ "iopub.status.idle": "2026-11-09T12:26:58.362603Z",
+ "shell.execute_reply": "2026-11-09T12:26:58.361063Z"
+ },
+ "tags": [
+ "hide-output"
+ ]
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[93m!\u001b[0m cells [(1, 4), (14, 13)] were not run consecutively\n"
+ ]
},
{
- "data": {
- "image/png": "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",
- "text/plain": [
- ""
- ]
- },
- "metadata": {
- "needs_background": "light"
- },
- "output_type": "display_data"
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[92m→\u001b[0m to save the notebook html, run: lamin save /home/seokim/seocodes_linux/single-cell-best-practices/jupyter-book/deconvolution/bulk_deconvolution.ipynb\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[92m→\u001b[0m finished Run('8POULixJNZAVUB4P') after 52s at 2026-11-09 12:26:58 UTC\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[92m→\u001b[0m go to: https://lamin.ai/theislab/sc-best-practices/run/8POULixJNZAVUB4P\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[92m→\u001b[0m to update your notebook from the CLI, run: lamin save /home/seokim/seocodes_linux/single-cell-best-practices/jupyter-book/deconvolution/bulk_deconvolution.ipynb\n"
+ ]
}
],
"source": [
- "selected_cell = healty_vs_covid.index[np.nanargmin(healty_vs_covid.to_numpy())]\n",
- "status_df = pd.DataFrame(metadata[\"status\"])\n",
- "status_df[\"cellFraction\"] = music_frac[[selected_cell]]\n",
- "status_df.boxplot(by=\"status\")"
+ "ln.finish()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
- "(deconvolution-bulk-deconvolution-key-takeaway-3)=\n",
"## Limitations and traps"
]
},
@@ -2454,9 +2210,13 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "While single cell data is less prone to contain missing cell types, compared to pre-selected sorted cells, dealing with missing cell types is still considered a major challenge in the field of cell type deconvolution to this day {cite:p}`bd:Cobos2020,bd:Jin2021`. In addition, the number of cell types within the signature matrix has a major influence on deconvolution accuracy, as more cell types usually results in a less accurate deconvolution process {cite:p}`bd:Newman2019`. \n",
+ "The [four rules of thumb](#deconvolution-bulk-deconvolution-key-takeaway-2) cover the most common sources of error.\n",
+ "Our example of deconvolving bulk COVID-19 whole blood samples shows a few more traps:\n",
"\n",
- "While several deconvolution methods can correctly infer the proportion of major cellular components, their performance for rare or correlated components varies. To deal with the co-linearity between the predictors some methods perform feature selection prior deconvolution by selecting a subset of genes (called signature gene list) that minimizes the correlation between cell types."
+ "- **Fractions of cells are not fractions of RNA.** Converting between the two relies on an estimate of each cell type's RNA content, so the fractions of cell types with little RNA, such as platelets (`Megakaryocytes`), are uncertain.\n",
+ "- **The reference is not the sample.** Differences in patients, technology or disease state change gene expression and get attributed to the wrong cell types; a reference from the same samples helps {cite:p}`bd:Cobos2023`.\n",
+ "- **Unknown content is estimated, not identified.** The `Unknown` column tells you how much of a sample the reference misses, but not which cells {cite:p}`bd:Cobos2020,bd:Jin2021`.\n",
+ "- **Trust cohort trends more than single samples.** A few samples were off by more than 0.2, rare cell types are the least reliable {cite:p}`bd:Tsoucas2019`, and fractions are [compositional](../conditions/compositional.ipynb)."
]
},
{
@@ -2470,14 +2230,12 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "Other than the methods we described before, there are additional tools which can be utilized to either improve deconvolution or deconvolve higher resolution states within cell types:\n",
+ "Deconvolution methods are moving beyond cell type proportions:\n",
"\n",
- "**AutoGeneS** {cite:p}`bd:Aliee2021` proposes a multi-objective feature selection method that can be integrated into a deconvolution platform. AutoGeneS requires no prior knowledge about marker genes and selects genes by simultaneously optimizing multiple criteria: minimizing the correlation and maximizing the distance between cell types.\n",
- "AutoGeneS can be applied to reference profiles from various sources like single-cell experiments or sorted\n",
- "cell populations. \n",
- "\n",
- "**CPM** {cite:p}`bd:Frishberg2019` is a cell-state deconvolution method which allows discovering compositional changes occurring within each cell type, based on the single cell cell space, often capturing transitions in cell compositions across continuous cellular trajectories.\n",
- "By focusing on the variation within cell types, and less between cell types (as most deconvolution methods), CPM can discover changes in compositions of distinct subgroups of cells or continuous changes across specific cellular trajectories. "
+ "- **Cell-type-specific expression.** BayesPrism {cite:p}`bd:Chu2022` and CIBERSORTx {cite:p}`bd:Newman2019` also estimate each cell type's expression in each sample, which tells apart more expression per cell from more cells.\n",
+ "- **Marker gene selection.** AutoGeneS {cite:p}`bd:Aliee2021` selects genes that make cell types as distinguishable as possible, without prior knowledge of markers.\n",
+ "- **Cell states.** CPM {cite:p}`bd:Frishberg2019` deconvolves the variation within cell types, such as shifts along a cellular trajectory.\n",
+ "- **Spatial transcriptomics.** Each spot captures several cells and is deconvolved like a small bulk sample, see the chapter on [spatial deconvolution](../spatial/deconvolution.ipynb)."
]
},
{
@@ -2491,13 +2249,14 @@
"### Authors\n",
"\n",
"* Hananeh Aliee\n",
- "* Amit Frishberg"
+ "* Amit Frishberg\n",
+ "* Seo H. Kim"
]
}
],
"metadata": {
"kernelspec": {
- "display_name": "Python 3.8.13 ('ehrapy')",
+ "display_name": "bulk-deconvolution",
"language": "python",
"name": "python3"
},
@@ -2511,12 +2270,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
- "version": "3.10.9"
- },
- "vscode": {
- "interpreter": {
- "hash": "4d5918d002166dfd527209d819571eb9af8e7968715260fa98d1ef9b8155f081"
- }
+ "version": "3.12.16"
}
},
"nbformat": 4,
diff --git a/jupyter-book/deconvolution/bulk_deconvolution.yml b/jupyter-book/deconvolution/bulk_deconvolution.yml
new file mode 100644
index 00000000..06eef514
--- /dev/null
+++ b/jupyter-book/deconvolution/bulk_deconvolution.yml
@@ -0,0 +1,16 @@
+name: bulk-deconvolution
+channels:
+ - conda-forge
+dependencies:
+ - conda-forge::ipykernel=7.3.0
+ - conda-forge::ipywidgets=8.1.9
+ - conda-forge::python=3.12.16
+ - pip
+ - pip:
+ - lamindb==2.12.2
+ # rectanglepy pins numpy<2 and scipy==1.13.0, which has no wheels for Python 3.13
+ - rectanglepy==1.7.0
+ # pyarrow 26 requires numpy>=2
+ - pyarrow==25.0.0
+ - scanpy==1.11.5
+ - seaborn==0.13.2
diff --git a/jupyter-book/deconvolution/bulk_deconvolution_keytakeaways.txt b/jupyter-book/deconvolution/bulk_deconvolution_keytakeaways.txt
index 736fb1da..dc2550a5 100644
--- a/jupyter-book/deconvolution/bulk_deconvolution_keytakeaways.txt
+++ b/jupyter-book/deconvolution/bulk_deconvolution_keytakeaways.txt
@@ -1,11 +1,8 @@
1
-Use unbiased reference data with no missing cell type.
+Cell type deconvolution method allows us to gain single-cell resolution information out of the old bulk samples.
2
-Normalize the reference data using library size normalization.
+Follow the four rules of thumb when performing cell type deconvolution.
3
-Feature selection prior deconvolution improves the accuracy of the results particularly for linear deconvolution methods.
-
-4:deconvolution-bulk-deconvolution-key-takeaway-3
-Deconvolution is a challenging task (see limitations and traps). Therefore, we recommend the users to try more than one deconvolution method and select one after assessing the results biologically.
\ No newline at end of file
+Practically, when performing cell type deconvolution, run more than one method, check whether they agree, and validate against any measured proportions you have (for example, blood counts or histology).
\ No newline at end of file
diff --git a/scripts/deconvolution/bulk_decon_covid.ipynb b/scripts/deconvolution/bulk_decon_covid.ipynb
new file mode 100644
index 00000000..92a30cf4
--- /dev/null
+++ b/scripts/deconvolution/bulk_decon_covid.ipynb
@@ -0,0 +1,371 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "70a1f13a",
+ "metadata": {},
+ "source": [
+ "# bulk COVID-19 whole blood samples"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "id": "315538ff",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-06T13:52:24.630450Z",
+ "iopub.status.busy": "2026-11-06T13:52:24.630322Z",
+ "iopub.status.idle": "2026-11-06T13:52:27.469274Z",
+ "shell.execute_reply": "2026-11-06T13:52:27.468036Z"
+ }
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[92m→\u001b[0m connected lamindb: theislab/sc-best-practices\n",
+ "\u001b[92m→\u001b[0m loaded Transform('u1QfiYNpetF80002', key='bulk_decon_covid.ipynb'), re-started Run('8qZN9LOkJGgTAHi5') at 2026-11-09 13:03:02 UTC\n"
+ ]
+ }
+ ],
+ "source": [
+ "import lamindb as ln\n",
+ "\n",
+ "ln.connect(\"theislab/sc-best-practices\")\n",
+ "assert ln.setup.settings.instance.slug == \"theislab/sc-best-practices\"\n",
+ "ln.track(\"u1QfiYNpetF8\")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "id": "99aed9ee",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-06T13:52:27.473983Z",
+ "iopub.status.busy": "2026-11-06T13:52:27.473497Z",
+ "iopub.status.idle": "2026-11-06T13:52:27.688346Z",
+ "shell.execute_reply": "2026-11-06T13:52:27.686965Z"
+ }
+ },
+ "outputs": [],
+ "source": [
+ "from pathlib import Path\n",
+ "\n",
+ "import pandas as pd"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "id": "41418456",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-06T13:52:27.690103Z",
+ "iopub.status.busy": "2026-11-06T13:52:27.689875Z",
+ "iopub.status.idle": "2026-11-06T13:52:32.589459Z",
+ "shell.execute_reply": "2026-11-06T13:52:32.588285Z"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "AnnData object with n_obs × n_vars = 89883 × 33417\n",
+ " obs: 'orig.ident', 'nCount_RNA', 'nFeature_RNA', 'nCount_HTO', 'nFeature_HTO', 'percent.mito', 'percent.hb', 'HTO_maxID', 'HTO_secondID', 'HTO_margin', 'HTO_classification', 'HTO_classification.global', 'hash.ID', 'demultID', 'donor', 'onset_of_symptoms', 'days_after_onset', 'sampleID', 'date_of_sampling', 'experiment', 'cartridge', 'platform', 'purification', 'cells', 'age', 'sex', 'group_per_sample', 'who_per_sample', 'disease_stage', 'diagnosis', 'oxygen', 'outcome', 'comorbidities', 'COVID.19.related_medication_and_anti.microbials', 'primary_complaint', 'RNA_snn_res.0.8', 'cluster_labels_res.0.8', 'new.order', 'hpca.labels', 'blueprint.labels', 'monaco.labels', 'immune.labels', 'dmap.labels', 'hemato.labels'\n",
+ " obsm: 'X_umap'\n",
+ " layers: None (.X)"
+ ]
+ },
+ "execution_count": 3,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "import anndata as ad\n",
+ "import h5py\n",
+ "import numpy as np\n",
+ "import scipy.sparse as sp\n",
+ "\n",
+ "h5ad_path = Path(\n",
+ " \"~/Downloads/seurat_COVID19_freshWB_PBMC_cohort2_incl_raw.h5ad\"\n",
+ ").expanduser()\n",
+ "\n",
+ "# The file holds whole blood and PBMC samples, with normalized values in X and raw counts in\n",
+ "# layers[\"counts\"]. The bulk samples are whole blood, so the reference only needs the whole blood\n",
+ "# cells and their raw counts. Reading the counts in gene chunks avoids loading both full matrices.\n",
+ "with h5py.File(h5ad_path) as f:\n",
+ " obs = ad.io.read_elem(f[\"obs\"])\n",
+ " var = ad.io.read_elem(f[\"var\"])\n",
+ " umap = ad.io.read_elem(f[\"obsm/X_umap\"])\n",
+ " keep = (obs[\"cells\"] == \"Whole_blood\").to_numpy()\n",
+ " counts = ad.io.sparse_dataset(\n",
+ " f[\"layers/counts\"]\n",
+ " ) # stored as CSC, so column slices are cheap\n",
+ " chunk = 2000\n",
+ " X = sp.hstack(\n",
+ " [counts[:, j : j + chunk][keep] for j in range(0, counts.shape[1], chunk)]\n",
+ " ).tocsr()\n",
+ "\n",
+ "assert np.array_equal(X.data, np.round(X.data)), (\n",
+ " \"layers['counts'] should hold integer counts\"\n",
+ ")\n",
+ "X = X.astype(\n",
+ " np.float32\n",
+ ") # integer counts are exact in float32, at half the size of float64\n",
+ "\n",
+ "adata = ad.AnnData(\n",
+ " X=X,\n",
+ " obs=obs[keep].copy(),\n",
+ " var=pd.DataFrame(index=var.index),\n",
+ " obsm={\"X_umap\": umap[keep]},\n",
+ ")\n",
+ "for col in adata.obs.select_dtypes(\"category\"):\n",
+ " adata.obs[col] = adata.obs[col].cat.remove_unused_categories()\n",
+ "adata"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "id": "bd31b955",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-06T13:52:32.591107Z",
+ "iopub.status.busy": "2026-11-06T13:52:32.590903Z",
+ "iopub.status.idle": "2026-11-06T13:53:18.612845Z",
+ "shell.execute_reply": "2026-11-06T13:53:18.611914Z"
+ }
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[92m→\u001b[0m returning artifact with same hash: Artifact(uid='Cbed0qYVdW4lrsAy0001', key='deconvolution/bulk_deconvolution/schulte_schrepping2020_covid19_wholeblood_counts.h5ad', description='scRNA-seq reference: COVID-19 fresh whole blood, cohort 2, raw counts in X, cell types in obs['cluster_labels_res.0.8'], author UMAP in obsm['X_umap']. Schulte-Schrepping et al. 2020, Cell (doi:10.1016/j.cell.2020.08.001)', suffix='.h5ad', kind=None, otype='AnnData', size=198591867, hash='_hE_W4wRW92txt31VtzQVn', n_files=None, n_observations=None, extra_data=None, branch_id=1, created_on_id=1, space_id=1, storage_id=1, run_id=224, schema_id=None, created_by_id=5, created_at=2026-11-06 13:52:43 UTC, is_locked=False, version_tag=None, is_latest=True); to track this artifact as an input, use: ln.Artifact.get()\n"
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "Artifact(uid='Cbed0qYVdW4lrsAy0001', key='deconvolution/bulk_deconvolution/schulte_schrepping2020_covid19_wholeblood_counts.h5ad', description='scRNA-seq reference: COVID-19 fresh whole blood, cohort 2, raw counts in X, cell types in obs['cluster_labels_res.0.8'], author UMAP in obsm['X_umap']. Schulte-Schrepping et al. 2020, Cell (doi:10.1016/j.cell.2020.08.001)', suffix='.h5ad', kind=None, otype='AnnData', size=198591867, hash='_hE_W4wRW92txt31VtzQVn', n_files=None, n_observations=None, extra_data=None, branch_id=1, created_on_id=1, space_id=1, storage_id=1, run_id=224, schema_id=None, created_by_id=5, created_at=2026-11-06 13:52:43 UTC, is_locked=False, version_tag=None, is_latest=True)"
+ ]
+ },
+ "execution_count": 4,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "reference_path = Path(\"schulte_schrepping2020_covid19_wholeblood_counts.h5ad\")\n",
+ "# The chapter environment is pinned to anndata 0.10 by rectanglepy, which cannot read the\n",
+ "# nullable string encoding that newer anndata versions use for pandas string columns.\n",
+ "with ad.settings.override(allow_write_nullable_strings=False):\n",
+ " adata.write_h5ad(reference_path, compression=\"gzip\")\n",
+ "\n",
+ "ln.Artifact(\n",
+ " reference_path,\n",
+ " key=\"deconvolution/bulk_deconvolution/schulte_schrepping2020_covid19_wholeblood_counts.h5ad\",\n",
+ " description=(\n",
+ " \"scRNA-seq reference: COVID-19 fresh whole blood, cohort 2, raw counts in X, \"\n",
+ " \"cell types in obs['cluster_labels_res.0.8'], author UMAP in obsm['X_umap']. \"\n",
+ " \"Schulte-Schrepping et al. 2020, Cell (doi:10.1016/j.cell.2020.08.001)\"\n",
+ " ),\n",
+ ").save()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "id": "491a9b75",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-06T13:53:18.615756Z",
+ "iopub.status.busy": "2026-11-06T13:53:18.615171Z",
+ "iopub.status.idle": "2026-11-06T13:53:45.180086Z",
+ "shell.execute_reply": "2026-11-06T13:53:45.179312Z"
+ }
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "genes without a length: 17\n"
+ ]
+ }
+ ],
+ "source": [
+ "REPO = \"https://raw.githubusercontent.com/schultzelab/COVID-19-blood-bulk-RNA-Seq/main/tables/\"\n",
+ "GTF = \"https://ftp.ebi.ac.uk/pub/databases/gencode/Gencode_human/release_33/gencode.v33.annotation.gtf.gz\"\n",
+ "\n",
+ "# --- 1. Fetch and read ---------------------------------------------------------\n",
+ "counts = pd.read_csv(\n",
+ " REPO + \"raw_counts.txt\", sep=\"\\t\", index_col=0\n",
+ ") # genes x samples, Ensembl IDs\n",
+ "counts.index.name = \"gene_id\"\n",
+ "counts.columns = counts.columns.astype(str)\n",
+ "\n",
+ "metadata = pd.read_csv(REPO + \"anno.txt\", sep=\"\\t\", index_col=0)\n",
+ "metadata.index = metadata.index.astype(str)\n",
+ "metadata.index.name = \"sample_id\"\n",
+ "\n",
+ "id2sym = (\n",
+ " pd.read_csv(\n",
+ " REPO + \"ID2SYMBOL_gencode_v33.txt\",\n",
+ " sep=\"\\t\",\n",
+ " header=None,\n",
+ " index_col=0,\n",
+ " usecols=[0, 1],\n",
+ " )\n",
+ " .iloc[:, 0]\n",
+ " .rename(\"gene_symbol\") # without a string name, saving to parquet fails\n",
+ ")\n",
+ "\n",
+ "\n",
+ "# --- 2. Gene lengths from GENCODE v33 (union of exons per gene) ----------------\n",
+ "def gene_lengths_from_gtf(gtf_path):\n",
+ " gtf = pd.read_csv(\n",
+ " gtf_path,\n",
+ " sep=\"\\t\",\n",
+ " comment=\"#\",\n",
+ " header=None,\n",
+ " usecols=[2, 3, 4, 8],\n",
+ " names=[\"feature\", \"start\", \"end\", \"attr\"],\n",
+ " )\n",
+ " ex = gtf[gtf[\"feature\"] == \"exon\"].copy()\n",
+ " ex[\"gene_id\"] = ex[\"attr\"].str.extract(r'gene_id \"([^\"]+)\"', expand=False)\n",
+ " ex = ex.sort_values([\"gene_id\", \"start\"]).reset_index(drop=True)\n",
+ " prev_end = ex.groupby(\"gene_id\")[\"end\"].cummax().groupby(ex[\"gene_id\"]).shift()\n",
+ " block = (\n",
+ " prev_end.isna() | (ex[\"start\"] > prev_end + 1)\n",
+ " ).cumsum() # merge overlapping exons\n",
+ " blocks = ex.groupby(block).agg(\n",
+ " gene_id=(\"gene_id\", \"first\"), start=(\"start\", \"min\"), end=(\"end\", \"max\")\n",
+ " )\n",
+ " return (\n",
+ " (blocks[\"end\"] - blocks[\"start\"] + 1)\n",
+ " .groupby(blocks[\"gene_id\"])\n",
+ " .sum()\n",
+ " .rename(\"length_bp\")\n",
+ " )\n",
+ "\n",
+ "\n",
+ "lengths = gene_lengths_from_gtf(GTF)\n",
+ "print(\n",
+ " \"genes without a length:\", lengths.reindex(counts.index).isna().sum()\n",
+ ") # should be ~0\n",
+ "\n",
+ "\n",
+ "# --- 3. Derived tables -----------------------------------------------------------\n",
+ "def counts_to_tpm(counts, lengths):\n",
+ " lengths = lengths.reindex(counts.index)\n",
+ " keep = lengths.notna()\n",
+ " rate = counts[keep].div(lengths[keep] / 1e3, axis=0)\n",
+ " return rate.div(rate.sum(axis=0), axis=1) * 1e6\n",
+ "\n",
+ "\n",
+ "tpm = counts_to_tpm(counts, lengths)\n",
+ "bulks = (\n",
+ " tpm.groupby(id2sym.reindex(tpm.index)).sum().T\n",
+ ") # samples x genes, TPM (Rectangle input)\n",
+ "bulks.index.name = \"sample_id\"\n",
+ "\n",
+ "metadata = metadata.loc[bulks.index]"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "id": "8798abbb",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-06T13:53:45.181575Z",
+ "iopub.status.busy": "2026-11-06T13:53:45.181489Z",
+ "iopub.status.idle": "2026-11-06T13:53:48.182105Z",
+ "shell.execute_reply": "2026-11-06T13:53:48.181500Z"
+ }
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[92m→\u001b[0m returning artifact with same hash: Artifact(uid='0ZMDOll0eeiu2jiB0000', key='deconvolution/bulk_deconvolution/covid19_wholeblood_bulk_tpm.parquet', description='Whole-blood bulk RNA-seq, TPM (exon-union lengths, GENCODE v33), samples x genes. Aschenbrenner et al. 2021 (doi:10.1186/s13073-020-00823-5), github.com/schultzelab/COVID-19-blood-bulk-RNA-Seq', suffix='.parquet', kind='dataset', otype='DataFrame', size=31920445, hash='BKL_r-HhLYmPnJGK2ihIxQ', n_files=None, n_observations=49, extra_data=None, branch_id=1, created_on_id=1, space_id=1, storage_id=1, run_id=218, schema_id=None, created_by_id=5, created_at=2026-11-05 14:25:55 UTC, is_locked=False, version_tag=None, is_latest=True); to track this artifact as an input, use: ln.Artifact.get()\n",
+ "\u001b[92m→\u001b[0m returning artifact with same hash: Artifact(uid='RuXh6aQaToI9tnMA0000', key='deconvolution/bulk_deconvolution/covid19_wholeblood_metadata.parquet', description='Sample metadata incl. status and neutrophil counts (/mm3). Aschenbrenner et al. 2021 (doi:10.1186/s13073-020-00823-5), github.com/schultzelab/COVID-19-blood-bulk-RNA-Seq', suffix='.parquet', kind='dataset', otype='DataFrame', size=14265, hash='ywXnYflpiiKFvEB4L65dTQ', n_files=None, n_observations=49, extra_data=None, branch_id=1, created_on_id=1, space_id=1, storage_id=1, run_id=218, schema_id=None, created_by_id=5, created_at=2026-11-05 14:26:21 UTC, is_locked=False, version_tag=None, is_latest=True); to track this artifact as an input, use: ln.Artifact.get()\n"
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "Artifact(uid='RuXh6aQaToI9tnMA0000', key='deconvolution/bulk_deconvolution/covid19_wholeblood_metadata.parquet', description='Sample metadata incl. status and neutrophil counts (/mm3). Aschenbrenner et al. 2021 (doi:10.1186/s13073-020-00823-5), github.com/schultzelab/COVID-19-blood-bulk-RNA-Seq', suffix='.parquet', kind='dataset', otype='DataFrame', size=14265, hash='ywXnYflpiiKFvEB4L65dTQ', n_files=None, n_observations=49, extra_data=None, branch_id=1, created_on_id=1, space_id=1, storage_id=1, run_id=218, schema_id=None, created_by_id=5, created_at=2026-11-05 14:26:21 UTC, is_locked=False, version_tag=None, is_latest=True)"
+ ]
+ },
+ "execution_count": 6,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "src = \"Aschenbrenner et al. 2021 (doi:10.1186/s13073-020-00823-5), github.com/schultzelab/COVID-19-blood-bulk-RNA-Seq\"\n",
+ "\n",
+ "ln.Artifact.from_dataframe(\n",
+ " bulks,\n",
+ " key=\"deconvolution/bulk_deconvolution/covid19_wholeblood_bulk_tpm.parquet\",\n",
+ " description=f\"Whole-blood bulk RNA-seq, TPM (exon-union lengths, GENCODE v33), samples x genes. {src}\",\n",
+ ").save()\n",
+ "\n",
+ "ln.Artifact.from_dataframe(\n",
+ " metadata,\n",
+ " key=\"deconvolution/bulk_deconvolution/covid19_wholeblood_metadata.parquet\",\n",
+ " description=f\"Sample metadata incl. status and neutrophil counts (/mm3). {src}\",\n",
+ ").save()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 7,
+ "id": "a3279837",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\u001b[94m•\u001b[0m please hit CTRL + s to save the notebook in your editor .. \u001b[92m✓\u001b[0m\n",
+ "\u001b[92m→\u001b[0m finished Run('8qZN9LOkJGgTAHi5') after 44s at 2026-11-09 13:03:46 UTC\n",
+ "\u001b[92m→\u001b[0m go to: https://lamin.ai/theislab/sc-best-practices/run/8qZN9LOkJGgTAHi5\n",
+ "\u001b[92m→\u001b[0m to update your notebook from the CLI, run: lamin save /home/seokim/seocodes_linux/single-cell-best-practices/scripts/deconvolution/bulk_decon_covid.ipynb\n"
+ ]
+ }
+ ],
+ "source": [
+ "ln.finish()"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "bulk-decon-lamin",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.13.0"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}