CLI Tutorial: A Step-by-Step Guide
This comprehensive guide walks you through the complete workflow using the
microlens-submit CLI, from initial project setup to final submission export.
Note
CLI vs Python API
The CLI always operates on saved (on-disk) solutions and events. There is no concept of an “unsaved” solution in the CLI (except when using –dry-run, which does not persist anything).
In the Python API, you can create solutions/events in memory and remove them before saving. In the CLI, every change is immediately saved to disk.
Prerequisites
Python 3.8 or higher
microlens-submitinstalled (pip install microlens-submit)Basic familiarity with command-line interfaces
Understanding of microlensing parameters and models
Learning Objectives
This turorial is designed to help you manage you submission project effectively, by using the microlens-submit CLI to do the following
Project Initialization: Set up your submission project structure
Solution Addition: Add microlensing solutions with parameters and metadata
Bulk Importing Solutions from CSV
Validation: Check your solutions for completeness and consistency
Documentation: Add notes and generate review materials
Export: Create the final submission package
Tutorial Contents
The in-depth contents of this tutorial are organized as follows:
Step-by-Step Guide
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
If microlens-submit is not found after pip install, your
Python Scripts folder is likely missing from PATH. Try py -m pip install
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
Start by creating a new submission project with your team information:
microlens-submit init --team-name "Your Team" \
--tier "beginner" /path/to/project
Note
If you need to update your team name, tier, or other top-level submission
info later, you can simply re-run microlens-submit init in the same
project directory. This will overwrite the submission.json metadata
with your new values, but will not affect your events or solutions. It’s
a quick way to fix mistakes without editing the JSON file directly. If you
pass a project path, init creates that directory. Run subsequent
commands from inside it (cd /path/to/project), or re-run init
without a path while already inside the project directory.
This creates the project directory structure and initializes the submission metadata.
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
not applicable.
If you are working on Roman Nexus, you can use nexus-init instead of
init to auto-populate hardware info.
GitHub Integration:
Set your repository URL for automatic linking in the dossier:
microlens-submit set-repo-url https://github.com/team/microlens-analysis \
/path/to/project
Hardware Information:
Provide details about your compute environment for resource tracking:
microlens-submit set-hardware-info \
--cpu-details "Intel Xeon Gold 6248" \
--ram-gb 128 \
--gpu "NVIDIA A100" \
--gpu-count 1 \
--gpu-memory-gb 40 \
/path/to/project
If you don’t have GPU information or are running on CPU-only hardware, you can omit the GPU options.
If you are using Roman Nexus, you can run nexus-init instead of
init to automatically populate your hardware information based on
the Nexus node you are using. This will set the CPU details, RAM, and
indicate that there is no GPU.
If you use different compute environments for different solutions, you can also set solution-level hardware overrides (see Solution-level hardware overrides for details).
3. Add Your First Solution
Add a microlensing solution with all required parameters:
microlens-submit add-solution EVENT123 1S1L \
--param t0=555.5 --param u0=0.1 --param tE=25.0 \
--log-likelihood -1234.56 \
--n-data-points 1250 \
--cpu-hours 15.2 \
--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
Required Parameters
Event ID: Unique identifier for the microlensing event
Model type: Microlensing model (1S1L, 1S2L, 2S1L, etc.)
Model parameters: Specific to the model type (see also Parameter File Support)
Now for a lengthy aside on some of these features that are especially important for documentation and evaluation. Skip to 4. to return to the main workflow.
Parameter File Support:
You can also load parameters from a JSON or YAML file instead of listing them on the command line.
# Create a parameter file with uncertainties
cat > params.yaml << EOF
parameters:
t0: 2459123.5
u0: 0.15
tE: 20.5
q: 0.001
s: 1.15
alpha: 45.2
uncertainties:
t0: [0.1, 0.1]
u0: 0.02
tE: [0.3, 0.4]
q: 0.0001
s: 0.05
alpha: 2.0
EOF
Create the above params.yaml containing your values and run:
# Use the parameter file
microlens-submit add-solution EVENT123 1S2L \
--params-file params.yaml \
--lightcurve-plot-path plots/event123_lc.png \
--lens-plane-plot-path plots/event123_lens.png \
--notes "Initial fit" \
--higher-order-effect parallax,finite-source
Use structured parameter files for complex models or to fascilitate integration with fitting pipelines. The file can include both parameters and uncertainties in JSON or YAML format (see examples below). This is especially useful for models with many parameters or when you want to include uncertainty information without cluttering the command line.
Parameter File Formats:
Simple Format (Parameters Only):
{
"t0": 555.5,
"u0": 0.1,
"tE": 25.0
}
Or in YAML:
t0: 555.5
u0: 0.1
tE: 25.0
Structured Format (Parameters + Uncertainties):
{
"parameters": {
"t0": 555.5,
"u0": 0.1,
"tE": 25.0
},
"uncertainties": {
"t0": [0.1, 0.1],
"u0": 0.02,
"tE": [0.3, 0.4]
}
}
Or in YAML:
parameters:
t0: 555.5
u0: 0.1
tE: 25.0
uncertainties:
t0: [0.1, 0.1]
u0: 0.02
tE: [0.3, 0.4]
Uncertainty Metadata:
Uncertainties can be single values (symmetric) or [lower, upper] arrays (asymmetric). Both JSON and YAML formats are supported with the same structure.
Tip
Include metadata about how uncertainties were derived to help evaluators interpret your results correctly. This is especially important for automated evaluation of physical parameters.
# Add solution with MCMC uncertainties
microlens-submit add-solution EVENT123 1S2L \
--params-file params.json \
--param-uncertainty t0=0.01 \
--param-uncertainty u0=[0.005,0.008] \
--uncertainty-method mcmc_posterior \
--confidence-level 0.68
# Add physical parameters with propagated uncertainties
microlens-submit add-solution EVENT456 1S1L \
--params-file params.json \
--physical-param Mtot=0.45 \
--physical-param D_L=5.2 \
--physical-param-uncertainty Mtot=0.08 \
--physical-param-uncertainty D_L=0.3 \
--uncertainty-method propagation \
--confidence-level 0.68
Available uncertainty methods:
mcmc_posterior: From MCMC posterior distributionsfisher_matrix: From Fisher information matrixbootstrap: From bootstrap resamplingpropagation: From error propagation of fitted parametersinference: From Bayesian inferenceliterature: From published values or external constraintsother: Custom or unspecified method
Confidence levels:
0.68: 1-sigma confidence interval (default)0.95: 2-sigma confidence interval0.997: 3-sigma confidence intervalCustom values between 0 and 1
Note
While uncertainties are optional, providing them along with the method and confidence level is strongly recommended for solutions you want evaluated. This helps distinguish high-confidence fits from preliminary results.
4. Bulk Importing Solutions from CSV
You can import multiple solutions at once from a CSV file using the bulk import command. This is especially useful for large teams or automated pipelines.
microlens-submit import-solutions path/to/your_solutions.csv
Bulk Import Features
Supports individual parameter columns or a JSON parameters column
Handles solution aliases, notes, and higher-order effects
Duplicate handling: error (default), override, or ignore
Supports dry-run and validation options
File paths are resolved relative to the current working directory or with –project-path
Example CSVs:
See tests/data/test_import.csv in the repository for a comprehensive example covering all features and edge cases. You can use this file as a template for your own imports.
Basic CSV format:
# event_id,solution_alias,model_tags,t0,u0,tE,s,q,alpha,notes
OGLE-2023-BLG-0001,simple_1S1L,"[""1S1L""]",2459123.5,0.1,20.0,,,,,"# Simple Point Lens"
OGLE-2023-BLG-0001,binary_1S2L,"[""1S2L""]",2459123.5,0.1,20.0,1.2,0.5,45.0,"# Binary Lens"
OGLE-2023-BLG-0002,finite_source,"[""1S1L"", ""finite-source""]",2459156.2,0.08,35.7,,,,,"# Finite Source"
Project Management Commands
The following caommand may help you to manage multiple events and solutions efficiently:
# List all events
cd <project_directory>
ls events/
# Check project status
microlens-submit validate-submission
# View project structure
tree -I '*.pyc|__pycache__'
5. Validate without saving
Test your solution before committing it to disk:
microlens-submit add-solution EVENT123 1S2L \
--param t0=555.5 --param u0=0.1 --param tE=25.0 \
--dry-run
This prints the parsed input, resulting schema output, and validation results without writing anything to disk. Any parameter validation warnings will be displayed. This is especially useful for checking relative probability assignments before saving.
6. Validate existing solutions
Check your solutions for completeness and consistency:
# Validate a specific solution
microlens-submit validate-solution <solution_id>
# Validate all solutions for an event
microlens-submit validate-event EVENT123
# Validate the entire submission
microlens-submit validate-submission
These commands check parameter completeness, types, and physical consistency based on the model type and higher-order effects. They also validate that relative probabilities for active solutions in each event sum to 1.0.
7. Attaching files
You can attach files (e.g., posterior samples, plots, or markdown notes files) to your solutions and track their paths in the project. This allows you to include rich documentation and visualizations in your submission dossier.
Posterior samples
After generating a posterior sample (e.g., an MCMC chain), store the file within your project and record its relative path using the CLI:
microlens-submit edit-solution <solution_id> --posterior-path posteriors/chain.h5
Tip
Make sure to place the files within your project directory and use the relative paths.
Plots and visualizations
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.
microlens-submit edit-solution <solution_id> \
--lightcurve-plot-path plots/event123_lc.png \
--lens-plane-plot-path plots/event123_lens.png
Notes
The notes for each solution are always stored as a Markdown file, and the path is tracked in the solution JSON. You can:
Use
--notes-file <path>to specify an existing Markdown file (the path is stored as-is).Use
--notes <string>to create a canonical notes file atevents/<event_id>/solutions/<solution_id>.md(the path is stored automatically).If neither is provided, an empty canonical notes file is created.
You can append to notes later with
microlens-submit edit-solution <solution_id> --append-notes "More details after review."
Or open the notes file in your editor (using $EDITOR, nano, or vi) with
microlens-submit notes <solution_id>
Tip
Notes support full Markdown formatting (headers, lists, code, tables, links, etc.).
The notes file is included in the exported zip and rendered in the HTML dossier.
Quick Notes Editing:
The microlens-submit notes <solution_id> command is a convenient way to
quickly edit solution notes:
# Open notes in your default editor
microlens-submit notes <solution_id>
This will:
Open the notes file in your $EDITOR environment variable
If $EDITOR is not set, it will try nano, then vi
Save changes automatically when you exit the editor
Validate the markdown formatting
Editor Configuration:
You can set your preferred editor by setting the $EDITOR environment variable:
# Set VS Code as your default editor
export EDITOR="code --wait"
# Set Vim as your default editor
export EDITOR="vim"
# Set Emacs as your default editor
export EDITOR="emacs"
# Then use the notes command
microlens-submit notes <solution_id>
Tip
Windows 11 tip:
If you have VS Code installed, set EDITOR=code (the CLI will add
--wait). Otherwise, the notes command will fall back to Notepad or
your default app.
Alternative Editing Methods:
You can also edit notes directly or use the append method:
# Method 1: Direct file editing (if you know the path)
nano events/EVENT123/solutions/<solution_id>.md
# Method 2: Append to existing notes
microlens-submit edit-solution <solution_id> \
--append-notes "Additional analysis results..."
# Method 3: Replace notes entirely
microlens-submit edit-solution <solution_id> \
--notes "Complete replacement of notes content"
Rich Documentation with Markdown Notes:
The notes field supports full Markdown formatting, allowing you to create rich, structured documentation for your solutions. This is particularly valuable for creating detailed submission dossiers for evaluators.
Example: Comprehensive Solution Documentation
Create detailed notes with markdown formatting:
cat << 'EOF' > notes.md
# Binary Lens Solution for EVENT123
## Model Overview
This solution represents a **binary lens** with a planetary companion (q = 0.001).
## Fitting Strategy
- **Sampling Method:** MCMC with 1000 walkers
- **Chain Length:** 50,000 steps per walker
- **Burn-in:** First 10,000 steps discarded
- **Convergence:** Gelman-Rubin statistic < 1.01 for all parameters
## Key Findings
1. **Planetary Signal:** Clear detection of a planetary companion
2. **Caustic Crossing:** Source crosses the planetary caustic
3. **Finite Source Effects:** ρ = 0.001 indicates significant finite source effects
## Physical Parameters
| Parameter | Value | Units |
|-----------|-------|-------|
| M_L | 0.45 ± 0.05 | M☉ |
| D_L | 6.2 ± 0.3 | kpc |
| M_planet | 1.5 ± 0.2 | M⊕ |
| a | 2.8 ± 0.4 | AU |
## Model Comparison
- **Single Lens:** Δχ² = 156.7 (rejected)
- **Binary Lens:** Best fit with ΔBIC = 23.4
## Code Reference
````python
# Fitting code snippet
import emcee
sampler = emcee.EnsembleSampler(nwalkers=1000, ndim=8, log_prob_fn=log_probability)
sampler.run_mcmc(initial_state, 50000)
````
## References
- [Gould & Loeb 1992](https://ui.adsabs.harvard.edu/abs/1992ApJ...396..104G)
- [Mao & Paczynski 1991](https://ui.adsabs.harvard.edu/abs/1991ApJ...374L..37M)
---
*Last updated: 2025-01-15*
EOF
microlens-submit add-solution EVENT123 1S2L \
--param t0=2459123.5 --param u0=0.12 --param tE=22.1 \
--param q=0.001 --param s=1.15 --param alpha=45.2 \
--alias "binary_planetary" \
--notes-file notes.md
Markdown Features Supported
Headers (
##,###, etc.) for section organizationBold and italic text for emphasis
Lists (numbered and bulleted) for structured information
Tables for parameter comparisons and data presentation
Code blocks for algorithm snippets and examples
Links to external references and documentation
Images (if referenced files exist in your project)
Mathematical expressions using LaTeX syntax
Appending to Existing Notes:
You can build up detailed documentation over time:
# Add initial notes
cat << 'EOF' > events/EVENT123/solutions/<solution_id>.md
# Initial Single Lens Fit
Basic point-source point-lens model as starting point.
EOF
microlens-submit add-solution EVENT123 1S1L \
--param t0=2459123.5 --param u0=0.15 --param tE=20.5 \
--notes-file events/EVENT123/solutions/<solution_id>.md
# Later, append additional analysis
cat << 'EOF' >> events/EVENT123/solutions/<solution_id>.md
## Follow-up Analysis
After reviewing the residuals, we identified systematic deviations
that suggest a more complex model is needed. The binary lens model
provides a significantly better fit (Δχ² = 156.7).
### Residual Analysis
- Peak deviation: 0.15 magnitudes
- Systematic pattern suggests caustic crossing
- Finite source effects may be important
EOF
8. Manage Solutions for the Same Event
When you have multiple solutions for the same event, you can manage them effectively using the CLI. This is important for comparing different models and specifying how they should be weighted in the evaluation. You are not limited to just one solution per event - you can add as many as you want and assign r elative probabilities to indicate their likelihood.
Add a competing solution
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:
When you have multiple solutions for the same event, you can compare them using the CLI. This will show you a table of all solutions for that event, including their model types, log-likelihood values, BIC scores, and relative probabilities.
Compare solutions using BIC-based relative probabilities:
microlens-submit compare-solutions EVENT123
Listing your solutions
Review all solutions for an event:
microlens-submit list-solutions EVENT123
Relative Probability Guidelines:
When assigning relative probabilities to multiple solutions for the same event, keep the following guidelines in mind:
Sum to 1.0: All active solutions in an event must have probabilities summing to 1.0
Automatic Calculation: If you provide log-likelihood and n_data_points, BIC-based probabilities are calculated automatically
Manual Override: You can set explicit probabilities based on your analysis
Single Solution: If only one active solution exists, its probability should be 1.0 or None
Validation: The system will warn you if probabilities don’t sum correctly
Deactivate the less-good solution
Deactivated solutions are kept in the project but excluded from exports. Use this when you want to keep the solution data for reference but don’t want it in your final submission.
microlens-submit deactivate <solution_id>
Remove mistake
Completely remove solutions or events that were created by mistake:
# Remove a saved solution (requires --force for safety)
microlens-submit remove-solution <solution_id> --force
# Remove an entire event and all its solutions (requires --force for safety)
microlens-submit remove-event <event_id> --force
What happens if you forget –force?
If you try to remove a saved solution or event without –force, you’ll get a helpful message and nothing will be deleted. For example:
$ microlens-submit remove-solution 12345678-1234-1234-1234-123456789abc
⚠ Refusing to remove solution 12345678... without --force.
💡 Consider using deactivate to keep the solution, or re-run with --force to proceed.
When to use removal vs deactivation:
Use deactivate() when you want to keep the solution data but exclude it from exports
Use remove_solution() when you made a mistake and want to completely clean up (requires –force in the CLI)
Use remove_event() when you created an event by accident and want to start over (requires –force in the CLI)
Safety Features
Saved solutions/events require
--forceto prevent accidental data lossRemoval cannot be undone - use deactivate() if you’re unsure
Temporary files (notes in tmp/) are automatically cleaned up
Editing solution attributes
After creating solutions, you can modify their attributes:
# Update relative probability
microlens-submit edit-solution <solution_id> --relative-probability 0.7
# Append to notes
microlens-submit edit-solution <solution_id> --append-notes "Updated after model comparison"
# Update compute info
microlens-submit edit-solution <solution_id> --cpu-hours 25.5 --wall-time-hours 6.2
# Fix a parameter typo
microlens-submit edit-solution <solution_id> --param t0=2459123.6
# Update an uncertainty
microlens-submit edit-solution <solution_id> --param-uncertainty t0=[0.05,0.05]
# 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
# See what would change without saving
microlens-submit edit-solution <solution_id> --relative-probability 0.8 --dry-run
Solution Aliases:
You can assign human-readable aliases to your solutions for easier identification:
microlens-submit add-solution EVENT123 1S1L \
--param t0=555.5 --param u0=0.1 --param tE=25.0 \
--alias "best_fit" \
--notes "Initial fit"
Alias Features
Aliases must be unique within each event (e.g., you can’t have two solutions with alias “best_fit” in EVENT123)
Aliases are displayed as primary identifiers in dossier generation, with UUIDs as secondary
In the full dossier report, solutions are titled as “Solution: <event_id> <alias>” with UUID as subtitle
Aliases can be edited later using the edit-solution command
Solutions without aliases fall back to UUID-based identification
Editing solution aliases:
microlens-submit edit-solution <solution_id> --alias "updated_best_fit"
How to inspect solutions and resolve duplicate aliases:
If you re-run a notebook or script, you might accidentally reuse an alias. Aliases must be unique within each event, so the validator will complain. Use the steps below to inspect what already exists and decide how to fix it.
1) List solutions for the event
microlens-submit list-solutions EVENT123This shows all solution IDs and aliases for the event. Identify the conflicting alias and the solution ID you want to keep.
2) Validate a specific solution (optional)
microlens-submit validate-solution <solution_id>3) Rename the alias for the solution you just created
microlens-submit edit-solution <solution_id> --alias "new_alias"4) If it’s a true duplicate, deactivate or remove the extra solution
# Keep it for reference but exclude from exports microlens-submit deactivate <solution_id> # Or remove it entirely (saved solutions require --force) microlens-submit remove-solution <solution_id> --forceTip
If you are running a notebook multiple times, consider appending a timestamp or run label to the alias (e.g.,
best_fit_v2) to avoid collisions.
Example Solution Comparison Workflow:
When you have multiple solutions for the same event, it’s crucial to manage them effectively and specify how they should be weighted. Here’s a comprehensive workflow:
1. Add Multiple Solutions for Comparison:
# Add a simple single-lens solution microlens-submit add-solution EVENT123 1S1L \ --param t0=2459123.5 --param u0=0.15 --param tE=20.5 \ --alias "simple_1S1L" \ --log-likelihood -1234.56 --n-data-points 1250 \ --notes "Initial single-lens fit using MCMC sampling" # Add a more complex binary-lens solution microlens-submit add-solution EVENT123 1S2L \ --param t0=2459123.5 --param u0=0.12 --param tE=22.1 \ --param q=0.001 --param s=1.15 --param alpha=45.2 \ --alias "binary_1S2L" \ --log-likelihood -1189.34 --n-data-points 1250 \ --notes "Binary-lens fit with planetary companion. MCMC with 1000 walkers." # Add a third alternative solution microlens-submit add-solution EVENT123 1S2L \ --param t0=2459123.8 --param u0=0.18 --param tE=19.8 \ --param q=0.002 --param s=0.95 --param alpha=32.1 \ --alias "alternative_1S2L" \ --log-likelihood -1201.45 --n-data-points 1250 \ --notes "Alternative binary solution with different parameter space."2. Compare Solutions with Detailed Analysis:
# View comparison table microlens-submit compare-solutions EVENT123
- This will show:
Model types and parameter counts
Log-likelihood values
BIC scores (calculated automatically)
Relative probabilities (calculated automatically)
Higher-order effects used
3. Set Explicit Relative Probabilities:
If you want to override the automatic BIC-based calculation:
# Set explicit probabilities based on your analysis microlens-submit edit-solution <solution_id_1> --relative-probability 0.1 microlens-submit edit-solution <solution_id_2> --relative-probability 0.7 microlens-submit edit-solution <solution_id_3> --relative-probability 0.2 # Verify probabilities sum to 1.0 microlens-submit compare-solutions EVENT1234. Manage Solution States:
# Deactivate the worst solution (keeps it for reference) microlens-submit deactivate <solution_id_3> # Re-activate if needed later microlens-submit activate <solution_id_3> # Remove completely if it was a mistake microlens-submit remove-solution <solution_id_3> --force5. Update Solutions Based on Comparison:
# Refine the best solution with additional analysis microlens-submit edit-solution <solution_id_2> \ --append-notes " ## Model Comparison Results After comparing all three solutions: - **Simple 1S1L:** Δχ² = 156.7 vs binary models (rejected) - **Binary 1S2L (primary):** Best fit with ΔBIC = 23.4 - **Binary 1S2L (alternative):** ΔBIC = 11.2 vs primary The primary binary solution is clearly preferred, with the alternative binary solution having some merit but lower probability."6. Validate Your Final Solution Set:
# Check that everything is valid microlens-submit validate-event EVENT123 # Ensure relative probabilities sum to 1.0 for active solutions microlens-submit validate-submission
Solution Comparison Best Practices:
Start Simple: Always begin with a single-lens model as baseline
Document Decisions: Use notes to explain why you prefer certain solutions
Use Aliases: Give meaningful names to solutions for easier management
Keep History: Use deactivate() rather than remove() to preserve analysis history
Validate Regularly: Check that relative probabilities sum to 1.0
Consider Uncertainties: Include parameter uncertainties when available
Record Compute Time: Track computational resources for each solution
Solution-level hardware overrides (optional):
If a solution was produced on a different server or environment, you can attach per-solution hardware info without changing the submission-wide metadata.
# Autofill from the current environment
microlens-submit edit-solution <solution_id> --autofill-hardware-info
# Manual JSON override
microlens-submit edit-solution <solution_id> \
--hardware-info-json '{"cpu_details": "Xeon", "memory_gb": 128, "nexus_image": "roman-science-platform:latest"}'
# Clear the solution-level override
microlens-submit edit-solution <solution_id> --clear-hardware-info
9. Export the final package
Create the submission package for upload:
microlens-submit export submission.zipThis creates a zip file containing all active solutions and associated files, ready for submission to the challenge organizers.
10. Preview your submission dossier
Generate a human-readable HTML dashboard for review:
microlens-submit generate-dossierThis will create a human-readable HTML dashboard at
dossier/index.htmlinside your project directory. Open this file in your web browser to preview your submission as evaluators will see it.You can also serve the dossier with a simple local server:
cd dossier python3 -m http.serverThen open
http://localhost:8000in your browser.
- The dossier includes:
Team and submission metadata
Solution summaries and statistics
Progress bar and compute time
Event table and parameter distribution placeholders
Note
The dossier is for your review only and is not included in the exported submission zip.
Comprehensive Best Practices Guide
Best Practices for Using microlens-submit
Use dry-run: Always test with
--dry-runbefore savingValidate regularly: Check your submission frequently during development
Document thoroughly: Add detailed notes to explain your analysis
Version control: Use git to track changes to your project
Backup regularly: Keep copies of your project directory
Test export: Verify your submission package before final submission
Reproducibility:
Always use
--cpu-hoursand--wall-time-hoursto record computational detailsInclude version information for key dependencies in your notes
Use descriptive notes for each solution explaining your methodology
Record your analysis pipeline with code snippets and parameter choices
Document data preprocessing steps and quality cuts applied
# Example of comprehensive compute info
microlens-submit add-solution EVENT123 1S1L \
--param t0=2459123.5 --param u0=0.15 --param tE=20.5 \
--cpu-hours 15.2 --wall-time-hours 3.8 \
--notes "# Single Lens Analysis
## Analysis Pipeline
- **Data Source:** Roman DC2 2018-test tier
- **Preprocessing:** 3σ outlier removal, band-specific calibration
- **Fitting Method:** MCMC with 500 walkers, 20,000 steps
- **Software Versions:** MulensModel 2.8.1, emcee 3.1.4
- **Hardware:** 16-core Intel Xeon, 64GB RAM
## Quality Cuts
- Removed data points with mag_err > 0.1
- Applied systematic error floor of 0.02 mag
- Used only I-band data for final fit
## Convergence Criteria
- Gelman-Rubin statistic < 1.01 for all parameters
- Effective sample size > 1000 for all parameters
- Visual inspection of chain traces"
Workflow Management:
Save frequently with regular validation checks
Use
deactivate()instead of deleting solutions to preserve analysis historyKeep multiple solutions for comparison and model selection
Use meaningful aliases for easier solution identification
Organize your project structure with clear file naming conventions
# Example workflow with multiple solutions
microlens-submit add-solution EVENT123 1S1L \
--alias "baseline_1S1L" --notes "Baseline single-lens model"
microlens-submit add-solution EVENT123 1S2L \
--alias "planetary_1S2L" --notes "Planetary companion model"
# Compare and document your decision
microlens-submit compare-solutions EVENT123
# Deactivate the worse solution but keep for reference
microlens-submit deactivate <baseline_solution_id>
# Update the preferred solution with comparison results
microlens-submit edit-solution <planetary_solution_id> \
--append-notes "Selected over single-lens model: Δχ² = 156.7"
Data Quality:
Validate your parameters before adding solutions
Include uncertainties when available for better statistical analysis
Record the number of data points used in each fit
Document data quality cuts and preprocessing steps
Check for systematic errors and include them in your analysis
# Example with comprehensive data quality info
microlens-submit add-solution EVENT123 1S2L \
--param t0=2459123.5 --param u0=0.12 --param tE=22.1 \
--param q=0.001 --param s=1.15 --param alpha=45.2 \
--param-uncertainty t0=[0.1,0.1] --param-uncertainty u0=0.02 \
--param-uncertainty tE=[0.3,0.4] --param-uncertainty q=0.0001 \
--n-data-points 1250 \
--notes "# High-Quality Binary Lens Fit
## Data Quality Assessment
- **Total data points:** 1,450 (raw)
- **Points used in fit:** 1,250 (after quality cuts)
- **Systematic error floor:** 0.02 mag applied
- **Band coverage:** I-band primary, V-band secondary
- **Temporal coverage:** 2459120-2459130 (10 days)
## Uncertainty Analysis
- Parameter uncertainties from MCMC posterior distributions
- Asymmetric uncertainties for t0 and tE due to light curve asymmetry
- Systematic uncertainties included in error budget"
Performance Optimization:
The tool is designed for long-term projects with efficient handling of large numbers of solutions
Export only when ready for final submission to avoid unnecessary processing and data duplication. You can build dossiers and validate without exporting.
Use bulk import if you did not integrate this tool into your analysis pipeline from the start.
Organize your file structure efficiently with clear naming conventions
Monitor disk space for large posterior files and plots. Be mindful that they will need to be duplicated into the export zip when you run the export command.
# Example of efficient bulk processing
# Create a CSV file with all your solutions
cat > solutions.csv << EOF
event_id,solution_alias,model_tags,t0,u0,tE,log_likelihood,n_data_points,notes
EVENT123,baseline,["1S1L"],2459123.5,0.15,20.5,-1234.56,1250,"Baseline model"
EVENT123,planetary,["1S2L"],2459123.5,0.12,22.1,-1189.34,1250,"Planetary model"
EVENT124,simple,["1S1L"],2459156.2,0.08,35.7,-2156.78,2100,"Simple fit"
EOF
# Bulk import all solutions at once
microlens-submit import-solutions solutions.csv --validate
# Generate dossier for review
microlens-submit generate-dossier
# Export only when ready for submission
microlens-submit export final_submission.zip
Troubleshooting
Common Issues and Solutions:
1. Validation Errors:
Check that all required parameters are provided for your model type
Ensure relative probabilities sum to 1.0 for active solutions
Verify parameter types (numbers vs strings)
2. File Path Issues:
Use relative paths from the project root
Ensure referenced files exist before adding solutions
Check file permissions for reading/writing
3. Model Type Errors:
Verify model type spelling (1S1L, 1S2L, 2S1L, etc.)
Check that parameters match the model type requirements
Ensure higher-order effects are compatible with the model
4. Export Problems:
Make sure at least one solution is active per event
Check that all referenced files exist
Verify the export path is writable
Getting Help
Documentation: This tutorial and the API reference
GitHub Issues: Report bugs or request features
Validation Messages: Read the detailed error messages for guidance