Documentation Review

[salbalkus]

Hi @nhejazi,

As we discussed, I've narrowed down the feedback I'm looking for on this package to something more specific for you. Namely, would you mind quickly reviewing the quick start tutorial for this package?

Specifically, it would be much appreciated if you could visit https://salbalkus.github.io/CausalTables.jl/ and read it (Just this "Home" page, though if anything is confusing you're welcome to read in more detail on the other sub-pages). I'm mainly hoping for feedback on:

1. Does this page give you a sense of what the package does from the perspective of someone who has never seen it before?
2. Would the page benefit from re-organizing the order of the sections or content?
3. Is there any other functionality you think the package needs before releasing it on Julia's General Repository?
4. Are there any additional questions you'd want answered on the package homepage?

If you have any other feedback on the documentation, I'm also open to it as well!

[nhejazi]

thanks for narrowing the scope @salbalkus, here are some comments related to the prompts above,

1. yes, the documentation is clear but might not characterize as "someone who has never seen it before," as it might help to explain the motivations behind several functions that are implemented, e.g., condensity(), conmean():
   • why might the user care about computing conditional densities or conditional means? these are extremely useful quantities, but maybe a little bit more of the motivation relevant to causality should be introduced? for example, you might show how to compute a counterfactual mean in the DGP example using a combination of the condensity() and conmean() functions?
   • it might help to also include a simple visualization of the graphical structure encoded in the DGP, e.g., W -> X -> Y and W -> Y
2. the organization seems clear and easy to follow -- well done!
3. some minor points below.
4. see minor points below.

miscellaneous/minor notes:

• needed to install as Pkg> add https://github.com/salbalkus/CausalTables.jl.git since the package is not yet registered in the Julia package directory
• suggest renaming the "controls" slot of DataGeneratingProcess to "confounders", to be more consistent with standard causal inference nomenclature (or are the slot names arbitrary?)

• could the CausalTable method of the print() function be made to more closely match that of DataFrame, e.g.,

  julia> data
  CausalTable((W = [5, 1, 5, 3, 4], X = [4.820551923273377, 2.2695289936786396, 5.44923832208513, 2.7009031951746945, 6.022890875678664], Y = [5.724526108863238, 2.383639280605512, 4.21152866924832,    3.351160445117804, 7.357756291671657]), :X, :Y, [:W], Graphs.SimpleGraphs.SimpleGraph{Int64}(0, Vector{Int64}[]), NamedTuple())
  
  julia> test = DataFrame(data)
  5×3 DataFrame
   Row │ W      X        Y
       │ Int64  Float64  Float64
  ─────┼─────────────────────────
     1 │     5  4.82055  5.72453
     2 │     1  2.26953  2.38364
     3 │     5  5.44924  4.21153
     4 │     3  2.7009   3.35116
     5 │     4  6.02289  7.35776

  where the latter seems much friendlier to the user. given that the CausalTable() generator doesn't seem to alter the data structure passed in (e.g., retained as DataFrame in the Titanic example), could this simply be implemented by checking whether the passed-in data is a DataFrame and coercing to one if not? (or is there a downside to this?)

• it would be useful to implement a function parents() on the nodes of a DataGeneratingProcess such that the dependency structure code be drawn out, e.g., parents(dgp.response) would return a subsetted DataFrame or table of the information in the controls and treatment slots; analogous true for parents(dgp.treatment). presumably, having such subsets easily accessible would help in computing nuisance functions in package's building upon this one. in a sense, this amounts to outputting a "subtable" such that it's slots are relatively preserved, e.g., the "response" slot of a parents(dgp.treatment) table would be the treatment itself
• "Getting Started" seems to be an empty page on the docs website; consider removing
• it might help to cite the "no interference" component of Rubin's SUTVA in "The previous example assumes that each unit (row in the Table, in this case df), is "causally independent" of every other unit – that is, the treatment of one unit does not affect the response of any other unit."
• would implementing causal operations on DGPs be within-scope for this package? for example, would obtaining conditional distributions under interventions (say, setting treatment to a given value)

let's plan to discuss the degree to which incorporating the above minor points is worthwhile prior to an initial release. overall, this is very nicely done!