chore: update version to 0.17.5 and enhance CLI tutorial with new file attachment features

Author: AmberLee2427

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.17.5] - 2026-02-09
+
+### Added
+- CLI support for attaching posterior samples via `add-solution` (`--posterior-path`).
+- CLI commands to edit and clear solution file paths (`--posterior-path`, `--lightcurve-plot-path`, `--lens-plane-plot-path`) in `edit-solution`.
+
+### Changed
+- Updated CLI tutorial regarding file attachments (plots and posteriors).
+
+
 ## [0.17.4] - 2026-02-09
 
 ### Added

CITATION.cff

@@ -1,9 +1,9 @@
 cff-version: 1.2.0
 message: "If you use microlens-submit, please cite it as below."
 title: "microlens-submit"
-version: "0.17.4"
+version: "0.17.5"
 authors:
   - family-names: Malpas
     given-names: Amber
 url: "https://github.com/AmberLee2427/microlens-submit"
-doi: "10.5281/zenodo.18558755"
+doi: "10.5281/zenodo.18580965"

README.md

@@ -160,15 +160,15 @@ import this file directly.
 
 Bibtex:
 ```
-@software{malpas_2025_18558755,
+@software{malpas_2025_18580965,
   author       = {Malpas, Amber},
   title        = {microlens-submit},
   month        = oct,
   year         = 2025,
   publisher    = {Zenodo},
   version      = {v0.16.3},
-  doi          = {10.5281/zenodo.18558755},
-  url          = {https://doi.org/10.5281/zenodo.18558755},
+  doi          = {10.5281/zenodo.18580965},
+  url          = {https://doi.org/10.5281/zenodo.18580965},
 }
 ```
 

RELEASE_NOTES.md

@@ -1,18 +1,14 @@
-# microlens-submit v0.17.4 Release Notes
+# microlens-submit v0.17.5 Release Notes
 
 **Release Date:** 2026-02-09
 
 ## Changelog
 
-## [0.17.4] - 2026-02-09
+## [0.17.5] - 2026-02-09
 
 ### Added
-- Added `regenerate` flag for `notebook_display_solution()` to force HTML refresh.
+- CLI support for attaching posterior samples via `add-solution` (`--posterior-path`).
+- CLI commands to edit and clear solution file paths (`--posterior-path`, `--lightcurve-plot-path`, `--lens-plane-plot-path`) in `edit-solution`.
 
 ### Changed
-- Dossier notebook rendering now inlines local plot images referenced by solution pages.
-- Temporary notes created without a project root now track their absolute location.
-
-### Fixed
-- Submission save now relocates temporary notes even when the tmp file lives outside the project directory.
-- Conda recipe now uses the `pypi.io` source URL to avoid PyPI source 404s during build.
+- Updated CLI tutorial regarding file attachments (plots and posteriors).

conda/recipe/meta.yaml

@@ -1,6 +1,6 @@
 {% set name = "microlens-submit" %}
 {% set filename_name = name | replace("-", "_") %}
-{% set version = "0.17.4" %}
+{% set version = "0.17.5" %}
 {% set python_min = "3.10" %}
 
 # NOTE: This recipe is the source of truth for conda-forge. Edit it here in

docs/cli_tutorial.rst

@@ -41,8 +41,15 @@ The in-depth contents of this tutorial are organized as follows:
 **Step-by-Step Guide**
 ######################
 
-If your terminal does not support ANSI escape codes, add ``--no-color`` to
-disable colored output.
+In this section, we will go through the complete workflow of using the
+``microlens-submit`` CLI to manage your Roman Microlensing Data Challenge
+2026 submission project. Each step includes detailed explanations, command
+examples, and tips for best practices.
+
+.. attention:: Terminal Compatibility
+
+   If your terminal does not support ANSI escape codes, add ``--no-color`` to
+   disable colored output.
 
 .. tip:: **Windows PATH tip**
 
@@ -51,7 +58,7 @@ disable colored output.
    microlens-submit`` and run ``py -m microlens_submit.cli --help``, or add
    the Scripts path shown by ``py -m pip show -f microlens-submit`` to PATH.
 
-1. **Initialize your project**
+1. **Initialize Your Project**
 ******************************
 
 Start by creating a new submission project with your team information:
@@ -81,8 +88,10 @@ metadata.
    - ``--tier``: Challenge tier ("beginner" or "experienced")
    - Project path: Where to create the project directory
 
-2. **Record repository and hardware info**
-******************************************
+.. _compute_information:
+
+2. **Record Repository and Hardware Information**
+*************************************************
 
 Before validation and export, set your repository URL and hardware details.
 GPU information is optional (Roman Nexus nodes are CPU-only), so omit it if
@@ -126,7 +135,7 @@ can also set solution-level hardware overrides (see
 `Solution-level hardware overrides <solution_hardware_overrides_>`__
 for details).
 
-3. **Add your first solution**
+3. **Add Your First Solution**
 ******************************
 
 Add a microlensing solution with all required parameters:
@@ -141,6 +150,7 @@ Add a microlensing solution with all required parameters:
          --wall-time-hours 3.8 \
          --lightcurve-plot-path plots/event123_lc.png \
          --lens-plane-plot-path plots/event123_lens.png \
+         --posterior-path posteriors/chain.h5 \
          --notes "Initial fit" \
          --higher-order-effect parallax,finite-source
 
@@ -152,13 +162,14 @@ Add a microlensing solution with all required parameters:
 
 .. admonition:: **Optional Metadata**
 
-   - Log-likelihood and data points for statistical analysis
-   - Compute information for resource tracking
+   - `Log-likelihood <solution_comparison_>`__ and data points for statistical analysis
+   - `Compute information <compute_information_>`__ for resource tracking
    - Physical parameters (``--physical-param Mtot=0.5``)
-   - Parameter uncertainties (``--param-uncertainty t0=[1.1,1.3]``)
+   - `Parameter uncertainties <uncertainty_metadata_>`__ (``--param-uncertainty t0=[1.1,1.3]``)
    - Physical parameter uncertainties (``--physical-param-uncertainty Mtot=0.08``)
    - `Uncertainty metadata <uncertainty_metadata_>`__ (``--uncertainty-method mcmc_posterior --confidence-level 0.68``)
-   - Plot paths for visualization files
+   - `Plot paths <plots_>`__ for visualization files
+   - `Posterior samples file <posteriors_>`__ (``--posterior-path``)
    - `Notes <notes_>`__ for documentation
    - Higher-order effects for advanced models
    - `Solution aliases <solution_aliases_>`__ for easier identification
@@ -218,7 +229,7 @@ cluttering the command line.
 **Parameter File Formats:**
 ---------------------------
 
-**Simple format (parameters only):**
+**Simple Format (Parameters Only):**
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: json
@@ -237,7 +248,7 @@ Or in YAML:
    u0: 0.1
    tE: 25.0
 
-**Structured format (parameters + uncertainties):**
+**Structured Format (Parameters + Uncertainties):**
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: json
@@ -442,30 +453,30 @@ include rich documentation and visualizations in your submission dossier.
 =====================
 
 After generating a posterior sample (e.g., an MCMC chain), store the file
-within your project and record its relative path using the Python API::
+within your project and record its relative path using the CLI:
 
-   >>> sub = microlens_submit.load("/path/to/project")
-   >>> evt = sub.get_event("EVENT123")
-   >>> sol = next(iter(evt.solutions.values()))
-   >>> sol.posterior_path = "posteriors/chain.h5"
-   >>> sol.lightcurve_plot_path = "plots/event123_lc.png"
-   >>> sol.lens_plane_plot_path = "plots/event123_lens.png"
-   >>> sub.save()
+.. code-block:: bash
 
-.. note::
+   microlens-submit edit-solution <solution_id> --posterior-path posteriors/chain.h5
+
+.. tip::
 
-   The CLI does not currently have a command for attaching arbitrary files,
-   but you can use the Python API to set any file paths you want tracked
-   in the solution JSON or edit the JSON files directly. Just make sure to
-   place the files within your project directory and save the relative paths.
+   Make sure to place the files within your project directory and use the
+   relative paths.
 
 .. _plots:
 
 **Plots and visualizations**
 ============================
 
-You can attach any plots or visualizations by saving them in your project and
-tracking their paths in the solution JSON.
+The submission packets are limited to two images per solution; the light-curve and lens-plane plots.
+You can attach any by saving them in your project and tracking their paths in the solution JSON.
+
+.. code-block:: bash
+
+   microlens-submit edit-solution <solution_id> \
+         --lightcurve-plot-path plots/event123_lc.png \
+         --lens-plane-plot-path plots/event123_lens.png
 
 .. _notes:
 
@@ -685,6 +696,8 @@ Add alternative models for comparison:
    microlens-submit add-solution EVENT123 1S1L \
          --param t0=556.0 --param u0=0.2 --param tE=24.5
 
+.. _solution_comparison:
+
 **Solution Comparison:**
 ========================
 
@@ -793,6 +806,9 @@ After creating solutions, you can modify their attributes:
    # Add higher-order effects
    microlens-submit edit-solution <solution_id> --higher-order-effect parallax,finite-source
 
+   # Update plot paths
+   microlens-submit edit-solution <solution_id> --lightcurve-plot-path plots/new_lc.png
+
    # Clear an attribute
    microlens-submit edit-solution <solution_id> --clear-relative-probability
 

docs/conf.py

@@ -8,7 +8,7 @@
 author = "RGES-PIT"
 
 # The full version, including alpha/beta/rc tags
-release = "0.17.4"
+release = "0.17.5"
 
 extensions = [
     "sphinx.ext.autodoc",

microlens_submit/__init__.py

@@ -5,7 +5,7 @@
 the command line interface.
 """
 
-__version__ = "0.17.4"
+__version__ = "0.17.5"
 
 from .models import Event, Solution, Submission
 from .utils import load

microlens_submit/cli/commands/solutions.py

@@ -238,6 +238,11 @@ def add_solution(
         "--lens-plane-plot-path",
         help="Path to lens plane plot file " "(relative to project directory) [ADVANCED]",
     ),
+    posterior_path: Optional[Path] = typer.Option(
+        None,
+        "--posterior-path",
+        help="Path to posterior samples file " "(relative to project directory) [ADVANCED]",
+    ),
     alias: Optional[str] = typer.Option(
         None,
         "--alias",
@@ -316,6 +321,7 @@ def add_solution(
         sol.set_compute_info(cpu_hours=cpu_hours, wall_time_hours=wall_time_hours, git_dir=sub.git_dir)
     sol.lightcurve_plot_path = str(lightcurve_plot_path) if lightcurve_plot_path else None
     sol.lens_plane_plot_path = str(lens_plane_plot_path) if lens_plane_plot_path else None
+    sol.posterior_path = str(posterior_path) if posterior_path else None
     # Handle notes file logic
     canonical_notes_path = Path(project_path) / "events" / event_id / "solutions" / f"{sol.solution_id}.md"
     if notes_file is not None:
@@ -343,6 +349,7 @@ def add_solution(
             "wall_time_hours": wall_time_hours,
             "lightcurve_plot_path": (str(lightcurve_plot_path) if lightcurve_plot_path else None),
             "lens_plane_plot_path": (str(lens_plane_plot_path) if lens_plane_plot_path else None),
+            "posterior_path": (str(posterior_path) if posterior_path else None),
             "alias": alias,
             "notes_path": sol.notes_path,
         }
@@ -552,6 +559,24 @@ def edit_solution(
         help="Higher-order effects (replaces existing effects)",
     ),
     clear_higher_order_effects: bool = typer.Option(False, help="Clear all higher-order effects"),
+    lightcurve_plot_path: Optional[Path] = typer.Option(
+        None,
+        "--lightcurve-plot-path",
+        help="Path to lightcurve plot file (relative to project directory)",
+    ),
+    lens_plane_plot_path: Optional[Path] = typer.Option(
+        None,
+        "--lens-plane-plot-path",
+        help="Path to lens plane plot file (relative to project directory)",
+    ),
+    posterior_path: Optional[Path] = typer.Option(
+        None,
+        "--posterior-path",
+        help="Path to posterior samples file (relative to project directory)",
+    ),
+    clear_lightcurve_plot_path: bool = typer.Option(False, help="Clear lightcurve plot path"),
+    clear_lens_plane_plot_path: bool = typer.Option(False, help="Clear lens plane plot path"),
+    clear_posterior_path: bool = typer.Option(False, help="Clear posterior sample path"),
     dry_run: bool = typer.Option(
         False,
         "--dry-run",
@@ -699,6 +724,40 @@ def edit_solution(
                 f"Update higher_order_effects: {target_solution.higher_order_effects} {arrow} {higher_order_effect}"
             )
             target_solution.higher_order_effects = higher_order_effect
+
+    if clear_lightcurve_plot_path:
+        if target_solution.lightcurve_plot_path:
+            changes.append(f"Clear lightcurve_plot_path: {target_solution.lightcurve_plot_path}")
+            target_solution.lightcurve_plot_path = None
+    elif lightcurve_plot_path is not None:
+        old_val = target_solution.lightcurve_plot_path
+        new_val = str(lightcurve_plot_path)
+        if old_val != new_val:
+            changes.append(f"Update lightcurve_plot_path: {old_val} {arrow} {new_val}")
+            target_solution.lightcurve_plot_path = new_val
+
+    if clear_lens_plane_plot_path:
+        if target_solution.lens_plane_plot_path:
+            changes.append(f"Clear lens_plane_plot_path: {target_solution.lens_plane_plot_path}")
+            target_solution.lens_plane_plot_path = None
+    elif lens_plane_plot_path is not None:
+        old_val = target_solution.lens_plane_plot_path
+        new_val = str(lens_plane_plot_path)
+        if old_val != new_val:
+            changes.append(f"Update lens_plane_plot_path: {old_val} {arrow} {new_val}")
+            target_solution.lens_plane_plot_path = new_val
+
+    if clear_posterior_path:
+        if target_solution.posterior_path:
+            changes.append(f"Clear posterior_path: {target_solution.posterior_path}")
+            target_solution.posterior_path = None
+    elif posterior_path is not None:
+        old_val = target_solution.posterior_path
+        new_val = str(posterior_path)
+        if old_val != new_val:
+            changes.append(f"Update posterior_path: {old_val} {arrow} {new_val}")
+            target_solution.posterior_path = new_val
+
     if dry_run:
         if changes:
             console.print(Panel(f"Changes for {solution_id} (event {target_event_id})", style="cyan"))

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "microlens-submit"
-version = "0.17.4"
+version = "0.17.5"
 authors = [
   { name="Amber Malpas", email="malpas.1@osu.edu" },
   {name = "Roman Science Platform Team", email = "roman-science-platform@stsci.edu"}