bsaul/geex

Toward a grammar of M-estimation

Closed this issue · 5 comments

bsaul commented

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 commented

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 commented
BarkleyBG commented

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 commented

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 commented

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.