Skip to content

Examples

Full walkthroughs, each pairing a DATA_DESCRIPTION.md convention with a TASK.md request. The data paths below (data/my_survey/ etc.) are placeholders for your own catalogue directory — substitute the real path to whatever you're analysing.

1. Single-bin, full-sky clustering

Data: data/my_survey/ — see the full DATA_DESCRIPTION.md example. No mask, no tomography, galaxy_density only.

@cosmotron compute the angular power spectrum for the galaxy catalogue in
data/my_survey/ at nside=256.

Walks: bootstrap_session (resolves nside=256, full_sky=true) → ingest_to_session (single bin, no z_edges) → compute_cls_from_session → plot_cls_comparison → build_review_evidence → REVIEW: PASS. See Session model for what each step writes.

2. Tomographic clustering (multi-bin)

Data: data/my_survey_tomo/. Multiple redshift bins, still full-sky.

@cosmotron compute Cls for data/my_survey_tomo/, tomographic, nside=256.

## plots:
cls_grid

ingest_to_session is called with z_edges (or a bin_col, if the catalogue has one — see Multi-format ingestion), producing one manifest entry per bin. compute_all_cls_from_session computes every auto- and cross-spectrum in one call.

3. Masked tomographic clustering

Data: data/my_survey_masked/. Same as above, plus a survey mask — exercises apodisation and the non-full-sky covariance path.

@cosmotron compute Cls and covariance for data/my_survey_masked/,
tomographic, nside=256, apodisation_scale=1.0.

bootstrap_session resolves apodise_mask=true and pins apodisation_scale; full_sky=false follows from the mask being present (see Session model).

4. Cosmic shear

Data: data/my_survey_shear/. Spin-2, single-probe.

@cosmotron compute cosmic shear power spectra for data/my_survey_shear/ at
nside=512.

## probes:
galaxy_shear: sigma_e=0.28

ingest_to_session detects probe="galaxy_shear", standardises E1/E2, computes shot noise from sigma_e/n_eff_arcmin2, and compute_cls_from_session persists EE alongside cls_BB/cls_EB for the B-mode null tests. This is also the shape of task that triggers @systematics_checker's B-mode + PSF-leakage checks.

5. Full 3×2pt with inference

See the full example TASK.md for the complete task text — a joint galaxy_density + galaxy_shear analysis with adjacent-bin correlations, then a CosmoSIS nautilus chain sampling Omega_c/sigma8 against the resulting SACC.

6. Running heavy steps on a cluster

Data: data/my_survey_tomo/ on the Spark. Maps/spectra run locally; the covariance and the inference chain run as Slurm jobs on a configured cluster.

@cosmotron tomographic 3×2pt on data/my_survey_tomo/ at nside=1024.

## remote:
site: sunrise
covariance, inference

bootstrap_session resolves pipeline_config.remote = {site: sunrise, steps: [covariance, inference]} and pins the session to that site. Add a queue: bigmem line under site: to send both steps to a non-default sites.yaml queue instead of their resource class's own default. @analysis_coder calls compute_full_covariance_from_session / @inference calls run_inference exactly as in the local examples above — the tools auto-attach the jobspec, submit Slurm jobs, and the agents poll them to completion; the covariance JSON and the chain land back in the session, and review runs locally. Prerequisite: a sites.yaml entry + cosmotron-remote bootstrap sunrise (see Remote execution). To run from data that already lives on the cluster, use a site:path instead: @cosmotron analyse sunrise:/cfs/nobackup/mygroup/my_survey/ at nside=1024 (ingest then runs remotely too). See Data placement.

7. Driving it from a saved TASK.md file

The examples above inline every parameter into one prompt line. In practice, for anything beyond a quick one-off, it's easier to write the request down as a file once and point the agent at it. Save something like this as, say, tasks/my_analysis.md:

# TASK: Tomographic clustering with covariance

## Data
data_folder: ./data/my_survey_tomo/

## Analysis Task
Compute Cls for the catalogue using NaMaster with maps at nside=256,
lmin=10 and lmax=256 in 10 multipole bins. There are 3 tomographic bins;
compute both auto and cross power spectra. Save the Cls in SACC format,
using the NZ tracer to store the redshift distribution, and include the
covariance in the SACC file. No systematics checks needed.

### Plots to make:
1. Estimated Cls (noise-removed) vs the theory Cl in the data folder —
   unbinned theory, y-axis ell*C_ell, include the noise power spectrum and
   error bars from the covariance.
2. Calibrated n(z) vs a histogram of the catalogue redshifts.
3. Covariance, with colour bar and ell values on both axes.

Then, in opencode:

@cosmotron follow the task in tasks/my_analysis.md

or in Claude Code:

/cosmotron ./data/my_survey_tomo/ follow the task in tasks/my_analysis.md

@cosmotron reads the file's free text the same way it reads an inline prompt — the ## Data/## Analysis Task sections here are a readability convention, not the deterministically-parsed grammar (that's the ## probes:/## correlations:/## plots: sections documented in Writing TASK.md; you can mix both styles in the same file). Keeping the request in a file makes it easy to re-run, diff, and review before handing it to the agent.

Registering a dataset first

Any of the above can be preceded by registering the data directory once, so repeat runs skip standardisation entirely:

from cosmotron_mcp.tools import register_dataset
register_dataset("data/my_survey_masked", name="my_survey_masked", version="v1")

See The dataset registry for the full registration-decision flow, including what happens on a first unregistered ingest (the registration_pending gate) rather than a proactive register_dataset call.