actograma                        package:unknown                       Documentation

PLOTAGEM DE RITMOS BIOLÓGICOS NA FORMA DE ACTOGRAMA
  
Descrição:

  Função para retornar graficamente dados biológicos ritmicos no formato típico de 
  actograma, comumente utilizado na área de estudos cronobiológicos. O actograma 
  permite combinar os dados de um mesmo indivíduo a diferentes regimes ambientais
  de fotoperíodo (obrigatório) e de temperatura(opcional). Além do gráfico, a função
  retorna o número de dias presente no actograma gerado e uma tabela detalhando os
  regimes cícilos de claro-escuro e de quente-frio declarados para cada data.
  
Uso:
  
  actograma(data_hora, ritmo, n.linhas, Ei, Ef, Fi=rep("00:00:00",n.linhas), 
            Ff=rep("00:00:00",n.linhas))   
  
Argumentos:
 
  data_hora: Vetor contendo valores de data e hora no formato de 'time stamp'
             (mês/dia/ano hora:minutos:segundos).

  ritmo: Vetor contento valores numéricos positivos da variável biológica 
         ritmica observada para cada data_hora.
 
  n.linhas: Valor numérico equivalente à posição da última observação contida no 
            conjunto que deve ser incluído no actograma.
  
  Ei: Vetor contendo os horários de início de escuro para cada observação, no
      formato "hh:mm:ss".
  
  Ef: Vetor contendo os horários de término de escuro para cada observação, no
      formato "hh:mm:ss".
  
  Fi: (Opcional) Vetor contendo os horários de início de frio para cada observação,
      no formato "hh:mm:ss". Quando não informado, assume-se valores "00:00:00".
    
  Ff: (Opcional) Vetor contendo os horários de término de frio para cada observação,
      no formato "hh:mm:ss". Quando não informado, assume-se valores "00:00:00".
  
Detalhes:
   
  O argumento n.linhas pode ser utilizado para selecionar um conjunto dos dados
  desejados, tendo-se em mente que como trata-se de dados temporais em sequência,
  n.linhas se refere à quantidade de observações contidas no intervalo 1:n.linhas,
  ou seja, sempre a partir da primeira observação fornecida.
  
  Caso não sejam fornecidos valores para Fi nem Ff, assume-se um regime de tempera-
  tura constante e o actograma é gerado com as barras referentes aos valores do
  ritmo na cor preta. Na tabela de detalhamento das condições utilizadas, esse tipo
  de regime é indicado como Q:F 24:0.
  
  É possível indicar trechos de temperatura constante utilizando valores iguais para
  Fi e Ff. Dessa forma, pode-se combinar num mesmo actograma regimes térmicos cons-
  tantes e cíclicos.
  
  Da mesma forma para regimes fotoperiódicos (de claro-escuro), é possível indicar
  regime de claro contante ao utilizar valores iguais para Ei e Ef, regime de escuro
  constante ao utilizar Ei="00:00:00" e Ef="23:59:59", ou regime de claro-escuro
  cíclico de acordo com os horários indicados de início e término para cada data.
  Também é possível combinar diferentes condições utilizadas num mesmo actograma.   
  
Valores retornados:

  Actograma duplo do ritmo indicado, representado na forma de barras, combinado a
  regimes de fotoperíodo e temperatura detalhados pelo usuário.
  
  Tabela com detalhamento do regime de claro-escuro descrito para cada dia do acto-
  grama, combinado ao regime de quente-frio quando inserido pelo usuário.

Avisos:

  Valores negativos para o vetor de ritmo são permitidos, embora não sejam represen-
  tados no gráfico e gerem uma mensagem de aviso.
  
  Todas as observações de uma mesma data devem conter os mesmos horários para Ei,
  Ef, Fi ou Ff. A fim de permitir maleabilidade de regimes claro-escuro e quente-
  frio em um mesmo actograma, a inserção correta fica a cargo do usuário.
  Em caso de inserções incorretas, podem haver falhas gráficas no actogtama sem 
  que haja avisos.
      
  A fim de permitir melhor visualização de padrões, as larguras das barras que 
  representam o ritmo no actograma estão configuradas para abranger 500 segundos
  na escala de 24 horas. Em caso de sobreposição de dados nesse intervalo, o acto-
  grama é gerado com mensagens de aviso.
  
  Caso algum dos argumentos seja inserido incorretamente, a função é interrompida
  e traz uma mensagem de erro.
  
Autores:
  
  Beatriz Foganholi Fernandes
  e-mail: beatriz.foganholi.fernandes@usp.br
          beatrizfernandes.bff@gmail.com
  
Referências:
  
  MARQUES, M. D.; GOLOMBEK, D.; MORENO, C. Adaptação Temporal. In: MARQUES, N. &
  MENNA-BARRETO, L. Cronobiologia: princípios e aplicações. São Paulo: Editora 
  Universidade de São Paulo, 1999. p.45-62.
  
Exemplos:
  
  #Representando um actograma com quatro dias, com seis observações equidistantes
  #de ritmo em cada, e diferentes condições de regime claro-escuro e quente-frio:
  
    #Seis horários equidistantes em quatro datas (totalizando 24 observações).
  data_hora <- c("03/29/1995 00:00:00", "03/29/1995 04:00:00",
                 "03/29/1995 08:00:00", "03/29/1995 12:00:00", 
                 "03/29/1995 16:00:00", "03/29/1995 20:00:00", 
                 "03/30/1995 00:00:00", "03/30/1995 04:00:00", 
                 "03/30/1995 08:00:00", "03/30/1995 12:00:00", 
                 "03/30/1995 16:00:00", "03/30/1995 20:00:00", 
                 "03/31/1995 00:00:00", "03/31/1995 04:00:00", 
                 "03/31/1995 08:00:00", "03/31/1995 12:00:00", 
                 "03/31/1995 16:00:00", "03/31/1995 20:00:00", 
                 "04/01/1995 00:00:00", "04/01/1995 04:00:00", 
                 "04/01/1995 08:00:00", "04/01/1995 12:00:00", 
                 "04/01/1995 16:00:00", "04/01/1995 20:00:00")
                 
  #24 valores aleatórios para ritmo.               
  ritmo <- c(abs(rnorm(n=24, mean=10, sd=9)))
  
  #1º dia com regime de claro constante, 2º dia com escuro entre 6h e 18h,
  #3º dia com escuro entre 18h e 6h, 4º dia com escuro constante.
  Ei <- c(rep("00:00:00",6),rep("06:00:00",6),rep("18:00:00",6),rep("00:00:00",6))
  Ef <- c(rep("00:00:00",6),rep("18:00:00",6),rep("06:00:00",6),rep("23:59:59",6))
  
  #1º dia com regime de temperatura constante, 2º dia com frio entre 6h e 18h,
  #3º dia com frio entre 18h e 6h, 4º dia com frio entre 4h e 20h.
  Fi <- c(rep("00:00:00",6),rep("06:00:00",6),rep("18:00:00",6),rep("04:00:00",6))
  Ff <- c(rep("00:00:00",6),rep("18:00:00",6),rep("06:00:00",6),rep("20:00:00",6))
  
  #Executando a função para todos os dados e regimes:
  actograma(data_hora=data_hora,ritmo=ritmo,n.linhas=24,Ei=Ei,Ef=Ef,Fi=Fi,Ff=Ff)
  
  #Executando a função para todos os dados sem fornecer Fi nem Ff:
  actograma(data_hora=data_hora,ritmo=ritmo,n.linhas=24,Ei=Ei,Ef=Ef)
  
  #Executando a função para os 3 primeiros dias, com todos os regimes:
  actograma(data_hora=data_hora,ritmo=ritmo,n.linhas=18,Ei=Ei,Ef=Ef,Fi=Fi,Ff=Ff)
  
  #Executando a função para os 3 primeiros dias, sem fornecer Fi nem Ff:
  actograma(data_hora=data_hora,ritmo=ritmo,n.linhas=18,Ei=Ei,Ef=Ef)