pop.handling					package: -					R Documentation


Extrair indivíduos/SNPs e seus respectivos dados de um arquivo independente da formatação da estrutura do arquivo, portanto que seja matriz/dataframe. 


Description:
	
	A função requer dois arquivos de entrada - uma matriz/dataframe e uma lista de identificadores - e a determinação do eixo
	do vetor onde estão os indivíduos/SNPs. A partir da posição do vetor na matriz definida pelo usuário, compara-se e extrai
	apenas os indivíduos/SNPs presentes na lista de comparação, e todos os seus dados associados. Argumentos adicionais incluem
	manipulação de NAs, comparação gráfica entre os dataframes (entrada/saída) e possibilidar de salvar diretamente o novo dataframe.

Usage:

	pop.hanlding(data,axis,list.names, na.omit = F, na.start = 1, graph= F, out= F)


Arguments:

	data: matriz ou data.frame.
	axis: "c:i" ou "l:i", onde "c" determina que o vetor de nomes para o match está em coluna no dataframe, "l" indica que está em linha,
	e "i" deve ser um número inteiro indicando a posição ordinal da coluna/linha onde se encontra o vetor.
	list.names: vetor com os nomes do match de interesse.
	na.omit: omite NAs se o parâmetro for TRUE (padrão = FALSE), podendo ainda o usário definir um número (e.g. zero) que será considerado como NA.
	na.start: determina a partir de que linha/coluna os NAs serão considerados para quantificação/omissão.
	graph: se verdadeiro (TRUE), geram gráficos de comparação entre as IDs e NAs dos data.framas de entrada e de saída (padrão = FALSE).
	out: deve ser um vetor com único valor da classe caractere indicando o path e nome do arquivo a ser salvo (padrão = FALSE).
		


Details:

	A função utiliza apenas as funções básicas do R internamente, e exige obrigatoriamente os dois arquivos de entrada, que são um data.frame
	e a lista de nomes (indivíduos/SNPs), bem como o argumento "axis" informando o eixo no data.frame onde se encontra o vetor de nomes para 
	comparação e extração dos dados. Os demais argumentos são opcionais.

Value:	

	Ao final será gerado um novo data.frame com os dados exclusivos de interesse do usuário, com base em sua lista de indivíduos/SNPs/nomes e 
	toda a informação a eles associadas. Opcionalmente, pode-se salvar diretamente indicando o path na própria função, e visualizar os gráficos
	de comparação entre ambos os data.frames.

Warnings:

	Os argumentos "na.omit", bem como seus associados "na.start" e "graph" foram introduzidos com fins didáticos da disciplina e que podem ser 
	utilizados eficientemente em data.frames convencionais. Arquivos originais em genética populacional, entretanto, costumam ser extensos, e ter
	muitos ou mesmo nenhum NA, sendo um conhecimento prévio da estrutura do arquivo a ser trabalho é importante para o uso de tais argumentos.
	O argumento "out" possibilita ao usuário definir o destino e nome do arquivo, mas não sua formatação. A formatação padrão que foi definida 
	pela função write.table() baseia-se em arquivos .ped .thap e vcf, convencionais em genética de população. Para definir parâmetros, aconselha-se
	salvar o resultado da função em um objeto e então chamar a função write.table() com os parâmetros desejados.
	
	Dependendo do tamanho do arquivo, a função chamada pelo argumento out pode demorar para terminar sua execução.  

Author

	Cainã Max Couto-Silva
	cmcouto.silva@usp.br

References:

	https://www.cog-genomics.org/plink2/formats#ped
	
Examples:

#Faça o download dos arquivos em seu diretório de trabalho

#Importando arquivos para o R
ped.file = read.table("hapmap1.ped", as.is = T) #data.frame com dados de SNP-array de populações japonesas e chineasas;
map.file = read.table("hapmap1.map", as.is = T) #informações sobre os SNPs do arquivo ped (arquivo complementar), apenas por curiosidade;
ped.resized= read.table("hapmap1_resized.ped", as.is = T) #dataframe draticamente reduzido para mostrar ação dos argumentos que manipulam NAs;
japonese= read.table("japonese.txt") #lista dos nomes dos indivíduos japoneses
chinese= read.table("chinese.txt")  #lista dos nomes dos indivíduos chineses

#Utilização da função
ped_japonese= pop.handling(ped.file,"c:1",japonese) #argumentos básicos - extração dos dados da população japonesa;
ped_chinese= pop.handling(data = ped.resized, axis = "c:1", list.names = chinese, na.omit = 0, na.start = 7, graph = T, out = "./arquivoteste.txt") #argumentos completos - extração dos dados da população japonesa, remoção dos NAs (0 representando os NAs neste caso), considerando apenas os zeros/NAs após a sexta coluna (a partir da sétima), comparação gráfico e arquivo-resultado salvo na pasta local com o nome "arquivoteste.txt".