coordinate-transform-recipes

Coordinate transform recipes: PySPEDAS/IDL cotrans to Agent Kit routes

Use this skill when a prompt mentions PySPEDAS cotrans, IDL SPEDAS cotrans, THEMIS/MMS coordinate cribs, tplot coordinate metadata, FAC, MVA, LMN, quaternions, GSE/GSM/GEI/SM/GEO/J2000, or "convert this variable/vector to another frame". It is a route-scout and provenance checklist, not a new tool: it tells an agent which existing Agent Kit skill/tool path fits the request and when a PySPEDAS/IDL routine is only an external runtime route.

MCP/default-surface boundary

When documenting PySPEDAS or IDL coordinate routines, use the structured marker external_runtime_route.not_an_mcp_tool: true. The following are source evidence or external runtime routes unless a current Agent Kit MCP tool explicitly exposes them:

• pyspedas.cotrans, pyspedas.cotrans_tools.*, fac_matrix_make, minvar_matrix_make, lmn_matrix_make, tvector_rotate;
• IDL cotrans, spd_cotrans, thm_cotrans, thm_cotrans_lmn, mms_cotrans_lmn, mms_qcotrans, and mission .pro coordinate helpers (load spedas-heritage-vocabulary when translating legacy examples);
• PyTplot state helpers such as cotrans_get_coord, cotrans_set_coord, store_data, get_data, and tplot_names.

Do not present those names as Agent Kit MCP tools. The MCP-first path is: spedas-skills-index -> this skill or a focused downstream skill -> existing planning/data/geometry/analysis tools -> artifact paths + provenance/run.json.

When to use

• "Convert THEMIS/MMS/OMNI position or B from GSE to GSM/SM/GEO/J2000."
• "This IDL crib calls cotrans/thm_cotrans; how do I do the Agent Kit route?"
• "Build FAC for wave polarization or PAD interpretation."
• "Rotate B into MVA/LMN for a boundary crossing, then make a hodogram."
• "Check whether a tplot variable's coordinate metadata makes the requested transform meaningful."

Route table

User intent	Preferred Agent Kit route	External PySPEDAS/IDL evidence
Choose a science frame (RTN, GSE/GSM, HEE/HEEQ/HCI, J2000) and transform vectors/time series with Agent Kit geometry	coordinate-frame-tour; use transform_coordinates for a single vector, or transform_timeseries_coordinates(input_file=..., coord_in=..., coord_out=..., output_file=...) for an artifact time series	PySPEDAS cotrans; IDL cotrans
Preserve / inspect loaded tplot variable names, coordinates, units, and suffixes before any transform	tplot-data-lifecycle and pyspedas-load-planning; record coord_in, coord_out, variable name, units, and support-data choices	cotrans_get_coord, cotrans_set_coord, store_data, get_data
FAC matrix for B-aligned wave/PAD context	apply-rotation-matrix after generating or importing the FAC matrix; then compose with wave-polarization or pitch-angle-distribution	fac_matrix_make, tvector_rotate
Data-driven MVA/LMN for a boundary or current sheet	boundary-minimum-variance for the MVA basis; apply-rotation-matrix for an explicit matrix stack; hodogram for rotation sense	minvar_matrix_make, thm_cotrans_lmn, mms_cotrans_lmn
Model magnetopause LMN normal / Shue cross-check	model-lmn-boundary or magnetopause-lmn-analysis	lmn_matrix_make, gsm2lmn
Field-line/footpoint/L-shell mapping	field-line-footpoint; supply positions in GSM kilometers first	IDL/PySPEDAS coordinate conversion helpers
Mission-specific attitude/quaternion transforms	Stay in the mission skill (mms-basic-workflows, themis-workflows, psp-solo-heliophysics-workflows) and record the support data/quaternion source before any transform	mms_qcotrans, dsl2gse, gse2dsl