evident
v0.4.0
Evident est un outil permettant d'effectuer des calculs de taille et de puissance d'effet sur les données du microbiome.
Vous pouvez installer la version la plus récente d'Evident depuis PyPi à l'aide de la commande suivante :
pip install evident
Evident est également disponible sous forme de plugin QIIME 2. Assurez-vous d'avoir activé un environnement QIIME 2 et exécutez la même commande d'installation que ci-dessus.
Pour vérifier qu'Evident est correctement installé, exécutez ce qui suit à partir de la ligne de commande :
qiime evident --help
Vous devriez voir quelque chose comme ceci si Evident est correctement installé :
Usage: qiime evident [OPTIONS] COMMAND [ARGS]...
Description: Perform power analysis on microbiome data. Supports
calculation of effect size given metadata covariates and supporting
visualizations.
Plugin website: https://github.com/biocore/evident
Getting user support: Please post to the QIIME 2 forum for help with this
plugin: https://forum.qiime2.org
Options:
--version Show the version and exit.
--example-data PATH Write example data and exit.
--citations Show citations and exit.
--help Show this message and exit.
Commands:
multivariate-effect-size-by-category
Multivariate data effect size by category.
multivariate-power-analysis Multivariate data power analysis.
plot-power-curve Plot power curve.
univariate-effect-size-by-category
Univariate data effect size by category.
univariate-power-analysis Univariate data power analysis.
univariate-power-analysis-repeated-measures
Univariate data power analysis for repeated
measures.
visualize-results Tabulate evident results.
Evident peut opérer sur deux types de données :
Les données univariées peuvent être une diversité alpha. ratios logarithmiques, coordonnées PCoA, etc. Les données multivariées sont généralement une matrice de distance de diversité bêta.
Pour ce didacticiel, nous utiliserons les valeurs de diversité alpha, mais les commandes sont presque les mêmes pour les matrices de distance de diversité bêta.
Tout d’abord, ouvrez Python et importez Evident
import evidentEnsuite, chargez votre fichier de diversité et des exemples de métadonnées.
import pandas as pd
metadata = pd . read_table ( "data/metadata.tsv" , sep = " t " , index_col = 0 )
faith_pd = metadata [ "faith_pd" ] La structure de données principale dans Evident est le « DataHandler ». C'est ainsi qu'Evident stocke les données et métadonnées pour les calculs de puissance. Pour notre exemple de diversité alpha, nous allons charger la classe UnivariateDataHandler depuis Evident. UnivariateDataHandler prend en entrée la série pandas avec les valeurs de diversité et le DataFrame pandas contenant les exemples de métadonnées. Par défaut, Evident ne prendra en compte que les colonnes de métadonnées comportant au maximum 5 niveaux. Nous choisissons 5 échantillons comme valeur par défaut car les colonnes contenant plus de 5 groupes peuvent indiquer des colonnes techniques (par exemple, ID du sujet). Pour modifier ce comportement, fournissez une valeur pour l'argument max_levels_per_category . Vous pouvez définir cette valeur sur -1 pour ne pas fournir de limite supérieure de niveaux auxquels supprimer une colonne. De plus, Evident ne prendra en compte aucun niveau de catégorie représenté par moins de 3 échantillons. Nous choisissons 3 échantillons comme valeur par défaut car les niveaux comportant moins de 3 échantillons peuvent présenter des variances élevées. Pour modifier ce comportement, utilisez l'argument min_count_per_level (doit être > 1).
adh = evident . UnivariateDataHandler ( faith_pd , metadata )Supposons ensuite que nous souhaitions obtenir l’ampleur de l’effet des différences de diversité entre deux groupes d’échantillons. Nous avons dans notre exemple une colonne dans les métadonnées « classification » comparant deux groupes de patients atteints de la maladie de Crohn. Tout d’abord, nous examinerons la moyenne du PD de Faith entre ces deux groupes.
metadata . groupby ( "classification" ). agg ([ "count" , "mean" , "std" ])[ "faith_pd" ]ce qui aboutit à
count mean std
classification
B1 99 13.566110 3.455625
Non-B1 121 9.758946 3.874911
On dirait qu'il y a une assez grande différence entre ces deux groupes. Ce que nous aimerions faire maintenant, c’est calculer l’ampleur de l’effet de cette différence. Comme nous ne comparons que deux groupes, nous pouvons utiliser le d de Cohen. Evident choisit automatiquement la taille d'effet correcte à calculer - soit le d de Cohen s'il n'y a que deux catégories, soit le f de Cohen s'il y en a plus de 2.
adh . calculate_effect_size ( column = "classification" )Cela nous indique que notre taille d’effet est de 1,03.
Supposons maintenant que nous voulions voir de combien d’échantillons nous avons besoin pour pouvoir détecter cette différence avec une puissance de 0,8. Evident vous permet de spécifier facilement des arguments pour les observations alpha, de puissance ou totales pour l'analyse de puissance. Nous pouvons ensuite tracer ces résultats sous forme de courbe de puissance pour résumer les données.
from evident . plotting import plot_power_curve
import numpy as np
alpha_vals = [ 0.01 , 0.05 , 0.1 ]
obs_vals = np . arange ( 10 , 101 , step = 10 )
results = adh . power_analysis (
"classification" ,
alpha = alpha_vals ,
total_observations = obs_vals
)
plot_power_curve ( results , target_power = 0.8 , style = "alpha" , markers = True )Lorsque nous inspectons ce graphique, nous pouvons voir combien d’échantillons nous aurions besoin de collecter pour observer la même taille d’effet à différents niveaux de signification et de puissance.
Evident permet aux utilisateurs d'effectuer de manière interactive des calculs de taille et de puissance d'effet à l'aide de Bokeh. Pour créer une application Bokeh, utilisez la commande suivante :
from evident . interactive import create_bokeh_app
create_bokeh_app ( adh , "app" ) Cela enregistrera les fichiers nécessaires dans un nouveau répertoire app/ . Accédez au répertoire contenant app/ ( pas app/ lui-même) et exécutez cette commande depuis votre terminal :
bokeh serve --show app
Cela devrait ouvrir une fenêtre de navigateur avec les visualisations interactives. L'onglet "Résumé" donne un aperçu des données et des tailles/puissances d'effet. Des barplots montrant les tailles d'effet des métadonnées pour les catégories binaires et multi-classes (classées par ordre décroissant) sont affichés. Sur la droite se trouve une courbe de puissance dynamique montrant l'analyse de puissance des colonnes de métadonnées. Le niveau de signification, la plage d'observation totale et les colonnes choisies peuvent être modifiés à l'aide du panneau de commande sur le côté gauche de l'onglet.
Passez à l'onglet "Données" en utilisant la barre en haut. Ici, vous pouvez voir des diagrammes en boîte des données pour chaque catégorie de métadonnées. Sélectionnez une colonne dans la liste déroulante pour modifier les données affichées. Vous pouvez également cocher la case « Afficher les points de dispersion » pour superposer les données brutes sur les boîtes à moustaches.
Notez que, étant donné qu'Evident utilise Python pour effectuer les calculs de puissance, il n'est pour le moment pas possible d'intégrer cette application interactive dans une page Web autonome.
Evident prend en charge le cadre populaire QIIME 2 d'analyse des données du microbiome. Nous supposons dans ce didacticiel que vous êtes familiarisé avec l'utilisation de QIIME 2 en ligne de commande. Sinon, nous vous recommandons de lire l'excellente documentation avant de commencer avec Evident. Notez que nous avons testé Evident uniquement sur QIIME 2 version 2021.11. Si vous utilisez une version différente et rencontrez une erreur, veuillez nous en informer via un problème.
Pour calculer la puissance, nous pouvons exécuter la commande suivante :
qiime evident univariate-power-analysis
--m-sample-metadata-file metadata.qza
--m-sample-metadata-file faith_pd.qza
--p-data-column faith_pd
--p-group-column classification
--p-alpha 0.01 0.05 0.1
--p-total-observations $(seq 10 10 100)
--o-power-analysis-results results.qza
Nous fournissons plusieurs exemples de fichiers de métadonnées à QIIME 2 car ils sont fusionnés en interne. Vous devez fournir une valeur pour --p-data-column afin qu'Evident sache quelle colonne des métadonnées fusionnées contient les valeurs numériques (cela n'est nécessaire que pour une analyse univariée). Dans ce cas, le nom du vecteur faith_pd.qza est faith_pd , nous l'utilisons donc comme entrée.
Remarquez comment nous avons utilisé $(seq 10 10 100) pour fournir une entrée dans l'argument --p-total-observations . seq est une commande sur les systèmes de type UNIX qui génère une séquence de nombres. Dans notre exemple, nous avons utilisé seq pour générer les valeurs de 10 à 100 par intervalles de 10 (10, 20, ..., 100).
Avec cet artefact de résultats, nous pouvons visualiser la courbe de puissance pour avoir une idée de la façon dont la puissance varie en fonction du nombre d'observations et du niveau de signification. Exécutez la commande suivante :
qiime evident plot-power-curve
--i-power-analysis-results results.qza
--p-target-power 0.8
--p-style alpha
--o-visualization power_curve.qzv
Vous pouvez visualiser cette visualisation sur view.qiime2.org directement dans votre navigateur.
Evident prend en charge la parallélisation des calculs de taille d'effet via joblib. La parallélisation est effectuée sur différentes colonnes lors de l'utilisation effect_size_by_category et pairwise_effect_size_by_category . Envisagez la parallélisation si vous avez de nombreux échantillons et/ou de nombreuses catégories de métadonnées différentes qui vous intéressent. Par défaut, aucune parallélisation n'est effectuée.
Avec Python :
from evident . effect_size import effect_size_by_category
effect_size_by_category (
adh ,
[ "classification" , "cd_resection" , "cd_behavior" ],
n_jobs = 2
)Avec QIIME2 :
qiime evident univariate-effect-size-by-category
--m-sample-metadata-file metadata.qza
--m-sample-metadata-file faith_pd.qza
--p-data-column faith_pd
--p-group-columns classification sex cd_behavior
--p-n-jobs 2
--o-effect-size-results alpha_effect_sizes.qza
Si vous rencontrez un bug dans Evident, veuillez publier un problème GitHub et nous y répondrons dès que possible. Nous sommes ouverts à toutes les idées ou mises à jour/correctifs de la documentation, veuillez donc soumettre un problème et/ou une pull request si vous avez des idées pour améliorer Evident.
Si votre question concerne la version QIIME 2 d'Evident, pensez à la publier sur le forum QIIME 2. Vous pouvez ouvrir un ticket sur le forum Community Plugin Support et taguer @gibsramen si nécessaire.
Si vous utilisez Evident dans votre travail, veuillez citer notre prépublication sur bioRxiv.
