sample.suff                package:unknown                R Documentation

SUFICIÊNCIA AMOSTRAL PARA ESTIMATIVAS DE DIVERSIDADE GENÉTICA

Description:

     Função para avaliar se, dado o número de indivíduos diplóides amostrados, o esforço amostral foi suficiente 
     para inferir a diversidade genética de populações, a partir de marcadores microssatélites genotipados. Há três
     opções para a estimativa de diversidade genética:heterozigosidade esperada, observada ou a riqueza alélica. A 
     função retorna um gráfico de rarefação com a média estimativa de diversidade genética simulada em função do 
     tamanho amostral da população (podendo ou não incluir o intervalo de confiança das estimativas). Note que o 
     tempo para executar a função sample.suff dependerá do número de simulações definido pelo usuário (nsim), sendo 
     que quanto maior nsim, mais tempo a função demorará para terminar sua execução.	 
	 
Usage:

     sample.suff (dados, col.ID, col.pop, col.loci, na.code=NA, IC.plot=TRUE, gen.div=c("He","Ho","Ar"), nsim=1000)

Arguments:

    dados     data frame com um indivíduo por linha e um locus por coluna, com alelos separados por /. Além disso, 
              data frame deve ter uma coluna com identificação dos indivíduos e outra com identificação das 
              populações.
    col.ID    número da coluna com identificação dos indivíduos (deve ser um número inteiro maior que 0).
    col.pop   número da coluna com identificação da população a qual os indivíduos pertencem (deve ser um número 
              inteiro maior que 0).
    col.loci  intervalo das colunas correspondentes aos loci microssatélite genotipados (deve ser um número inteiro 
              maior que 0). Note que a função foi elaborada para espécies diplóides. Portanto, cada loco deve conter 
              dois alelos.
    na.code   código utilizado para valores faltantes (Default = NA; neste caso, valores faltantes no data frame 
              dados não recebem nenhum valor ou código). Para evitar conflitos com o R, não utilizar "NA" como 
              código para dados faltantes.
    IC.plot   vetor lógico que indica se intervalos de confiança devem ou não ser plotados (Default = TRUE).
    gen.div   estimativa de diversidade genética a ser calculada, podendo ser heterozigosidade esperada e observada 
              (He e Ho, respectivamente) e riqueza alélica (Ar).
    nsim      número de simulações (Default = 1000).  

Details:

    Veja a seção Examples desta página de ajuda para obter um exemplo de data frame a ser utilizado como argumento 
    dados da função.

Value:

    A função retorna:
	(1) Gráfico de rarefação com estimativa de diversidade genética simulada em função do tamanho amostral da 
            população (podendo ou não incluir o intervalo de confiança das estimativas). Neste gráfico, cada 
            população é representada por uma cor diferente. As linhas representam a média da estimativa de 
            diversidade genética para cada população nos cenários simulados e a área sombreada o intervalos de 
            confiança referentes às estimativas.
        (2) Uma lista contendo:
	    comp1: data frame com estimativa de diversidade genética observada para as populações 
	    comp2: data frame com média e intervalos de confiança superior e inferior da estimativa de diversidade 
                   genética para cada população em cenários simulados com diferentes números de indivíduos. 

Warning:

    (1) Para evitar conflitos com o R, não utilizar na.code = "NA" 
    (2) Caso argumentos da função sejam inseridos incorretamente, a função não será executada, retornando mensagens 
        de erro.
    (3) O tempo para executar a função sample.suff dependerá do número de simulações definido pelo usuário (nsim), 
        sendo que quanto maior nsim, mais tempo a função demorará para terminar sua execução. Sugere-se, portanto, 
        testar previamente a executabilidade da função com baixo nsim (<20). Uma vez atestada positivamente sua 
        execução, definir nsim com valor maior ou igual a 1000. Caso nsim seja menor que 1000, função executará, mas 
        retornará um warning "Um número baixo de simulações pode afetar a confiabilidade dos resultados!"
    (4) A função sample.suff precisa do pacote 'adegenet' (Jombart 2008) para executar. Portanto, sua instalação é 
        necessária antes da execução de sample.suff
	
Author(s):

    Marianne Azevedo Silva
    E-mail: azevedosilva.m@gmail.com

References:

    Jombart T. (2008) adegenet: a R package for the multivariate analysis of genetic markers. Bioinformatics 24: 
    1403-1405. DOI:10.1093/bioinformatics/btn129
	
    Mori GM, Zucchi MI, Souza AP (2015) Multiple-Geographic-Scale Genetic Structure of Two Mangrove Tree Species: 
    The Roles of Mating System, Hybridization, Limited Dispersal and Extrinsic Factors. PLoS ONE 10: e0118710. 
    DOI:10.1371/journal.pone.0118710

See Also:

    pacote adegenet para compreender algumas funções incorporadas na função sample.suff

Examples:

    # Exemplo de estruturação de dataset. Este exemplo é um subconjunto do dataset disponível no trabalho de Mori et 
    # al. 2015 PLoS ONE 10(2): e0118710.
    print(data.frame(ID=c("AsAJU01","AsAJU02","AsAJU03"), pop=rep("Braganca-PA",3), 
    locus01=c("221/221","223/223","225/219"), locus02=c("150/150","148/150","148/148"), 
    locus03=c("213/213","","227/233")),row.names=F)
    # Exemplos de uso da função (nos dois exemplos, nsim foi deixado como 10 para que o exemplo execute mais 
    # rapidamente. Para uma análise com maior confiabilidade nsim deve ser maior ou igual a 1000
    # Exemplo1:
    # Gerar gáfico de rarefação, com intervalos de confiança, para as estimativas de heterozigosidade esperada em 
    # cenários simulados 
    # Carregar dados. Esses dados também são oriundos do dataset disponível no trabalho de Mori et al. 2015 PLoS ONE 
    # 10(2): e0118710
    dados <- read.table("dados-exemplo.txt", header = T,sep="\t",as.is = F)
    # Ver estrutura dos dados
    str(dados)
    # Executar função sample.suff
    sample.suff(dados, col.ID=1, col.pop=2, col.loci=3:14, na.code=NA, IC.plot=TRUE, gen.div="He", nsim=10)
    # Exemplo2:
    # Gerar gáfico de rarefação, sem intervalos de confiança, para as estimativas de riqueza alélica em cenários 
    # simulados 
    # Executar função sample.suff
    sample.suff(dados, col.ID=1, col.pop=2, col.loci=3:14, IC.plot=FALSE, gen.div="Ar", nsim=10)

• Este documento contém o mesmo conteúdo acima, porém armazenado em um arquivo .txt:Help-Função sample.suff
• Este documento contém um dataset¹⁾ para ser usado como no exemplo de execução da função, presente na página de ajuda da mesma. Trata-se de um arquivo cujo nome é dados-exemplo.txt e que deve estar presente no diretório de trabalho caso o usuário desejo executar o exemplo do help:Dataset-Exemplo-Função sample.suff