# Index of functions in BitInformation.jl

### Information

BitInformation.bitinformationFunction
M = bitinformation(A::AbstractArray{T}) where {T<:Union{Integer,AbstractFloat}}

Bitwise real information content of array A calculated from the bitwise mutual information in adjacent entries in A. Optional keyword arguments

- dim::Int=1 computes the bitwise information along dimension dim.
- masked_value::T=NaN masks all entries in A that are equal to masked_value.
- set_zero_insignificant::Bool=true set insignificant information to zero.
- confidence::Real=0.99 confidence level for set_zero_insignificant.
M = bitinformation(A::AbstractArray{T}, mask::BitArray) where {T<:Union{Integer,AbstractFloat}}

Bitwise real information content of array A calculated from the bitwise mutual information in adjacent entries in A along dimension dim (optional keyword). Array A is masked through trues in entries of the mask mask. Masked elements are ignored in the bitwise information calculation.

BitInformation.mutual_informationFunction

Mutual information from the joint probability mass function p of two variables X,Y. p is an nx x ny array which elements represent the probabilities of observing x~X and y~Y.

Mutual bitwise information of the elements in input arrays A,B. A and B have to be of same size and eltype.

BitInformation.redundancyFunction
R = redundancy(A::AbstractArray{T},B::AbstractArray{T}) where {T<:Union{Integer,AbstractFloat}}

Bitwise redundancy of two arrays A,B. Redundancy is a normalised measure of the mutual information: 1 for always identical/opposite bits, 0 for no mutual information.

### Bit counting and entropy

BitInformation.bitpattern_entropyFunction
H = bitpattern_entropy(A::AbstractArray,base::Real=2)

Calculates the bit pattern entropy H for an array A by reinterpreting the elements as UInts and sorting them to avoid creating a histogram. The bit pattern entropy is the entropy from occurences of every possible bitpattern in T in elements of A. The unit of entropy is given by base base, such that for the default base=2 it is bits.

BitInformation.bitpattern_entropy!Function
H = bitpattern_entropy!(A::AbstractArray,base::Real=2)

Calculates the bit pattern entropy H for an array A by reinterpreting the elements as UInts and sorting them to avoid creating a histogram. The bit pattern entropy is the entropy from occurences of every possible bitpattern in T in elements of A. The unit of entropy is given by base base, such that for the default base=2 it is bits. In-place version of bitpattern_entropy that will sort A. Use bitpattern_entropy if changes to A are to be avoided.

BitInformation.bitcountFunction
n = bitcount(A::AbstractArray{T},i::Int) where {T<:Unsigned}

Counts the occurences of the 1-bit in bit position i across all elements of A.

C = bitcount(A::AbstractArray{T}) where {T<:Union{Integer,AbstractFloat}}

Counts the occurences of the 1-bit in every bit position across all elements of A. Returns a counter array C::Vector{Int} such that the first entries represents the first bit in elements of type T, e.g. the sign bit for floats.

BitInformation.bitcount_entropyFunction
H = bitcount_entropy(A::AbstractArray{T},base::Real=2) where {T<:Union{Integer,AbstractFloat}}

Returns a vector H of entropies for the occurence of 0,1 in every bit position in T across elements of A. Makes use of the bitcount functions and calculates the entropy from the probability of the 0 and 1 bit. The base base is by default 2, such that the unit of entropy is bit.

BitInformation.bitpair_countFunction
C = bitpair_count(A::AbstractArray{T},B::AbstractArray{T}) where {T<:Union{Integer,AbstractFloat}}

Returns counter array C of size nbits x 2 x 2 for every 00|01|10|11-bitpairing in elements of A,B. nbits is the number of bits in type T.

C = bitpair_count(A::AbstractArray{T},mask::AbstractArray{Bool}) where {T<:Union{Integer,AbstractFloat}}

Returns counter array C of size nbits x 2 x 2 for every 00|01|10|11-bitpairing in elements of A,B where neither are masked as determined from mask. nbits is the number of bits in type T.

### Significance of information

BitInformation.binom_confidenceFunction
p₁ = binom_confidence(n::Int,c::Real)

Returns the probability p₁ of successes in the binomial distribution (p=1/2) of n trials with confidence c.

Example

At c=0.95, i.e. 95% confidence, n=1000 tosses of a coin will yield not more than

julia> p₁ = BitInformation.binom_confidence(1000,0.95)
0.5309897516152281

### Transformations

BitInformation.xor_deltaFunction

Bitwise XOR delta. Elements include A are XORed with the previous one. The first element is left unchanged. E.g. [0b0011,0b0010] -> [0b0011,0b0001].

Bitwise XOR delta. Elements include A are XORed with the previous one. The first element is left unchanged. E.g. [0b0011,0b0010] -> [0b0011,0b0001].

Bitwise XOR delta. Elements include A are XORed with the previous one. The first element is left unchanged. E.g. [0b0011,0b0010] -> [0b0011,0b0001].

BitInformation.xor_delta!Function

Bitwise XOR delta. Elements include A are XORed with the previous one. The first element is left unchanged. E.g. [0b0011,0b0010] -> [0b0011,0b0001]

BitInformation.unxor_deltaFunction

Undo bitwise XOR delta. Elements include A are XORed again to reverse xor_delta. E.g. [0b0011,0b0001] -> [0b0011,0b0010]

Undo bitwise XOR delta. Elements include A are XORed again to reverse xor_delta. E.g. [0b0011,0b0001] -> [0b0011,0b0010]

Undo bitwise XOR delta. Elements include A are XORed again to reverse xor_delta. E.g. [0b0011,0b0001] -> [0b0011,0b0010]

BitInformation.signed_exponentFunction
B = signed_exponent(A::AbstractArray{T}) where {T<:Base.IEEEFloat}

Converts the exponent bits of Float16,Float32 or Float64-arrays from its IEEE standard biased-form into a sign-magnitude representation.

Example

julia> bitstring(10f0,:split)
"0 10000010 01000000000000000000000"

julia> bitstring.(signed_exponent([10f0]),:split)[1]
"0 00000011 01000000000000000000000"

In the IEEE standard floats the exponent 3 is interpret from 0b10000010=130 via subtraction of the exponent bias of Float32 = 127. In sign-magnitude representation the exponent is inferred from the first exponent (0) as sign bit and a magnitude 2^1 + 2^1 = 3. NaN/Inf exponent bits are mapped to negative zero in sign-magnitude representation which is exactly reversed with biased_exponent.

BitInformation.biased_exponentFunction
B = biased_exponent(A::AbstractArray{T}) where {T<:Base.IEEEFloat}

Convert the signed exponents from signed_exponent back into the standard biased exponents of IEEE floats.

### Rounding

Base.roundMethod

Scalar version of round(::Float,keepbits) that first obtains shift, ulp_half, keep_mask and then rounds.

BitInformation.round!Function

IEEE's round to nearest tie to even for a float array X in-place. Calculates from keepbits only once the variables ulp_half, shift and keep_mask and loops over every element of the array.

BitInformation.get_shiftFunction

Shift integer to push the mantissa in the right position. Used to determine round up or down in the tie case. keepbits is the number of mantissa bits to be kept (i.e. not zero-ed) after rounding. Special case: shift is -1 for keepbits == significand_bits(T) to avoid a round away from 0 where no rounding should be applied.

BitInformation.get_ulp_halfFunction

Returns for a Float-type T and keepbits, the number of mantissa bits to be kept/non-zeroed after rounding, half of the unit in the last place as unsigned integer. Used in round (nearest) to add ulp/2 just before round down to achieve round nearest. Technically ulp/2 here is just smaller than ulp/2 which rounds down the ties. For a tie round up +1 is added in round(T,keepbits).

BitInformation.get_keep_maskFunction

Returns a mask that's 1 for all bits that are kept after rounding and 0 for the discarded trailing bits. E.g.

julia> get_keep_mask(Float16,5)
0xffe0

.

BitInformation.get_bit_maskFunction

Returns a mask that's 1 for a given mantissabit and 0 else. Mantissa bits are positive for the mantissa (mantissabit = 1 is the first mantissa bit), mantissa = 0 is the last exponent bit, and negative for the other exponent bits.

Base.isevenMethod

Checks a given mantissabit of x for eveness. 1=odd, 0=even. Mantissa bits are positive for the mantissa (mantissabit = 1 is the first mantissa bit), mantissa = 0 is the last exponent bit, and negative for the other exponent bits.

Base.isoddMethod

Checks a given mantissabit of x for oddness. 1=odd, 0=even. Mantissa bits are positive for the mantissa (mantissabit = 1 is the first mantissa bit), mantissa = 0 is the last exponent bit, and negative for the other exponent bits.

### Shaving, halfshaving, setting and bit grooming

BitInformation.shaveFunction

Bitshaving for floats. Sets trailing bits to 0 (round towards zero). keepmask is an unsigned integer with bits being 1 for bits to be kept, and 0 for those that are shaved off.

Bitshaving of a float x given keepbits the number of mantissa bits to keep after shaving.

BitInformation.halfshaveFunction

Halfshaving for floats. Replaces trailing bits with 1000... a variant of round nearest whereby the representable numbers are halfway between those from shaving or IEEE's round nearest.

Halfshaving of a float x given keepbits the number of mantissa bits to keep after halfshaving.

BitInformation.set_oneFunction

Bitsetting for floats. Replace trailing bits with 1s (round away from zero). setmask is an unsigned integer with bits being 1 for those that are set to one and 0 otherwise, such that the bits to keep are unaffected.

Bitsetting of a float x given keepbits the number of mantissa bits to keep after setting.

BitInformation.groom!Function

Bitgrooming for a float arrays X keeping keepbits mantissa bits. In-place version that shaves/sets the elements of X alternatingly.

### Printing and BitArray conversion

Base.bitstringMethod
s = bitstring(x::T,mode::Symbol) where {T<:AbstractFloat}

Bitstring function for floats with a split-mode for mode=:split that splits the bitstring into sign, exponent and significant bits.

Missing docstring.

Missing docstring for Base.BitArray(::Matrix). Check Documenter's build log for details.