8000 ENH: Add rotated copula CDF helper (_rotate_cdf) and tests by kudos07 · Pull Request #9681 · statsmodels/statsmodels · GitHub
[go: up one dir, main page]
Skip to content

ENH: Add rotated copula CDF helper (_rotate_cdf) and tests#9681

Open
kudos07 wants to merge 2 commits intostatsmodels:mainfrom
kudos07:feat/rotated-copula-cdf
Open

ENH: Add rotated copula CDF helper (_rotate_cdf) and tests#9681
kudos07 wants to merge 2 commits intostatsmodels:mainfrom
kudos07:feat/rotated-copula-cdf

Conversation

@kudos07
Copy link
Contributor
@kudos07 kudos07 commented Nov 2, 2025

Hi @josef-pkt

This PR adds the first stage of the rotated copula implementation, focusing only on the CDF rotation helper.
This is mainly to show the approach and structure, if this looks fine, I will proceed to add the PDF and RVS rotation helpers next.

Summary

  • Added _rotate_cdf(u, v, rotation, base_copula_cdf) in copulas.py.
  • Implements the rotation identities from Klein et al. (2019, Section 2.4) for 0°, 90°, 180°, and 270° rotations.
  • Rotations shift tail dependence to different corners of the unit square.

The conventions follow Joe (1997) and VineCopula.
Formulas implemented:

C90(u, v) = u - C(u, 1 - v)
C180(u, v) = u + v - 1 + C(1 - u, 1 - v)
C270(u, v) = v - C(1 - u, v)

Klein et al. (2019) use an opposite rotation orientation, so their 90° and 270° labels are reversed, but the results are mathematically identical.

Implementation details

  • _rotate_cdf accepts a base copula’s CDF and validated (u, v) inputs in (0, 1).
  • Inputs are flattened and stacked as (n, 2) arrays for compatibility with Archimedean copula classes, then reshaped back.
  • Parameter validation and clipping are already handled upstream.
  • Formulas verified directly from Klein et al. (2019, §2.4).

Testing

  • Added dedicated tests for rotated CDFs using the Clayton copula (θ = 2).
  • Verified that all rotations return values in [0, 1] and remain monotone non-decreasing.
  • Tests for 90°, 180°, and 270° all passed successfully.
  • Full test suite results: 102 passed, 1 skipped (Student-t CDF unimplemented), 3 xfailed (expected QMC).

Debugging notes

  • Fixed ImportError when _rotate_cdf was defined inside the class.
  • Fixed ValueError for ambiguous truth values by flattening and stacking (u, v).
  • Fixed unpacking error in ClaytonCopula.cdf by explicitly passing column-stacked arrays.
  • After these fixes, both rotation tests ran successfully.

Next steps

  • Implement _rotate_pdf using transformed arguments and the Jacobian.
  • Implement _rotate_rvs using geometric transformations such as (1 − U, 1 − V) for 180°.
  • Add a simple RotatedCopula wrapper to expose CDF, PDF, and RVS consistently.

Verification

Plan to cross-check rotated CDF values against the R package VineCopula::BiCopCDF for corresponding rotated families (for example, family codes 13 and 14 for 180° rotations) to confirm numerical consistency.

Thanks,

@kudos07
ENH: Add rotated copula CDF helper (_rotate_cdf) and tests
def550e 
Implements 0°, 90°, 180°, and 270° rotation formulas for Archimedean copulas
as described in Klein et al. (2019, Section 2.4). Includes tests verifying
numerical range and monotonicity for rotated Clayton copula.
github-advanced-security[bot]
936D
github-advanced-security bot found potential problems Nov 2, 2025
View reviewed changes
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@kudos07
0