# Index of functions in BitInformation.jl

### Information

`BitInformation.bitinformation`

— Function`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_information`

— FunctionMutual 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.redundancy`

— Function`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_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.

`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.bitcount`

— Function`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_entropy`

— Function`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_count`

— Function`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_confidence`

— Function`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
```

about 53.1% heads (or tails).

`BitInformation.binom_free_entropy`

— Function`Hf = binom_free_entropy(n::Int,c::Real,base::Real=2)`

Returns the free entropy `Hf`

associated with `binom_confidence`

.

### Transformations

`BitInformation.bittranspose`

— FunctionTranspose the bits (aka bit shuffle) of an array to place sign bits, etc. next to each other in memory. Back transpose via bitbacktranspose().

`BitInformation.bitbacktranspose`

— FunctionBacktranspose the bits of array A that were previously transposed with bittranspose().

`BitInformation.xor_delta`

— FunctionBitwise 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!`

— FunctionBitwise 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_delta`

— FunctionUndo 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.unxor_delta!`

— Function`BitInformation.signed_exponent`

— Function`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.signed_exponent!`

— FunctionIn-place version of `signed_exponent(::Array)`

.

`BitInformation.biased_exponent`

— Function`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.

`BitInformation.biased_exponent!`

— FunctionIn-place version of `biased_exponent(::Array)`

. Inverse of `signed_exponent!".

### Rounding

`Base.round`

— MethodScalar version of `round(::Float,keepbits)`

that first obtains `shift, ulp_half, keep_mask`

and then rounds.

`BitInformation.round!`

— FunctionIEEE'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_shift`

— FunctionShift 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_half`

— FunctionReturns 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_mask`

— FunctionReturns 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_mask`

— FunctionReturns 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.iseven`

— MethodChecks 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.isodd`

— MethodChecks 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.shave`

— FunctionBitshaving 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.shave!`

— FunctionIn-place version of `shave`

for any array `X`

with floats as elements.

`BitInformation.halfshave`

— FunctionHalfshaving 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.halfshave!`

— FunctionIn-place version of `halfshave`

for any array `X`

with floats as elements.

`BitInformation.set_one`

— FunctionBitsetting for floats. Replace trailing bits with `1`

s (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.set_one!`

— FunctionIn-place version of `set_one`

for any array `X`

with floats as elements.

`BitInformation.groom!`

— FunctionBitgrooming for a float arrays `X`

keeping `keepbits`

mantissa bits. In-place version that shaves/sets the elements of `X`

alternatingly.

`BitInformation.nsb`

— FunctionNumber of significant bits `nsb`

given the number of significant digits `nsd`

.

### Printing and BitArray conversion

`Base.bitstring`

— Method`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 for `Base.BitArray(::Matrix)`

. Check Documenter's build log for details.