Add the SPICE_FRAME information to data files

[greglucas]

Summary

Add SPICE_FRAME to all data files (perhaps individual variables there are multiple frames within the same file?).

End users need to know what frame the data is in when using it. We need to add this as metadata to the global fields if all variables are in a single frame or per variable if it varies depending on the quantity.
The metadata field should be called SPICE_FRAME  for now and should be a string representing the explicit frame name in SPICE, IMAP_DPS for example.

Each instrument should create sub-issues for their individual work.

Requirements

The more specific the better.

• Add a global attribute metadata field called SPICE_FRAME with the explicit frame of what it should be called.

Related tickets

No response

[jtniehof]

I'm working with Andriy on defining this for the per-variable rotations, it might be more involved. Not sure if this is the same thing or just loosely related.

[greglucas]

@subagonsouth also needs this per-variable I believe. Let us know what you hear from SPDF on recommendations.

[jtniehof]

Relevant precedent: SolO uses COORDINATE_SYSTEM, FRAME_ORIGIN, FRAME_VELOCITY, TENSOR_ORDER, REPRESENTATION_i.

Cluster has similar standards.

In the non-ESA space, there's the non-ISTP metadata list with the ISTP metadata standard.

I think what we need are just:
-What is the SPICE kernel defining the frame. This should(?) be handled by a single text string as an attribute on the relevant variable.
-Is it a velocity? We can probably play games with looking at units or the SPASE information in the DICT_KEY but probably better to just have something unambiguous.

We will assume it is always x,y,z in that frame, or a tensor in appropriate order. It will be a simple rotation unless it's a velocity. If it's a velocity, then we assume it's a velocity at the spacecraft position (important for rotating frames). Based on the frame definition can we always figure what it's relative to? Or maybe we explicitly specify the name of the SPICE object the velocity is relative to, and assume it's a velocity if and only if this attribute is present.

Then we establish rules that anything with a SPICE kernel attached gets transformed into the desired set of outputs.

[pleasant-menlo]

We investigated what we would need to automatically rotate data to other reference frames.

We propose including the following metadata attributes on all variables which are represented in a specific frame:

• SPICE_FRAME: specifies frame
• (only if the variable is a velocity) FRAME_VELOCITY: name of the SPICE object that the velocity is measured relative to

If the variable is not a velocity, we will assume it is a directional vector, like magnetic field, and not as a position relative to the spacecraft.

Some questions to consider:

1. What should the file naming convention be for files in a different reference frame?

2. Variables that are based on a reference frame but are not cartesian (x, y, z) are more complicated. For example:

   • Separate longitude and latitude variables
   • SWAPI solar wind velocity represented as speed, deflection angle, and clock angle

   Do we need additional metadata for these to make the data understandable by a machine?

• Peter and Gio

[tmplummer]

I think that there is some conflating of SPICE terms going on. Here are some definitions from NAIF:

• SPICE Body - solar system body, a space vehicle, or any other physical object
• SPICE Frame - A Cartesian coordinate system with 3 axes.
• State (of a Body): A state is an array of six double precision numbers. The first three numbers give the x, y, and z coordinates respectively for the position of some object relative to another object in some Cartesian reference frame. The next three numbers give the velocity ( dx/dt, dy/dt and dz/dt respectively) of the object with respect to the same reference frame.

I think that the summary of this ticket makes sense in that it is just stating what Frame some coordinates or vector are expressed in but some of the follow on discussion is not clear. For example:

-What is the SPICE kernel defining the frame. This should(?) be handled by a single text string as an attribute on the relevant variable.

A complete set of kernels that define the IMAP_SPACECRAFT frame, for example are:

• Frame kernel: imap_wkcp.tf
• Ephemeris: defines the state of the IMAP_BODY in the J2000 reference frame
• Attitude: defines the orientation of the IMAP_SPACECRAFT frame relative to the J2000 reference frame

[jtniehof]

The intent isn't for these attributes to include the full definition of the kernel, just the name (or SPICE ID?) of the frame. External knowledge would be needed to actually do the rotations, which can be inferred from e.g. mission metakernels.

Many of our quantities (e.g. magnetic field) are not state vectors of bodies. We also have a lot of velocities that aren't really state vectors, but velocities measured at the IMAP spacecraft location relative to the Sun, so they can sort of transform as a state vector mixing s/c position and the relevant velocity.