search

zmaroti / correctKin

GNU General Public License v3.0
2 stars 0 forks source link

[Documentation] out of date usage docs for the `filterRelates` module. #1

Closed MaelLefeuvre closed 1 year ago

MaelLefeuvre commented 1 year ago

Hello,

Just a quick issue regarding the documentation of the filterRelates module located in your main README, here:

The usage line in this section indicates that the .kinship.py matrix must be provided as the first argument, i.e.

filterRelates [OPTIONS] <PCangsd kin coeff matrix.npy> <marker_overlap_fraction.overlap>

Whereas on the contrary, the module's actual usage line mentions that the .overlap file must be specified first:

filterRelates [OPTIONS] <PREFIX.overlap> <PREFIX.kinship.npy>

Unless I'm mistaken, the latter example seems to be the correct usage of the module, and following the documentation will cause a runtime panic and output rather cryptic message for the user:

panic: runtime error: index out of range [0] with length 0
main.readOverlap({0x7ffda51c00a0, 0x1a})
        [...]/cmd/filterRelates/main.go:187 +0x670
main.main()
        [...]/cmd/filterRelates/main.go:740 +0x2f5

This panic is most probably caused by the software attempting to parse the binary numpy matrix with strArr2Float, thinking it is a tab-separated file.

My first suggestion would thus simply be to update your README.md file.

Secondly, since this documentation typo is also found within Additional file 8: Note S1. of your main article, implementing a simple sanity check within the module, and providing users with a comprehensive error message could also be a great addition for those following an outdated documentation of your program.

Don't know if you're accepting Pull Requests, but I'd be happy to submit one if you're open to contributions.

Hope this helps!

Cheers

zmaroti commented 1 year ago

Thanks for the corfrection. I've updated README to match the tool documentation. Will also fix the code to give more friendly error messages in case of not proper file formats. Unfortunately I am not very familiar with git, so I don't know how to allow pull requests ('Ive just managed my first commit/push, luckily the phylosophy is not hard just get to familiarize with).

MaelLefeuvre commented 1 year ago

Hi, thanks for answering so swiftly!

Pull requests are usually allowed by default on github, but if you're more comfortable with patching the code yourself, I guess submitting one won't be useful. 😃

Thank's for updating the README, and feel free to close this issue whenever you wish to.

Cheers