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)

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 End-User 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 End-User License

data(val)¶

Add this value to the statistics object.

Parameters:	val (float) – Value to Add

New in version 5.0.

License: Geosoft End-User 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 End-User 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 End-User 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 End-User 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 End-User 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 End-User 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 End-User 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 End-User 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 End-User License

histogram(bins)¶

This method prepares GXST for recording histogram.

Parameters:	bins (int) – # of bins

New in version 5.0.

License: Geosoft End-User 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 End-User 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 End-User 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 End-User 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_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¶

St mode

gxapi.ST_MODE = 8

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