23 N-uplas

Esse capítulo descreve funções para criação e manipulação de n-uplas, conjunto de valores associados a eventos (46). As n-uplas são armazenadas em arquivos. Seus valores podem ser extraídos em qualquer combinação e colocados em um histograma usando um função de seleção.

Os valores a serem armazenados são mantidos em uma estrutura de dados definida pelo usuário, e uma n-upla é criada associando essa estrutura de dados a um arquivo. Os valores são então escritos no arquivo (normalmente dentro de um ciclo) usando as funções de n-uplas descritas abaixo.

A histograma pode ser criado a partir de dados contidos em uma n-upla fornecendo uma função de seleção e uma função de valor. A função de seleção especifica se um evento deve ser incluído no subconjunto a ser analizado ou não. A função de valor calcula a entrada a ser adicionada ao histograma para cada evento.

Todas as funções de n-upla são definidas no arquivo de cabeçalho ‘gsl_ntuple.h’

23.1 A estrutura n-upla

N-uplas são tratadas usando a estrutura gsl_ntuple. Essa estrutura contém informação sobre o arquivo onde os dados da n-upla estão armqzenados, um apontador para a atual linha de dados da n-upla e o tamanho da estrutura de dados da n-upla, tamanho esse que foi definido pelo usuário.

typedef struct {
    FILE * file;
    void * ntuple_data;
    size_t size;
} gsl_ntuple;

23.2 Criando n-uplas

Function: gsl_ntuple * gsl_ntuple_create (char * filename, void * ntuple_data, size_t size)

Essa função cria um novo arquivo de n-upla somente escrita filename para n-uplas de tamanho size e retorna um apontados para a recentemente criada estrutura de n-upla. Qualquer arquivo existente com o mesmo nome é armazenado com comprimento e sobrescrito. Um apontador para memória para a atual linha de n-upla ntuple_data deve ser fornecido—isso é usado para copiar n-uplas do e para o arquivo.

23.3 Abrindo um arquivo existente de n-uplas

Function: gsl_ntuple * gsl_ntuple_open (char * filename, void * ntuple_data, size_t size)

Essa função abre um arquivo de n-upla que já existe chamado filename para leitura e retorna um apontador para a correspondente estrutura de n-upla. As n-uplas no arquivo deve ter tamanho size. Um apontador para memória para a atual linha de n-upla ntuple_data deve ser fornecido—isso é usado para copiar n-uplas do e para o arquivo.

23.4 Escrevendo n-uplas

Function: int gsl_ntuple_write (gsl_ntuple * ntuple)

Essa função escreve a atual n-upla ntuple->ntuple_data de tamanho ntuple->size ao arquivo correspondente.

Function: int gsl_ntuple_bookdata (gsl_ntuple * ntuple)

Essa função é um sinônimo para gsl_ntuple_write.

23.5 Lendo n-uplas

Function: int gsl_ntuple_read (gsl_ntuple * ntuple)

essa função lê a atual linha do arquivo de n-upla para ntuple e armazena dos valores em ntuple->data.

23.6 Fechando um arquivo de n-uplas

Function: int gsl_ntuple_close (gsl_ntuple * ntuple)

Essa função fecha o arquivo de n-upla ntuple e libera sua memória alocada associada.

23.7 Colocando valores das n-uplas no histograma

Uma vez que uma n-upla tenha sido criada seu conteúdo pode ser colocado em um histograma de várias formas usando a função gsl_ntuple_project. Duas funções definidas peo usuário devem ser fornecidos, uma função para selecionar eventos e uma função para calcular valores escalares. A função de seleção e a função de valor ambas aceitam a linha de n-upla como um primeiro argumento e outros parâmetros como um segundo argumento.

A função de seleção determina quais linhas de n-uplas são selecionadas para serem colocadas no histograma. A função de seleção é definida pela seguinte estrutura,

typedef struct {
  int (* function) (void * ntuple_data, void * params);
  void * params;
} gsl_ntuple_select_fn;

A componente de estrutura function deve retornar um valor diferente de zero para cada linha de n-upla que é para ser incluída no histograma.

A função de valor calcula valores escalares para aquelas linhas de n-upla selecionadas pela função de seleção,

typedef struct {
  double (* function) (void * ntuple_data, void * params);
  void * params;
} gsl_ntuple_value_fn;

Nesse caso a componente de estrutura function deve retornar o valor a ser adicionado ao histograma para a linha de n-upla.

Function: int gsl_ntuple_project (gsl_histogram * h, gsl_ntuple * ntuple, gsl_ntuple_value_fn * value_func, gsl_ntuple_select_fn * select_func)

Essa função atualiza o histograma h a partir da n-upla ntuple usando as função value_func e select_func. Para cada linha de n-upla onde a função de seleção select_func for diferentes de zero o correspondente valor daquele linha é calculado usando a função value_func e adicionado ao histograma. aquelas linhas de n-upla onde select_func retorna zero são ignoradas. Novas entradas são adicionadas ao histograma, de forma que chamadas subsequêntes podem ser usadas para acumular dados adicionais no mesmo histograma.

23.8 Exemplos

O seguinte programa exemplo demonstra o uso de n-uplas no gerenciamento de grandes conjuntos de dados. O primeiro programa cria um conjunto de 10,000 “eventos” simulados, cada um com três valores associados (x,y,z). Esses valores são gerados a partir de uma distribuição de Gauss com variância unitária, para propósito de demonstração, e escrito no arquivo de n-upla ‘test.dat’.

#include <gsl/gsl_ntuple.h>
#include <gsl/gsl_rng.h>
#include <gsl/gsl_randist.h>

struct data
{
  double x;
  double y;
  double z;
};

int
main (void)
{
  const gsl_rng_type * T;
  gsl_rng * r;

  struct data ntuple_row;
  int i;

  gsl_ntuple *ntuple 
    = gsl_ntuple_create ("test.dat", &ntuple_row, 
                         sizeof (ntuple_row));

  gsl_rng_env_setup ();

  T = gsl_rng_default; 
  r = gsl_rng_alloc (T);

  for (i = 0; i < 10000; i++)
    {
      ntuple_row.x = gsl_ran_ugaussian (r);
      ntuple_row.y = gsl_ran_ugaussian (r);
      ntuple_row.z = gsl_ran_ugaussian (r);
      
      gsl_ntuple_write (ntuple);
    }
  
  gsl_ntuple_close (ntuple);
  gsl_rng_free (r);

  return 0;
}

O programa seguinte analisa os dados de n-upla no arquivo ‘test.dat’. O procedimento de análise é calcular a soma de quadrados de cada evento, E^2=x^2+y^2+z^2, e selecionar somente aqueles que excederem um limite inferior de 1.5. Os eventos selecionados são então colocados no histograma usando seus valores E^2.

#include <math.h>
#include <gsl/gsl_ntuple.h>
#include <gsl/gsl_histogram.h>

struct data
{
  double x;
  double y;
  double z;
};

int sel_func (void *ntuple_data, void *params);
double val_func (void *ntuple_data, void *params);

int
main (void)
{
  struct data ntuple_row;

  gsl_ntuple *ntuple 
    = gsl_ntuple_open ("test.dat", &ntuple_row,
                       sizeof (ntuple_row));
  double lower = 1.5;

  gsl_ntuple_select_fn S;
  gsl_ntuple_value_fn V;

  gsl_histogram *h = gsl_histogram_alloc (100);
  gsl_histogram_set_ranges_uniform(h, 0.0, 10.0);

  S.function = &sel_func;
  S.params = &lower;

  V.function = &val_func;
  V.params = 0;

  gsl_ntuple_project (h, ntuple, &V, &S);
  gsl_histogram_fprintf (stdout, h, "%f", "%f");
  gsl_histogram_free (h);
  gsl_ntuple_close (ntuple);

  return 0;
}

int
sel_func (void *ntuple_data, void *params)
{
  struct data * data = (struct data *) ntuple_data;  
  double x, y, z, E2, scale;
  scale = *(double *) params;
  
  x = data->x;
  y = data->y;
  z = data->z;

  E2 = x * x + y * y + z * z;

  return E2 > scale;
}

double
val_func (void *ntuple_data, void *params)
{
  struct data * data = (struct data *) ntuple_data;  
  double x, y, z;

  x = data->x;
  y = data->y;
  z = data->z;

  return x * x + y * y + z * z;
}

O seguinte gráfico mostra a distribuição dos eventos selecionados. Note o corte no início do gráfico.

23.9 Referências e Leituras Adicionais

Informação adicional sobre o uso de n-uplas pode ser encontrada na documentação para o pacote CERN PAW e para o pacote CERN HBOOK (disponível online).

Esse documento foi gerado em 23 de Julho de 2013 usando texi2html 5.0.