Documentation improvement suggestions

[njmmerrill]

@djinnome

I went through the dsl and identify algorithm files and think that these changes to documentation will make things more clear.

Typo

ff should be if

y0/src/y0/dsl.py

Line 454 in 88d7e39

Will raise a value error ff the value of a new intervention conflicts

Clarity

When I was reading through the documentation, whenever I had to take extra time to decipher the language I tried to rewrite a version that I thought would be more clear.

y0/src/y0/dsl.py

Lines 18 to 24 in 88d7e39

	============================== =================================================
	Expression Description
	============================== =================================================
	:math:`P(Y_X \mid X^*, Y^*)` Probability of sufficient causation
	:math:`P(Y^*_{X^*} \mid X, Y)` Probability of necessary causation
	:math:`P(Y_X, Y^*_{X^*})` Probability of necessary and sufficient causation
	============================== =================================================

I like to use plain (non-statistics) language when possible to increase understanding. I would consider adding a plain language column for the table

==============================  =================================================  ===============================================================
Expression                      Description                                        Example
==============================  =================================================  ===============================================================
:math:`P(Y_X \mid X^*, Y^*)`    Probability of sufficient causation               Would the outcome have changed if treated?
:math:`P(Y^*_{X^*} \mid X, Y)`  Probability of necessary causation                Would the outcome have failed without treatment?
:math:`P(Y_X, Y^*_{X^*})`       Probability of necessary and sufficient causation Did treatment cause the outcome, and would it have failed otherwise?
==============================  =================================================  ===============================================================

y0/src/y0/dsl.py

Line 361 in 88d7e39

Counterfactual variables are like normal variables, but can have a list of interventions.

minor changes

A counterfactual variable used in formal causal reasoning. Counterfactual variables are like normal variables, but can have a set of interventions. Each intervention will either match the observed reality (no star) or represent deviations (star).

y0/src/y0/dsl.py

Line 379 in 88d7e39

def to_text(self) -> str:

Can we add and example of output here? I don't remember what it is.

"""Output this counterfactual variable in the internal string format (e.g., "Y_{X*}")."""

y0/src/y0/dsl.py

Line 433 in 88d7e39

"""Return if the counterfactual variable violates the Axiom of Effectiveness.

I am in favor of adding plain language for potential non-stats people.
Check whether the counterfactual variable violates the Axiom of Effectiveness (i.e., forcing a variable to a value but observing a different value).

y0/src/y0/dsl.py

Line 447 in 88d7e39

:param variables: The variable(s) used to extend this counterfactual variable's

The variable(s) to intervene on. These will be added to the counterfactual variable’s current interventions.

y0/src/y0/dsl.py

Line 489 in 88d7e39

"""Invert the value of the counterfactual variable."""

Again, I am in favor of adding plain language for potential non-stats people.
Invert the value of the counterfactual variable (i.e. Y^{-} becomes Y^{+} and vice versa).

Identify properties

y0/src/y0/algorithm/identify/utils.py

Lines 258 to 270 in 7cb0fe3

	def outcomes(self) -> set[Variable]:
	"""Return this identification object's query's outcomes."""
	return self.query.outcomes
	@property
	def treatments(self) -> set[Variable]:
	"""Return this identification object's query's treatments."""
	return self.query.treatments
	@property
	def conditions(self) -> set[Variable]:
	"""Return this identification object's query's conditions."""
	return self.query.conditions

I think these property descriptions are confusing to read.
I would change to something like this:

• Return the outcome variables from the query stored in this identification object.
• Return the treatment variables from the query stored in this identification object.
• Return the condition from the query stored in this identification object.

[njmmerrill]

y0/src/y0/dsl.py

Line 361 in 88d7e39

Counterfactual variables are like normal variables, but can have a list of interventions.

The counterfactual variable class has a comment about the intervention variables having an associated star bool. This comment should be moved to the Intervention class instead.

https://github.com/y0-causal-inference/y0/blob/88d7e39b525797790ca5dbe0931c91258fcc1b94/src/y0/dsl.py#L346C1-L351C1