Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Highlight the use of Julia boolean style #92

Open
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

earthgecko
Copy link

It may be helpful to users to inform them that the wrapper uses lowercase Julia booleans rather than Python booleans, that is not made specifically clear anywhere.

It may be helpful to users to inform them that the wrapper uses lowercase Julia booleans rather than Python booleans, that is not made specifically clear anywhere.
@malmaud
Copy link
Collaborator

malmaud commented May 25, 2022

Thanks for suggesting this! I think it's not really necessary though since I don't think it would be common for someone to think that literals would use Python syntax instead of Julia syntax. For example, the literal syntax for floating point numbers, strings, booleans, matrices, etc is different between Python and Julia and I don't think the readme of this package is the right place to document all of that.

However, I think adding a link to the the PyCall documentation and mentioning that values accepted by the API of this package generally go through the same conversion as arguments passed to PyCall (which would include Julia 'true' being converted to Python's 'True') could indeed be useful.

@earthgecko
Copy link
Author

@malmaud OK I guess you obviously have a better grasp of what is "common" to a new user than I do. However given that this is a wrapper to Pandas and makes the statement that

It sticks closely to the Pandas API. One exception...

That in itself almost suggests and hints to the user that Pandas arguments are valid. Most of the time user is probably going to be REPL'ing in the terminal at julia > trying to refactor Python methods to Julia Pandas at which point they are not going to be referring to PyCall documentation because they are not using PyCall as far as they are concerned (in their limited knowledge), they are going to be looking at Pandas.jl documentation. Granted they are going to revert to using pandas directly through PyCall as pd.Series.ewm when they iterated over every conceivable variation of Pandas.Series.ewm with zero succes. is the ewm method even available or are my arguments or data not correct? Is it one of the obscure functions referenced in Caveats? Who knows...

I digress, but given that a fair percentage of new users will be from a Python background having spent years thinking True was True, it would probably be useful to many of us to have these things related to Julia explicitly pointed out and reinforced wherever possible, especially in the any related documentation itself.

I guess this falls under the paradigm discussed in https://discourse.julialang.org/t/non-friendly-documentation/38109

It works exactly the same as in language XXXX but the syntaxis is completely different so you have to do it the Julia way.”

@malmaud I have updated this PR with your suggestion referencing PyCall Usage, however in my opinion it is opaque, therefore I have modified the PR to just state it once. Hopefully that is not too much bloat for README.md

Apologies if this is a bit of a rant, however having spent many days converting a handful of simple algorithms from Python to Julia and having spent hours iterating with trial and error over every conceivable way I could think of to try and get x to work with
Statistics, Pandas, SciPy, PyCall, StatsBase, HypothesisTests... I have come to the conclusion that a lot of Julia things (apart for the core language itself) are quite poorly documented, unless you are conversationally fluent in Julia, Julians in general seem almost unwilling to share examples of data structures and method calls in their documentation, although many of them seem to be very helpful on discourse.julialang.org, just a shame that more time was not spent on more helpful documentation to actually help people use things.

Pandas.jl actually has some of the best most understandable documentation...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants