Skip to content

Add properties with docstrings to XRTDEMIterative for all public result attributes #405

Description

@joyvelasquez

Feature description

XRTDEMIterative currently exposes many of its result and grid attributes as plain instance attributes set directly with self.xxx = inside methods like solve(), create_logT_grid(), and _run_monte_carlo(). These should be converted to proper @property definitions with NumPy-style docstrings so they appear correctly in the API reference documentation and can be cross-referenced from other docs pages.

The full list of candidates:

Core grid attributes (set in create_logT_grid):

  • logT — log10 temperature grid
  • T — linear temperature grid in Kelvin
  • dlogT — step size in log10(T)
  • dlnT — step size in ln(T)
  • n_bins — number of temperature bins

Initialization attributes:

  • observed_channel — validated filter names
  • responses — temperature response objects

Solver results (set in solve()):

  • dem — DEM solution array, cm⁻⁵ K⁻¹
  • chisq — chi-square value of the fit
  • modeled_intensities — forward-modeled filter intensities, DN/s/pix

Monte Carlo results (set in _run_monte_carlo()):

  • mc_dem — DEM solutions for all MC realizations, shape (N+1, n_T)
  • mc_chisq — chi-square for each realization, shape (N+1,)
  • mc_base_obs — observed intensities per realization, shape (N+1, n_channels)
  • mc_mod_obs — modeled intensities per realization, shape (N+1, n_channels)

Secondary spline/internal attributes (lower priority):

  • n_spl, spline_logT, spline_log_dem, abundances, interpolated_responses

Motivation

  • Without @property definitions, Sphinx cannot generate API pages for these attributes and they cannot be cross-referenced from documentation using :attr: or ~xrtpy.xrt_dem_iterative.XRTDEMIterative.mc_dem style links.
  • Users have no in-code documentation (docstrings) for what each result attribute contains, its shape, or its units.
  • Raised during review of PR XRT DEM Iterative Solver Module #367 by @namurphy — see comment on dem_overview.rst lines 175–177.
  • Consistent with the existing pattern in XRTDEMIterative where input parameters like observed_intensities, intensity_uncertainties, monte_carlo_runs, etc. are already implemented as properties with docstrings.

Implementation strategy

For each attribute:

  1. Rename the internal storage to self._xxx wherever it is assigned (in solve(), create_logT_grid(), _run_monte_carlo(), etc.)
  2. Add a @Property with a NumPy-style docstring specifying type, shape, and units
  3. Verify that dem_plotting.py and all test files still work — since the public name stays the same, no changes should be needed there
  4. Update dem_overview.rst to use Sphinx cross-reference links like ~xrtpy.xrt_dem_iterative.XRTDEMIterative.mc_dem once the properties exist

Files to modify: xrtpy/xrt_dem_iterative/dem_solver.py, docs/dem_overview.rst
Files to verify (no changes expected) - maybe : xrtpy/xrt_dem_iterative/dem_plotting.py, xrtpy/xrt_dem_iterative/test/test_dem_solver.py

Additional context

To be addressed in a follow-up PR after PR #367 (XRT DEM Iterative Solver) is merged. Extra detailed PR so it's easier to approach.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Code ImprovementFor general improvements to the codebase without adding new features.documentationImprovements or additions to documentationenhancementNew feature or requestgood first issueGood for newcomers

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions