geo.coordinates              package:nenhum               R Documentation

Coordenadas geográficas no Brasil. Mapa de distribuição.

Description:

  geo.coordinates procura pelos nomes de localidades brasileiras no banco de dados GEONet Names Server (GNS).
  É possível escolher a unidade das coordenadas geográficas que serão obtidas e, caso escolhida a decimal, a função utiliza elementos gráficos para auxiliar na desambiguação de localidades.
  A função ainda produz um mapa final com a distribuição das localidades (para coordenadas em decimal). Necessária a instalação dos pacotes sp e maptools.

Usage:

  geo.coordinates(x, output="Output", unit="dec", type=F, short=F, generic=F, class=F, elev=F, note=F)

Arguments:

  x		caráter. Interpretado como nome do arquivo de entrada se houver apenas um elemento. Deve ser uma tabela em formato de texto com apenas uma coluna contendo cabeçalho e os nomes das localidades de interesse. Ver Examples.
			 Interpretado como um vetor contendo os nomes das localidades se tiver mais de um elemento.

  output	caráter. Nome do arquivo que será produzido. Não colocar a extensão. Ver Value.

  unit		caráter. Unidade das coordenadas geográficas. Default: dec (decimal). Permite a construção de mapas temporários para auxiliar na determinação das localidade e de um mapa final com a distribuição dos pontos de interesse.
		Opções são dms (graus, minutos, segundos) ou mgrs (Military Grid Reference System). Não permitem a construção de mapas. Ver Value para interpretação dos resultados.

  type		lógico. Classificação do nome da localidade. Se TRUE, é inserido como coluna adicional no output. Ver Value para legenda dos resultados.

  short		lógico. Abreviação do nome da localidade. Se TRUE, é inserido como coluna adicional no output.

  generic	lógico. Descrição da localidade (como Rio, Fazenda etc). Se TRUE, é inserido como coluna adicional no output.

  class		lógico. Classificação da localidade. Se TRUE, é inserido como coluna adicional no output. Ver Value para legenda dos resultados.

  elev		lógico. Altitude em metros. Se TRUE, é inserido como coluna adicional no output.

  note		lógico. Observações do banco de dados sobre a localidade. Se TRUE, é inserido como coluna adicional no output.

Details:

  É recomendada a utilização de unit="dec" (unidade decimal das coordenadas) para que seja possível a construção de mapas temporários que ajudem na identificação das localidades. Para tal, os pacotes sp e maptools devem ser previamente instalados.
  Por padrão, os argumentos type, short, generic, class, elev e note não são considerados na função. De acordo com o interesse nas informações, uma coluna para cada um deles pode ser adicionada inserindo TRUE nos respectivos argumentos.
  geo.coordinates salva o banco de dados baixado do GEONet Names Serves e os shapefiles do mapa do Brasil numa pasta chamada "zip" automaticamente criada dentro do diretório de trabalho. Manter a pasta "zip" torna a função mais rápida para utilização consecutiva.

Value:

  geo.coordinates retorna um data.frame com os seguintes componentes nas colunas:

	original	nomes originais das localidades (fornecidos no argumento x)
	
	full		nomes como encontrados no banco de dados GNS
	
	lat_dec		latitude em graus decimais (± dd.dddddd); sem sinal (+) = Norte, sinal negativo (-) = Sul.
	
	long_dec	longitude em graus decimais (± dd.dddddd); sem sinal (+) = Leste, sinal negativo (-) = Oeste.
	
	lat_dms		latitude em graus, minutos e segundos (±ddmmss); sem sinal (+) = Norte, sinal negativo (-) = Sul.
	
	long_dms	longitude em graus, minutos e segundos (±ddmmss); sem sinal (+) = Leste, sinal negativo (-) = Oeste.
	
	coord_mgrs	coordenadas no sistema militar, sistema alfa-numérico de valores únicos para cada localidade do globo.
	
	type		Classificação do nome da localidade. Legenda:
							C = Conventional
							N = Approved
							NS = Non-roman script
							D = Unverified
							DS = Unverified non-roman script
							H = Historic
							HS = Historic non-roman script
							P = Provisional
							PS = Provisional non-roman script
							V = Variant or alternate
							VA = Anglicized variant
							VS = Variant non-roman script
	
	short		Abreviação dos nomes das localidades.
	
	generic		Descrição da localidade (como Rio, Fazenda etc).
	
	class		Classificação da localidade. Legenda:
							A = Administrative region feature type
							P = Populated place feature type
							V = Vegetation feature type
							L = Locality or area feature type
							U = Undersea feature type
							R = Streets, highways, roads, or railroad feature type
							T = Hypsographic feature type
							H = Hydrographic feature type
							S = Spot feature type
	
	elev		Altitude em metros.
	
	note		Observações encontradas no banco de dados sobre a localidade.

  Mais detalhes em: http://earth-info.nga.mil/gns/html/gis_countryfiles.html

  O data.frame é apresentado na tela ou pode ser salvo em um objeto. Seu conteúdo é salvo em uma tabela no diretório de trabalho em formato de texto (.txt separado por tabulação).
  Se escolhido unit="dec", a função também exporta para o diretório de trabalho um mapa do Brasil (em formato pdf) com as localidade plotadas de forma numérica, com os índices correspondentes aos nomes das localidades nas linhas da tabela produzida.

	
Warning:

  As coordenadas obtidas são originadas do banco de dados GNS. geo.coordinates exibe uma mensagem de aviso quando uma localidade de interesse não é encontrada no banco. Entretanto essas localidades não são inseridas na tabela final produzida.
  Para localidades com múltiplos registros no banco de dados, as opções são exibidas para que o usuário faça a escolha crítica da localidade apropriada.
  As demais informações que podem ser extraídas (altitude, classificação etc) podem não estar presentes para todas as localidades e devem ser analisadas pelo usuário de forma crítica.

Author:

  Tauana Junqueira da Cunha
  
  tauanajc@gmail.com
  tauana.cunha@usp.br

References:

  GEONet Names Server. National Geospatial-Intelligence Agency (NGA). Último acesso em 23 de abril de 2012. Disponível em: http://earth-info.nga.mil/gns/html/index.html

  Hijmans, R. 2012. DIVA-GIS. Último acesso em 23 de abril de 2012. Disponível em: http://www.diva-gis.org/
  
  Download do Banco de Bados do Brasil e outros países em: http://earth-info.nga.mil/gns/html/namefiles.htm

  Download do mapa (shapefile) de divisões políticas do Brasil em: http://www.diva-gis.org/datadown

  "Toponymic information is based on the Geographic Names Database, containing official standard names approved by the United States Board on Geographic Names and maintained by the National Geospatial-Intelligence Agency. More information is available at the Maps and Geodata link at www.nga.mil. The National Geospatial-Intelligence Agency name, initials, and seal are protected by 10 United States Code Section §445."

See Also:

  readShapePoly do pacote maptools (também necessário pacote sp) para a construção do mapa.

Examples:

  geo.coordinates(c("Casa Branca", "Sorocaba", "Tapiraí")) # Fornecendo x como vetor.

  # Baixe o arquivo "Localidades Teste.txt" para rodar os exemplos a seguir e salve-o no diretório de trabalho que será usado no R.
  
  geo.coordinates(x="Localidades Teste.txt", output="Coordenadas Teste", unit="dec", class=T) # Gera tabela com coordenadas em decimais e classificação das localidades e mapa nos arquivos Coordenadas Teste.txt e Coordenadas Teste_Map.pdf

  coordenadas.teste <- geo.coordinates(x="Localidades Teste.txt", unit="dms") # Guarda o data.frame produzido no objeto coordenadas no workspace do R e gera tabela de coordenadas em graus, minutos, segundos salva no arquivo Output.txt