[rastagan-git]

References to issues or other PRs

Fixes #61. This clarifies the 1D/2D contract explained in the maintainer's issue comment, including the follow-up requested in review 5439347758.

Describe the proposed changes

• Document (n,), (n, p), and (n, q) consistently for the nine usual biased, unbiased, or bias-corrected distance covariance/correlation and statistics functions in the first two estimator sections of the API list. The first axis is paired observations; feature counts may differ.
• Explain arbitrary vector dimension versus arbitrary array rank in the existing API reference, immediately before these estimator lists. The shape section is no longer on the homepage. Its scope is these dependency estimators, not energy distance or homogeneity tests.
• State that a tensor such as (n, 2, 5) should be reshaped before passing it to these functions, only if its remaining axes jointly describe each observation's features. This does not implement implicit flattening or gufunc-style batching.
• Expand the existing executable example's explanation: four observations, each a two-by-five measurement grid, become four observations with ten components. Link rowwise for separate dataset calculations.

The final diff changes only dcor/_dcor.py docstrings and docs/apilist.rst. No new page, executable function, estimator, or public signature is added. Stripping docstrings yields identical executable ASTs against both the original PR head and the upstream base.

Additional information

Final local follow-up verification on Windows, Python 3.12.11, NumPy 2.5.3, SciPy 1.18.1, Numba 0.68.0, and dcor 0.8.dev0:

• python -m pytest -q dcor/_dcor.py: 11 doctests passed.
• python -m pytest -q: 73 passed, 22 subtests passed, with 14 existing non-array-input deprecation warnings. The 11 focused doctests are included in this total. The original PR head was rerun with the same suite result and warnings.
• An independent local file outside the contribution tree: 46 checks passed across all nine documented APIs, covering scalar/column equivalence, different feature counts, rejection of rank-3 x or y, explicit parameter documentation, and the small reshape example's analytic value 13**(-0.25). Its 37 behavior/example checks also passed on the original PR head; the nine new-documentation checks are not applicable to that head. This verifier is not part of the PR and is not represented as 46 new project tests.
• python -m sphinx -b html -D plot_gallery=0 docs <output-directory>: HTML built successfully with the same two existing CONTRIBUTORS.md heading/cross-reference warnings previously reproduced on the upstream base. The shape section appears in the API list, not the homepage; all nine parameter pages and the expanded example/links were checked in local HTML. Gallery scripts were not executed; pytest executed the docstring example.
• python -m pip check, executable AST comparisons, git diff --check, and staged whitespace checks passed.

No provider, clinical/private data, performance benchmark, other Python version, or other OS was tested. These local results do not claim that the new commit's remote CI has run or that the maintainer has accepted the revision.

AI assistance

Codex performed the source reading, initial documentation edit, maintainer-requested follow-up, tests, and build checks for the account owner. The account owner has not independently read or run the changes; no independent human self-review is claimed. The publicly reported usage issue and the maintainer's actual review are the evidence for this contribution, not an invented production incident.

Checklist before requesting a review

Executable-code typing/new-functionality items in the template are not applicable. Documentation checks and the executable example were performed by Codex as disclosed above, not represented as the account owner's manual self-review.

[vnmabus]

Thanks for the PR! I think it is a step in the right direction, although I would prefer it to cover also other dependency measures, and a couple of additional small changes.

[vnmabus]

I would clarify a bit more the meaning of the dimensions in the example.

[vnmabus]

Suggested change

	Random vectors may have an arbitrary number of components, but this does not
	mean that arbitrary-rank tensors or batch axes are accepted. For example,
	an input with shape ``(n, 2, 5)`` can be reshaped to ``(n, 10)`` if the last
	two axes jointly describe the features of each observation. This computes
	one dependence measure between random vectors, not separate correlations
	for each tensor slice. See the :func:`dcor.distance_correlation` examples and
	:func:`dcor.rowwise` for separate calculations over multiple datasets.
	Random vectors may have an arbitrary number of components, but this does not
	mean that arbitrary-rank tensors or batch axes are accepted. For example,
	an input with shape ``(n, 2, 5)`` should be reshaped to ``(n, 10)`` if the last
	two axes jointly describe the features of each observation, before passing it to a dependency measure function from this package. This computes
	one dependence measure between random vectors, not separate correlations
	for each tensor slice. See the :func:`dcor.distance_correlation` examples and
	:func:`dcor.rowwise` for separate calculations over multiple datasets.

[vnmabus]

I think this section should not be in the index page (it is too specific). Maybe it can be moved to the section of the API reference that introduces the dependency functions.

[vnmabus]

I think these observations should be also done for distance covariance functions (biased and unbiased), as they accept vectors with the same shape.

[rastagan-git]

Added a follow-up commit to this existing PR addressing the four review points:

• Applied the same (n,) / (n, p) / (n, q) parameter contract to the biased and unbiased/bias-corrected covariance and correlation functions, and their statistics counterparts (nine functions in total).
• Moved the shared explanation from the homepage to the API list before the dependency estimator sections, with scope limited to those functions.
• Made the reshape-before-calling wording explicit, conditional on the remaining axes being features of one observation.
• Explained the example as four observations, each a two-by-five measurement grid, becoming four ten-component vectors.

The updated suite is 73 passed / 22 subtests passed (11 focused doctests are part of that total). A separate local verifier passed 46 checks; its 37 behavior/example checks also pass at the prior head. HTML builds with the same two pre-existing CONTRIBUTORS warnings, and executable ASTs are unchanged against the prior head and upstream base. Gallery scripts were not executed.

Codex performed this follow-up and validation, as disclosed in the updated PR description; the account owner has not independently read or run the change. No new PR or runtime change was introduced.

[vnmabus]

Well, I guess I have to thank you, for disclosing the generative AI usage, and for forcing me to pick a generative AI policy.

As I have now made clear in CONTRIBUTING.md, we will not allow AI output in the submission, mainly for copyright reasons. In addition, automatic contributions are not welcomed: I will gladly interact with and guide a fellow human to make a quality contribution, but I do not want to expend that time talking with a bot. I think this kind of contribution misses the point of open-source development completely.

The account owner has not independently read or run the changes; no independent human self-review is claimed.

Why should I spend my time reviewing this if you did not spend any time on it? This is rude behavior. If I wanted the direct output of AI, I could have used AI myself.