search

gesistsa / sweater

👚 Speedy Word Embedding Association Test & Extras using R
GNU General Public License v3.0
28 stars 4 forks source link

documentation: what is the preferred workflow? #19

Closed cmaimone closed 2 years ago

cmaimone commented 2 years ago

It is recommended to use the function query() to make a query and calculate_es() to calculate the effect size. You can also use the functions listed below.

I'm confused why there are both general functions and specific ones -- seems like you should either specify the method as an argument to query() or have to use a query function specific to each method -- not both options.

Are functions mac(), rnd(), nas() etc functions that create a query? If so, it would be great to get "query" in their names to make that clear.

re: https://github.com/openjournals/joss-reviews/issues/4036

chainsawriot commented 2 years ago

@cmaimone As of now, the preferred workflow is certainly query. The monolithic query interface is unfortunately an afterthought (4c0751c2b235265e807cf87e0cb813a170c914d0) and the package started with individual functions for each method. I know that there has been legacy code in some other researchers' analytic scripts using those individual functions. For backward compatibility, I need to keep those functions — their names at least — as they were (also, it's too late now to rename those functions with some tidyverse-style verb-based function names, similar to your "get query in their names").

Maybe a more proper approach is to make those individual functions less prominent in the README and state that they are here for backward compatibility.

cmaimone commented 2 years ago

Downplaying them in the readme seems like a good strategy -- maybe even mark them as depreciated and plan to take them out in the future (or, if you prefer separate functions, change the names)? Your package is pretty young to feel like you're locked in forever, but I do appreciate the care for existing users.

chainsawriot commented 2 years ago

TODO