GXST class

class GXST(handle=0)

GXST class.

Mono-variate statistics. The GXST class is used to accumulate statistical information about a set of data. This class is usually used in conjunction with others. For instance, GXDU.stat (see GXDU) will add a channel’s data to the GXST object, and sComputeST_IMG (see GXIMG) will compute statistics for a grid.

Note:

* Histogram ranges and color zone ranges *

Histogram bins are defined with inclusive minima and exclusive maxima; for instance if Min = 0 and Inc = 1, then the second bin would include all values z such that 0 >= z > 1 (the first bin has all values < 0).

Color zones used in displaying grids (GXITR, ZON etc…) are the opposite, with exclusive minima and inclusive maxima. For instance, if a zone is defined from 0 to 1, then it would contain all values of z such that 0 > z >= 1.

These definitions mean that it is impossible to perfectly assign GXITR colors to individual bars of a histogram. The best work-around when the data values are integers is to define the color zones using 0.5 values between the integers. A general work-around is to make the number of histogram bins much larger than the number of color zones.

See also GXST2 (bi-variate statistics)

__init__(handle=0)

classmethod create()

This method creates a statistics object which is used to accumulate statistics.

Returns:

GXST Object

Return type:

GXST

New in version 5.0.

License: Geosoft Open License

classmethod create_exact()

This method creates a statistics object which stores all values.

Returns:

GXST Object

Return type:

GXST

New in version 5.1.8.

License: Geosoft Open License

data(val)

Add this value to the statistics object.

Parameters:

val (float) – Value to Add

New in version 5.0.

License: Geosoft Open License

data_vv(vv)

Add all the values in this GXVV to the statistics object.

Parameters:

vv (GXVV) – GXVV object

New in version 5.0.

License: Geosoft Open License

equivalent_percentile(value)

Return corresponding Percentile for a Value.

Parameters:

value (float) – Input value

Returns:

The percentile at the given value (0 - 100)

Return type:

float

New in version 5.0.8.

License: Geosoft Open License

Note: Statistics and histogram must have been calculated prior to calling this method

equivalent_value(percent)

Return corresponding Value for a Percentile

Parameters:

percent (float) – Input percentile (0 - 100)

Returns:

The value at the given percentile.

Return type:

float

New in version 5.0.8.

License: Geosoft Open License

Note: Statistics and histogram must have been calculated prior to calling this method

get_histogram_bins(vv)

Retrieve number of items in each hostogram bin

Parameters:

vv (GXVV) – GXVV for numbers of items

New in version 6.1.

License: Geosoft Open License

Note: The length of the returned GXVV is set to the total number of bins. If a histogram is not defined in the GXST, then the returned length is zero.

get_histogram_info(div, min, max)

Retrieve number of bins, min and max value in histogram

Parameters:

• div (int_ref) – # of bins

• min (float_ref) – Min (value at start of 2nd bin)

• max (float_ref) – Max (value at end of 2nd last bin)

New in version 6.1.

License: Geosoft Open License

Note: The items correspond to those in histogram2. If a histogram is not defined in the GXST, then the returned number of bins is zero, and the min and max values will be dummies.

get_info(id)

This method allows you to retrieve (and compute) the information from the GXST object.

Parameters:

id (int) – ST_INFO constants

Returns:

Data you asked for GS_R8DM for none

Return type:

float

New in version 5.0.

License: Geosoft Open License

Note: The following can only be determined if the GXST has recorded a histogram: ST_MEDIAN, ST_MODE

ST_MINPOS can be used to retrieve the smallest value greater than zero, but not from GXST objects recovered from serialized object.

classmethod get_norm_prob(x)

Return percent value

Parameters:

x (float) – Real

Returns:

real

Notes this function is based on Normal Cumulative distribution function mit to about 5 standard deviations

Return type:

float

New in version 7.1.

License: Geosoft Open License

classmethod get_norm_prob_x(percent)

Return number of sigmas from 50% a given percent is

Parameters:

percent (float) – Real

Returns:

real

Notes this function is based on Normal Cumulative distribution function mit to about 5 standard deviations

Return type:

float

New in version 7.1.

License: Geosoft Open License

histogram(bins)

This method prepares GXST for recording histogram.

Parameters:

bins (int) – # of bins

New in version 5.0.

License: Geosoft Open License

Note: The Number of bins includes the one before the minimum and the one after the maximum, so it must be a value >2.

IMPORTANT: This function gets the histogram minimum and maximum from the current min and max values stored in the GXST, so this is equivalent to calling histogram2 with

#bins, Min, (Max-Min)/(# bins -2))

You should already have the data loaded in order to call this function.

See histogram_ranges

histogram2(bins, min, max)

This method prepares GXST for recording histogram.

Parameters:

• bins (int) – # of bins

• min (float) – Min

• max (float) – Max

New in version 5.0.

License: Geosoft Open License

Note: The Number of bins includes the one before the minimum and the one after the maximum, so it must be a value >2. The width of the individual bins will be (Min-Max)/(# - 2)

See histogram_ranges

is_null()

Check if this is a null (undefined) instance

Returns:

True if this is a null (undefined) instance, False otherwise.

Return type:

bool

normal_test()

Test the “normality” of the histogram distribution

Returns:

The normality statistic. Terminates if no histogram in the GXST object.

Return type:

float

New in version 5.0.

License: Geosoft Open License

Note: This function compares the histogram to a normal curve with the same mean and standard deviation. The individual counts are normalized by the total counts, the bin width and the standard deviation. For each bin, the rms difference between the expected probability and the normalized count is summed, and the final result is normalized by the total number of bins. In this way histograms with different means, standard deviations, number of bins and counts can be compared. If the histogram were perfectly normal, then a value of 0 would be returned. The more “non-normal”, the higher the statistic.

classmethod null()

A null (undefined) instance of GXST

Returns:

A null GXST

Return type:

GXST

reset()

Resets the Statistics.

New in version 5.0.

License: Geosoft Open License

ST_INFO constants

Information to retrieve

ST_ITEMS

Number of non-dummy items

gxapi.ST_ITEMS = 0

ST_NPOS

Number of items greater than zero

gxapi.ST_NPOS = 1

ST_NZERO

Number of items equal to zero

gxapi.ST_NZERO = 22

ST_TOTAL

Total number of items (dummy and non-dummy)

gxapi.ST_TOTAL = 24

ST_NEMPTYSTRINGS

Number of empty strings from string inputs

gxapi.ST_NEMPTYSTRINGS = 25

ST_DUMMIES

St dummies

gxapi.ST_DUMMIES = 2

ST_MIN

St min

gxapi.ST_MIN = 3

ST_MAX

St max

gxapi.ST_MAX = 4

ST_RANGE

St range

gxapi.ST_RANGE = 5

ST_MEAN

St mean

gxapi.ST_MEAN = 6

ST_MEDIAN

St median

gxapi.ST_MEDIAN = 7

ST_MODE

Mode value (most often repeated value)

gxapi.ST_MODE = 8

ST_SIMPLE_MODE

Mode value (using different algorithm)

gxapi.ST_SIMPLE_MODE = 23

ST_GEOMEAN

St geomean

gxapi.ST_GEOMEAN = 9

ST_VARIANCE

St variance

gxapi.ST_VARIANCE = 10

ST_STDDEV

St stddev

gxapi.ST_STDDEV = 11

ST_STDERR

St stderr

gxapi.ST_STDERR = 12

ST_SKEW

St skew

gxapi.ST_SKEW = 13

ST_KURTOSIS

St kurtosis

gxapi.ST_KURTOSIS = 14

ST_BASE

St base

gxapi.ST_BASE = 15

ST_SUM

Sums and sums of powers

gxapi.ST_SUM = 16

ST_SUM2

St sum2

gxapi.ST_SUM2 = 17

ST_SUM3

St sum3

gxapi.ST_SUM3 = 18

ST_SUM4

St sum4

gxapi.ST_SUM4 = 19

ST_MINPOS

Smallest value greater than zero.

gxapi.ST_MINPOS = 21

ST_HIST_MAXCOUNT

St hist maxcount

gxapi.ST_HIST_MAXCOUNT = 100