NcmStatsVec

NcmStatsVec — An online statistics vector.

Properties

guint length Read / Write / Construct Only
gboolean save-x Read / Write / Construct Only
NcmStatsVecType type Read / Write / Construct Only

Types and Values

Object Hierarchy

    GEnum
    ╰── NcmStatsVecType
    GObject
    ╰── NcmStatsVec

Description

This object calculates some basic statistics (mean, variance and covariance) of a set of random variables.

The mean can be calculated online using the following formula: $$\bar{x}_n = \bar{x}_{n-1} + (x_n - \bar{x}_{n-1})\frac{w_n}{W_n},$$ where $\bar{x}_n$ is the mean calculated using the first $n$ elements, $x_n$ is the $n$-th element, $w_n$ the $n$-th weight and finally $W_n$ is the sum of the first $n$ weights.

Using the expressions above we obtain the variance from as following: $$M_n = M_{n-1} + (x_n - \bar{x}_{n-1})^2w_n\frac{W_{n-1}}{W_n},$$ where the variance of the first $n$ elements is $$V_n = \frac{M_n}{W^\text{bias}_{n}}, \quad W^\text{bias}_{n} \equiv \frac{W_n^2 - \sum^n_iw_i^2}{W_n}.$$ In the formula above we defined the bias corrected weight $W^\text{bias}_{n}$.

Finally, the covariance is computed through the following expression: $$N(x,y)_n = N(x,y)_{n-1} + (x_n - \bar{x}_n)(y_n - \bar{y}_{n-1})w_n,$$ where the covariance of two variables $x$, $y$ is given by $$Cov(x,y)_n = \frac{N(x,y)_n}{W^\text{bias}_{n}}.$$

Example 5. Using a NcmStatsVec.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Creates a new one dimensional NcmStatsVec to calculates mean and variance.
NcmStatsVec *svec = ncm_stats_vec_new (1, NCM_STATS_VEC_VAR, FALSE); 

// Set and update three different values of the only random variable.
ncm_stats_vec_set (svec, 0, 1.0);
ncm_stats_vec_update (svec);
ncm_stats_vec_set (svec, 0, 2.0);
ncm_stats_vec_update (svec);
ncm_stats_vec_set (svec, 0, 1.5);
ncm_stats_vec_update (svec);

{
  gdouble mean = ncm_stats_vec_get_mean (svec, 0);
  gdouble var = ncm_stats_vec_get_var (svec, 0);
  ...
}

Functions

ncm_stats_vec_new ()

NcmStatsVec *
ncm_stats_vec_new (guint len,
                   NcmStatsVecType t,
                   gboolean save_x);

Creates a new NcmStatsVec.

Parameters

len

number of random variables.

 

t

type of statistics to be calculated.

 

save_x

whenever to save each vector x.

 

Returns

FIXME.

[transfer full]


ncm_stats_vec_ref ()

NcmStatsVec *
ncm_stats_vec_ref (NcmStatsVec *svec);

Increase the reference of svec by one.

Parameters

svec

a NcmStatsVec.

 

Returns

svec .

[transfer full]


ncm_stats_vec_free ()

void
ncm_stats_vec_free (NcmStatsVec *svec);

Decrease the reference count of svec by one.

Parameters

svec

a NcmStatsVec.

 

ncm_stats_vec_clear ()

void
ncm_stats_vec_clear (NcmStatsVec **svec);

Decrease the reference count of svec by one, and sets the pointer *svec to NULL.

Parameters

svec

a NcmStatsVec.

 

ncm_stats_vec_reset ()

void
ncm_stats_vec_reset (NcmStatsVec *svec);

Reset all data in svec .

Parameters

svec

a NcmStatsVec.

 

ncm_stats_vec_update_weight ()

void
ncm_stats_vec_update_weight (NcmStatsVec *svec,
                             gdouble w);

Updates the statistics using svec->x set in svec and weight , then reset svec->x to zero.

Parameters

svec

a NcmStatsVec.

 

w

The statistical weight.

 

ncm_stats_vec_append ()

void
ncm_stats_vec_append (NcmStatsVec *svec,
                      NcmVector *x,
                      gboolean dup);

Appends and updates the statistics using the vector x NcmVector of same size “length” and with continuous allocation. i.e., NcmVector:stride == 1.

If svec was created with save_x TRUE, the paramenter dup determines if the vector x will be duplicated or if just a reference for x will be saved.

Parameters

svec

a NcmStatsVec.

 

x

a NcmVector to be added.

 

dup

a gboolean.

 

ncm_stats_vec_prepend ()

void
ncm_stats_vec_prepend (NcmStatsVec *svec,
                       NcmVector *x,
                       gboolean dup);

Prepends and updates the statistics using the vector x and weight == 1.0. It assumes that NcmVector is of same size “length” and with continuous allocation. i.e., NcmVector:stride == 1.

If svec was created with save_x TRUE, the paramenter dup determines if the vector will be duplicated or if just a reference for x will be saved.

Parameters

svec

a NcmStatsVec.

 

x

a NcmVector to be added.

 

dup

a boolean.

 

ncm_stats_vec_append_data ()

void
ncm_stats_vec_append_data (NcmStatsVec *svec,
                           GPtrArray *data,
                           gboolean dup);

Appends and updates the statistics using the data contained in data and weight == 1.0. It assumes that each element of data is a NcmVector of same size “length” and with continuous allocation. i.e., NcmVector:stride == 1.

If svec was created with save_x TRUE, the paramenter dup determines if the vectors from data will be duplicated or if just a reference for the current vectors in data will be saved.

Parameters

svec

a NcmStatsVec.

 

data

a GPtrArray containing NcmVector s to be added.

[element-type NcmVector]

dup

a gboolean.

 

ncm_stats_vec_prepend_data ()

void
ncm_stats_vec_prepend_data (NcmStatsVec *svec,
                            GPtrArray *data,
                            gboolean dup);

Prepends and updates the statistics using the data contained in data and weight == 1.0. It assumes that each element of data is a NcmVector of same size “length” and with continuous allocation. i.e., NcmVector:stride == 1.

If svec was created with save_x TRUE, the paramenter dup determines if the vectors from data will be duplicated or if just a reference for the current vectors in data will be saved.

Parameters

svec

a NcmStatsVec.

 

data

a GPtrArray containing NcmVector s to be added.

[element-type NcmVector]

dup

a boolean.

 

ncm_stats_vec_get_autocorr ()

NcmVector *
ncm_stats_vec_get_autocorr (NcmStatsVec *svec,
                            guint p);

Calculates the autocorrelation vector, the j-th element represent the selfcorrelation with lag-j.

The returning vector use the internal memory allocation and will change with subsequent calls to ncm_stats_vec_get_autocorr().

Parameters

svec

a NcmStatsVec.

 

p

parameter id.

 

Returns

a read only autocorrelation vector.

[transfer full]


ncm_stats_vec_get_subsample_autocorr ()

NcmVector *
ncm_stats_vec_get_subsample_autocorr (NcmStatsVec *svec,
                                      guint p,
                                      guint subsample);

Calculates the autocorrelation vector, the j-th element represent the selfcorrelation with lag-j using the subsample parameter.

The returning vector use the internal memory allocation and will change with subsequent calls to ncm_stats_vec_get_autocorr().

Parameters

svec

a NcmStatsVec.

 

p

parameter id.

 

subsample

size of the subsample (>0).

 

Returns

a read only autocorrelation vector.

[transfer full]


ncm_stats_vec_get_autocorr_tau ()

gdouble
ncm_stats_vec_get_autocorr_tau (NcmStatsVec *svec,
                                guint p,
                                guint max_lag,
                                const gdouble min_rho);

Calculates the integrated autocorrelation time for the parameter p using all rows of data.

If max_lag is 0 or larger than the current number of itens than it use the current number of itens as max_lag .

Parameters

svec

a NcmStatsVec.

 

p

parameter id.

 

max_lag

max lag in the computation.

 

min_rho

minimum autocorrelation to be considered in the sum.

 

Returns

the integrated autocorrelation time of the whole data.


ncm_stats_vec_get_subsample_autocorr_tau ()

gdouble
ncm_stats_vec_get_subsample_autocorr_tau
                               (NcmStatsVec *svec,
                                guint p,
                                guint subsample,
                                guint max_lag,
                                const gdouble min_rho);

Calculates the integrated autocorrelation time for the parameter p using the subsample parameter.

Parameters

svec

a NcmStatsVec.

 

p

parameter id.

 

subsample

size of the subsample (>0).

 

max_lag

max lag in the computation.

 

min_rho

minimum autocorrelation to be considered in the sum.

 

Returns

the integrated autocorrelation time of data with subsample .


ncm_stats_vec_peek_x ()

NcmVector *
ncm_stats_vec_peek_x (NcmStatsVec *svec);

Returns the vector containing the current value of the random variables.

Parameters

svec

a NcmStatsVec.

 

Returns

the random variables vector.

[transfer none]


ncm_stats_vec_set ()

void
ncm_stats_vec_set (NcmStatsVec *svec,
                   guint i,
                   gdouble x_i);

Sets the value of the current i -th random variable to x_i .

Parameters

svec

a NcmStatsVec.

 

i

a variable index.

 

x_i

the value of the i -th variable.

 

ncm_stats_vec_get ()

gdouble
ncm_stats_vec_get (NcmStatsVec *svec,
                   guint i);

Returns the value of the current i -th random variable.

Parameters

svec

a NcmStatsVec.

 

i

a variable index.

 

Returns

i -th random variable.


ncm_stats_vec_update ()

void
ncm_stats_vec_update (NcmStatsVec *svec);

Same as ncm_stats_vec_update_weight() assuming weigth equal to one.

Parameters

svec

a NcmStatsVec.

 

ncm_stats_vec_get_mean ()

gdouble
ncm_stats_vec_get_mean (NcmStatsVec *svec,
                        guint i);

Return the current value of the variable mean, i.e., $\bar{x}_n$.

Parameters

svec

a NcmStatsVec.

 

i

a variable index.

 

Returns

$\bar{x}_n$.


ncm_stats_vec_get_var ()

gdouble
ncm_stats_vec_get_var (NcmStatsVec *svec,
                       guint i);

Return the current value of the variable variance, i.e., $Var_n$.

Parameters

svec

a NcmStatsVec.

 

i

a variable index.

 

Returns

$Var_n$.


ncm_stats_vec_get_sd ()

gdouble
ncm_stats_vec_get_sd (NcmStatsVec *svec,
                      guint i);

Return the current value of the variable standard deviation, i.e., $\sigma_n \equiv sqrt (Var_n)$.

Parameters

svec

a NcmStatsVec.

 

i

a variable index.

 

Returns

$\sigma_n$


ncm_stats_vec_get_cov ()

gdouble
ncm_stats_vec_get_cov (NcmStatsVec *svec,
                       guint i,
                       guint j);

Return the current value of the variance between the i -th and the j -th variables, i.e., $Cov_{ij}$.

Parameters

svec

a NcmStatsVec.

 

i

a variable index.

 

j

a variable index.

 

Returns

$Cov_{ij}$.


ncm_stats_vec_get_cor ()

gdouble
ncm_stats_vec_get_cor (NcmStatsVec *svec,
                       guint i,
                       guint j);

Return the current value of the correlation between the i -th and the j -th variables, i.e., $$Cor_{ij} \equiv \frac{Cov_{ij}}{\sigma_i\sigma_j}.$$

Parameters

svec

a NcmStatsVec.

 

i

a variable index.

 

j

a variable index.

 

Returns

$Cor_{ij}$.


ncm_stats_vec_get_weight ()

gdouble
ncm_stats_vec_get_weight (NcmStatsVec *svec);

Return the current value of the weight, for non-weighted means this is simply the number of elements.

Parameters

svec

a NcmStatsVec.

 

Returns

$W_n$.


ncm_stats_vec_get_mean_vector ()

void
ncm_stats_vec_get_mean_vector (NcmStatsVec *svec,
                               NcmVector *mean,
                               guint offset);

Copy the current value of the means to the vector mean starting from parameter offset .

Parameters

svec

a NcmStatsVec.

 

mean

a NcmVector.

 

offset

first parameter index.

 

ncm_stats_vec_get_cov_matrix ()

void
ncm_stats_vec_get_cov_matrix (NcmStatsVec *svec,
                              NcmMatrix *m,
                              guint offset);

Copy the current value of the correlation between the variables to the matrix m starting from paramenter offset .

Parameters

svec

a NcmStatsVec.

 

m

a NcmMatrix.

 

offset

first parameter index.

 

ncm_stats_vec_peek_cov_matrix ()

NcmMatrix *
ncm_stats_vec_peek_cov_matrix (NcmStatsVec *svec,
                               guint offset);

Gets the internal covariance matrix starting from paramenter offset . This is the internal matrix of svec and can change with further additions to svec . It is not guaranteed to be valid after new additions.

Parameters

svec

a NcmStatsVec.

 

offset

first parameter index.

 

Returns

the covariance matrix.

[transfer none]


ncm_stats_vec_peek_row ()

NcmVector *
ncm_stats_vec_peek_row (NcmStatsVec *svec,
                        guint i);

The i-th data row used in the statistics, this function fails if the object was not created with save_x == TRUE;

Parameters

svec

a NcmStatsVec.

 

i

the row's index.

 

Returns

the i-th data row.

[transfer none]


ncm_stats_vec_get_param_at ()

gdouble
ncm_stats_vec_get_param_at (NcmStatsVec *svec,
                            guint i,
                            guint p);

Gets the p-th parameter in the i-th data row used in the statistics, this function fails if the object was not created with save_x == TRUE;

Parameters

svec

a NcmStatsVec.

 

i

the row's index.

 

p

the parameter's index.

 

Returns

the parameter value.

Types and Values

enum NcmStatsVecType

FIXME

Members

NCM_STATS_VEC_MEAN

Calculates mean only.

 

NCM_STATS_VEC_VAR

Calculates mean and variance.

 

NCM_STATS_VEC_COV

Calculates mean, variance and covariance.

 

Property Details

The “length” property

  “length”                   guint

Number of random variables.

Flags: Read / Write / Construct Only

Allowed values: >= 1

Default value: 1


The “save-x” property

  “save-x”                   gboolean

Whenever to save each vector x through each interation.

Flags: Read / Write / Construct Only

Default value: FALSE


The “type” property

  “type”                     NcmStatsVecType

The statistics to be calculated.

Flags: Read / Write / Construct Only

Default value: NCM_STATS_VEC_MEAN