Toward a grammar of M-estimation

[bsaul]

The current function names in geex reflect the haphazard development thusfar. Before geex gains a wider user base (wishful thinking?), I'd like to reflect on the naming convention of functions within geex, keeping in mind the Design for Humans section of the tidyverse manifesto.

I propose the following conventions:

User functions

High level

• do_***: any primary high level function. Right now, this is only estimate_equations, which I don't think is particularly descriptive of what this function does.
  • so estimate_equations --> do_mestimation or something like that?
• correct_by_**: functions that correct the output of compute_matrices by some manipulation.
• verify_**: functions that verify the output of geex. e.g. check_GFUN which evaluates the GFUN at the estimated roots would become verify_roots.

For use within an eeFUN

• get_**: utility functions that takes some object and gets some element of that object
• make_**: functions that take some model object and makes the estimating functions for that model type.

Internal functions

These may be exported functions, but they are primarily designed for use within geex.

• compute_**: functions that take in stuff and compute numeric values.
• create_**: functions that take in stuff and create a function or list of functions.
• check_**: functions that check functions or other objects that they conform to what downstream functions expect.

Others

How to deal with functions such as binomial_integrand, objFun_merMod that are internal to a make_** function?

[BarkleyBG]

For the "others" category, I'm thinking of verbs like "construct." Or better yet, since these could be considered plumbing functions, or innards to another function, perhaps verbs that relate to guts/organs/biology?

[bsaul]

Or what about just not exporting these functions and not exporting them?

Or in keeping with the plumbing metaphor, how about digest_** as in digest_binomial_integrand :)

Or process_**?

binomial_integrand could be compute_binomial_integrand, but it’s such a highly specific function that this type of function does belong in a different category.

On Jul 13, 2017, at 2:13 PM, Brian G. Barkley notifications@github.com wrote:

For the "others" category, I'm thinking of verbs like "construct." Or better yet, since these could be considered plumbing functions, or innards to another function, perhaps verbs that relate to guts/organs/biology?

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/bsaul/geex/issues/24#issuecomment-315159056, or mute the thread https://github.com/notifications/unsubscribe-auth/AEqCLs7Z6lQMKo5YfjRuo6-U3x-Hvjvwks5sNl5IgaJpZM4OW_p0.

[BarkleyBG]

Or what about just not exporting these functions and not exporting them?

🤔

I kinda like process_** because it's general enough. Somewhere between process and digest. Unfortunately they're both nouns, too.

• absorb_*
• subsume_*

[BarkleyBG]

suggestions:

• use analyze() instead of do_mestimation() as the main geex function
• grab_*() instead of get_*()
• use action verbs like flip/turn/spin instead of make_*(), which may reference the functional programming piece

[bsaul]

Here are my current thoughts:

User functions

High level

• solve_equations: the primary high level function that essentially performs M-estimation.
• correct_by_**: functions that correct the output of compute_matrices by some manipulation.
• diagnose_**: functions that diagnose the output of geex, e.g. diagnose_roots(geex_object).

For use within an eeFUN

• grab: a generic function that takes an object and grabs some element of that object. Example usage: grab(from = my_model, what = 'response') or grab(from = my_model, what = 'eeFUN', data = mydata)

Internal functions

These may be exported functions, but they are primarily designed for use within geex.

• compute_**: functions that take in stuff and compute numeric values.
• create_**: functions that take in stuff and create a function or list of functions.
• check_**: functions that check functions or other objects that they conform to what downstream functions expect. NOT exported.

Others

Functions such as binomial_integrand andobjFun_merMod will not be exported.