Improve Error message when dim in bitinformation(data, dim) too short

[aaronspring]

What do you think about improving the error message when the dimension is too short to run bitinformation over it? i.e. when dim only have one or two elements, lets say the user wants to run bitinformation over a time dimension (where physically adjacent is recommended and should rather use lon or lat).

Right now the error message is: Mask has 347040 unmasked values, 0 entries are adjacent. which is correct. But maybe the user can get a more explanatory return message or at least warning like You try to calculate bitinformation along a (too) short dimension of {length(data[dim])} elements. Maybe even continuing ... bitinformation assumes that adjacents analysis elements are also physically adjacent...

Came up in observingClouds/xbitinfo#97 (comment)

[observingClouds]

I just add to this that I could imagine that BitInformation.jl would raise a user defined error, which could be as simple as

    type DimensionalityError <: Exception
    end
    type DimensionalityErrorTree <: Exception
        var::String
    end

    Base.showerror(io::IO, e:: DimensionalityErrorTree) = print(io, "You try to calculate bitinformation along a (too) short dimension of",e.var, "elements.")

    julia> throw(DimensionalityError(Len(data[dim])))

Not sure if this is the correct syntax. I just adapted it from here.

This would be easier to catch from calling scripts.

[milankl]

At the moment we are doing

BitInformation.jl/src/mutual_information.jl

Lines 103 to 105 in 5f3ebbd

	C = bitpair_count(A,mask) # nbits x 2 x 2 array of bitpair counters
	nelements = sum(C[1,:,:]) # depending on mask nelements changes so obtain via C
	@assert nelements > 0 "Mask has $(sum(.~mask)) unmasked values, 0 entries are adjacent."

So we count the bits but if the counter is still zero afterwards an AssertionError is triggered.

julia> using BitInformation
julia> A = rand(100);
julia> mask = A .== A;
julia> bitinformation(A,mask)
ERROR: AssertionError: Mask has 0 unmasked values, 0 entries are adjacent.
Stacktrace:
 [1] bitinformation(A::Vector{Float64}, mask::BitVector; dim::Int64, set_zero_insignificant::Bool, confidence::Float64)
   @ BitInformation ~/.julia/packages/BitInformation/VpaaY/src/mutual_information.jl:105
...

Julia has a bunch of error types. I agree that an AssertionError is maybe not the most telling and that we may want to reconsider what kind of error is thrown. However, it seems that this AssertionError is only propagated as a string in the error message (why are python error messages always sooo long 😄) probably because the python errors are not matched to julia errors. Meaning that whether we decide for another error type or define our own, this would only be of use if you could actually catch that error somehow. And what do you want to do with it if you catch it?

[milankl]

You try to calculate bitinformation along a (too) short dimension of {length(data[dim])} elements. Maybe even continuing ... bitinformation assumes that adjacents analysis elements are also physically adjacent...

Feel free to suggest error messages. I'd rather have it short and on the point though. I don't think it's the job of an error message to explain how a function is used though, this should be part of the docstring / documentation. On that note I don't think the masked array support ever made it into the documentation ... 😞