unify method docstrings and what functions return

[houssamzenati]

Looking at the documentation, it would be nice to have unified names on what estimators return

example for mediation_IPW

Returns
:
float – total effect

float – direct effect treated ( heta(1))

float – direct effect nontreated ( heta(0))

float – indirect effect treated (delta(1))

float – indirect effect untreated (delta(0))

int – number of used observations (non trimmed)

example for mediation_dml:

Returns
:
total (float) – Average total effect.

direct1 (float) – Direct effect on the exposed.

direct0 (float) – Direct effect on the unexposed,

indirect1 (float) – Indirect effect on the exposed.

indirect0 (float) – Indirect effect on the unexposed.

n_discarded (int) – Number of discarded samples due to trimming.

moreover, is it really useful for the user of the library to have n_discarded?? should we discard it for all estimators??

[bthirion]

Yes, we need homogeneity !

I also think that n_discarded is an internal parameter that should not be returned (but could be logged in the future)

[judithabk6]

n_discarded is not internal, it's important to be aware if trim argument is too high. @houssamzenati suggested a warning instead, and in that case we could remove it from the returned values. WDYT @bthirion?

[bthirion]

But I'm afraid there are 10 internal parameters of that kind and that we're focusing on one particular ? Bzw, I have the feeling that we should never use trimming.