Defining a Standardised Metadata Attribute API

SEP-0013.md

@@ -0,0 +1,198 @@
+# SEP-num -- SEP Title
+
+| SEP           | num                              |
+|---------------|----------------------------------|
+| title         | A Common API for Metadata Attributes |
+| author(s)     | [First Last](https://orcid.org/0000-0001-8661-3825)<br>Daniel Ryan |
+| contact email | [email protected]                    |
+| date-creation | 2021-09-11                       |
+| type          | standard                         |
+| discussion    | link to discussion if available  |
+| status        | discussion                       |
+
+# Introduction
+Moves are being made to develop a standardized metadata object for SunPy (and ndcube) data objects.
+The benefit of this is that the same type of metadata can be accessed in the same way irrespective
+of what data object is being used and what instrument the metadata has come from. To facilitate
+this, a set of standardized attribute names must be established for storing and accessing commonly
+used metadata in solar physics.  Then a metadata object can implement a translation from the
+original file/object containing the metadata file, e.g. FITS header, and the attributes.
+
+The purpose of this SEP is to agree the names of the different metadata attributes. To start with
+the list does not have to be exhaustive. We envision that it can be appended to over time. But
+once an attribute name is addedit should preferably not be changed so that users can rely on a
+stable, backwards compatible API.
+
+For now, this API does not include WCS metadata and should not be linked to a specific file format,
+e.g. FITS.
+
+
+# SunPy Metadata API
+Below is a class definition of an Metadata Abstract Base Class (ABC) for solar physics.
+
+```python
+
+class MetaABC():
+    ##### Instrument info #####
+
+    @abc.abstractproperty
+    def observatory(self):
+        """
+        Name of the observatory
+        """
+
+    @abc.abstractproperty
+    def instrument(self):
+        """
+        Name of the instrument
+        """
+
+    @abc.abstractproperty
+    def detector(self):
+        """
+        Name of the detector
+        """
+
+    ##### Data Info ####
+
+    @abc.abstractproperty
+    def data_processing_level(self):
+        """
+        The level to which the data has been processed.
+        """
+
+    @abc.abstractproperty
+    def data_version(self):
+        """
+        The data version.
+        """
+
+    ##### Observer Coordinate Info #####
+
+    @abc.abstractproperty
+    def observer_location(self):
+        """
+        Coordinate of observatory location.
+        """
+
+    def observer_radial_velocity(self):
+        """
+        Velocity of observer in direction of source.
+        """
+
+    @abc.abstractproperty
+    def celestial_frame(self):
+        """
+        The celestial coordinate frame of the image axes.
+        """
+
+    @abc.abstractproperty
+    def distance_to_sun(self):
+        """
+        Distance to Sun center from observatory.
+        """
+
+    @abc.abstractproperty
+    def light_travel_time(self):
+        """
+        Light travel time from emission source to observer.
+        """
+
+    @abc.abstractproperty
+    def light_travel_time_to_earth(self):
+        """
+        Light travel time from observer to Earth.
+        """
+
+    ##### Time Info #####
+
+    @abc.abstractproperty
+    def date_reference(self):
+        """
+        The base time from which time axis values are measured.
+        """
+
+    @abc.abstractproperty
+    def date_start(self):
+        """
+        Time at which the observation(s) were started.
+        """
+
+    @abc.abstractproperty
+    def date_average(self):
+        """
+        The mean/representative time of the observation(s).
+        """
+
+    @abc.abstractproperty
+    def date_end(self):
+        """
+        The time at which the observation(s) were ended.
+        """
+
+    @abc.abstractproperty
+    def exposure_time(self):
+        """
+        The exposure time(s) of the observation(s).
+        """
+
+    ##### Misc. #####
+
+    @abc.abstractproperty
+    def rsun_meters(self):
+        """
+        Solar radius in units of length.
+        """
+
+    @abc.abstractproperty
+    def rsun_angular(self):
+        """
+        Solar radius in angular units as seen from observatory.
+        """
+
+    ##### Spectral Info #####
+
+    @abc.abstractproperty
+    def spectral_window(self):
+        """
+        The name of the spectral window in which data has been taken.
+        """
+
+    ##### Imaging Info #####
+
+    @abc.abstractproperty
+    def filter(self):
+        """
+        The name of the filter(s) used to make the observation.
+        """
+
+    @abc.abstractproperty
+    def automatic_exposure_control_on(self):
+        """
+        Whether automatic exposure control was on during observations.
+        """
+
+    ##### Operational Info #####
+
+    @abc.abstractproperty
+    def observing_mode(self):
+        """
+        The observing mode used to make the observations.
+        """
+
+    @abc.abstractproperty
+    def observing_mode_id(self):
+        """
+        Identification number of the observing mode.
+        """
+
+    @abc.abstractproperty
+    def SAA(self):
+        """
+        Whether observer passed through the South Atlantic Anomaly during the observations.
+        """
+
+```
+
+# Decision Rationale
+This is a great idea because...