Merge branch 'staging'

Author: smithara

docs/release_notes.rst

@@ -4,6 +4,12 @@ Release notes
 Change log
 ----------
 
+Changes from 0.9.0 to 0.9.1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Added :py:meth:`viresclient.SwarmRequest.get_conjunctions` to fetch Swarm A/B conjunctions
+- Fixed compatibility with xarray v0.19 of ``reshape`` kwarg in :py:meth:`viresclient.ReturnedData.as_xarray`
+
 Changes from 0.8.0 to 0.9.0
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

viresclient/__init__.py

@@ -37,4 +37,4 @@
 from . import _data
 
 
-__version__ = "0.9.0"
+__version__ = "0.9.1"

viresclient/_client.py

@@ -247,13 +247,13 @@ class ClientRequest(object):
     """Base class handling the requests to and downloads from the server.
     """
 
-    def __init__(self, url=None, username=None, password=None, token=None,
+    def __init__(self, url=None, token=None,
                  config=None, logging_level="NO_LOGGING", server_type=None):
 
         # Check and prompt for token if not already set, then store in config
         # Try to only do this if running in a notebook
         if IN_JUPYTER:
-            if not ((username and password) or token or config):
+            if not (token or config):
                 cc = ClientConfig()
                 # Use production url if none chosen
                 url = url or cc.default_url or "https://vires.services/ows"
@@ -275,7 +275,7 @@ def __init__(self, url=None, username=None, password=None, token=None,
         set_stream_handler(self._logger, logging_level)
 
         self._wps_service = self._create_service_proxy_(
-            config, url, username, password, token
+            config, url, None, None, token
         )
         # Test if the token is working; re-enter if not
         if IN_JUPYTER:
@@ -292,7 +292,7 @@ def __init__(self, url=None, username=None, password=None, token=None,
                         raise AuthenticationError(AUTH_ERROR_TEXT)
                     set_token(url)
                     self._wps_service = self._create_service_proxy_(
-                        config, url, username, password, token
+                        config, url, None, None, token
                     )
 
     def _create_service_proxy_(self, config, url, username, password, token):

viresclient/_client_swarm.py

@@ -23,7 +23,8 @@
     'async': "vires_fetch_filtered_data_async.xml",
     'model_info': "vires_get_model_info.xml",
     'times_from_orbits': "vires_times_from_orbits.xml",
-    'get_observatories': 'vires_get_observatories.xml'
+    'get_observatories': 'vires_get_observatories.xml',
+    'get_conjunctions': 'vires_get_conjunctions.xml',
 }
 
 REFERENCES = {
@@ -401,8 +402,6 @@ class SwarmRequest(ClientRequest):
 
     Args:
         url (str):
-        username (str):
-        password (str):
         token (str):
         config (str or ClientConfig):
         logging_level (str):
@@ -415,6 +414,10 @@ class SwarmRequest(ClientRequest):
         'CryoSat-2': None,
     }
 
+    CONJUNCTION_MISISON_SPACECRAFT_PAIRS = {
+        (('Swarm', 'A'), ('Swarm', 'B')),
+    }
+
     COLLECTIONS = {
         "MAG": ["SW_OPER_MAG{}_LR_1B".format(x) for x in "ABC"],
         "MAG_HR": ["SW_OPER_MAG{}_HR_1B".format(x) for x in "ABC"],
@@ -728,7 +731,7 @@ class SwarmRequest(ClientRequest):
             "B_FGM1", "B_FGM2", "B_FGM3", "q_NEC_CRF", "q_error",
         ],
         "MAG_GRACE": [
-            "F", "B_NEC", "B_NEC_raw", "B_FGM", "B_mod_NEC",
+            "F", "B_NEC", "B_NEC_raw", "B_FGM",
             "q_NEC_CRF", "q_error",
         ],
         "MAG_GFO": [
@@ -770,10 +773,10 @@ class SwarmRequest(ClientRequest):
         "MCO_SHA_2X", "CHAOS", "CHAOS-MMA", "MMA_SHA_2C", "MMA_SHA_2F", "MIO_SHA_2C", "MIO_SHA_2D", "SwarmCI",
     ]
 
-    def __init__(self, url=None, username=None, password=None, token=None,
+    def __init__(self, url=None, token=None,
                  config=None, logging_level="NO_LOGGING"):
         super().__init__(
-            url, username, password, token, config, logging_level,
+            url, token, config, logging_level,
             server_type="Swarm"
             )
 
@@ -1309,16 +1312,38 @@ def get_times_for_orbits(self, start_orbit, end_orbit, mission="Swarm", spacecra
         start_orbit = int(start_orbit)
         end_orbit = int(end_orbit)
 
-        if mission not in self.MISSION_SPACECRAFTS:
-            raise ValueError(
-                f"Invalid mission {mission}!"
-                f"Allowed options are: {','.join(self.MISSION_SPACECRAFTS)}"
-            )
+        # Change to spacecraft = "A" etc. for this request
+        spacecraft = self._fix_spacecraft(mission, spacecraft)
+        self._check_mission_spacecraft(mission, spacecraft)
+
+        templatefile = TEMPLATE_FILES["times_from_orbits"]
+        template = JINJA2_ENVIRONMENT.get_template(templatefile)
+        request = template.render(
+            mission=mission,
+            spacecraft=spacecraft,
+            start_orbit=start_orbit,
+            end_orbit=end_orbit
+        ).encode('UTF-8')
+        response = self._get(
+            request, asynchronous=False, show_progress=False)
+        responsedict = json.loads(response.decode('UTF-8'))
+        start_time = parse_datetime(responsedict['start_time'])
+        end_time = parse_datetime(responsedict['end_time'])
+        return start_time, end_time
 
+    def _fix_spacecraft(self, mission, spacecraft):
         # Change to spacecraft = "A" etc. for this request
         spacecraft = str(spacecraft) if spacecraft is not None else None
         if mission == "Swarm" and spacecraft in ("Alpha", "Bravo", "Charlie"):
             spacecraft = spacecraft[0]
+        return spacecraft
+
+    def _check_mission_spacecraft(self, mission, spacecraft):
+        if mission not in self.MISSION_SPACECRAFTS:
+            raise ValueError(
+                f"Invalid mission {mission}!"
+                f"Allowed options are: {','.join(self.MISSION_SPACECRAFTS)}"
+            )
 
         if self.MISSION_SPACECRAFTS[mission]:
             # missions with required spacecraft id
@@ -1339,20 +1364,6 @@ def get_times_for_orbits(self, start_orbit, end_orbit, mission="Swarm", spacecra
                 "Set spacecraft to None."
             )
 
-        templatefile = TEMPLATE_FILES["times_from_orbits"]
-        template = JINJA2_ENVIRONMENT.get_template(templatefile)
-        request = template.render(
-            mission=mission,
-            spacecraft=spacecraft,
-            start_orbit=start_orbit,
-            end_orbit=end_orbit
-        ).encode('UTF-8')
-        response = self._get(
-            request, asynchronous=False, show_progress=False)
-        responsedict = json.loads(response.decode('UTF-8'))
-        start_time = parse_datetime(responsedict['start_time'])
-        end_time = parse_datetime(responsedict['end_time'])
-        return start_time, end_time
 
     def get_orbit_number(self, spacecraft, input_time, mission="Swarm"):
         """Translate a time to an orbit number.
@@ -1506,3 +1517,89 @@ def _check_deprecated_models(models):
             print("WARNING: Model {} is deprecated. {}".format(
                 deprecated_model, DEPRECATED_MODELS[deprecated_model]
             ), file=sys.stdout)
+
+
+    def get_conjunctions(self, start_time=None, end_time=None, threshold=1.0,
+                         spacecraft1='A', spacecraft2='B',
+                         mission1='Swarm', mission2='Swarm'):
+        """ Get times of the spacecraft conjunctions. Currently available for
+        the following spacecraft pairs:
+          - Swarm-A/Swarm-B
+
+        Args:
+            start_time (datetime / ISO_8601 string): optional start time
+            end_time (datetime / ISO_8601 string): optional end time
+            threshold (float): optional maximum allowed angular separation
+                 in degrees; by default set to 1; allowed values are [0, 180]
+            spacecraft1: identifier of the first spacecraft, default to 'A'
+            spacecraft2: identifier of the second spacecraft, default to 'B'
+            mission1 (str): mission of the first spacecraft, defaults to 'Swarm'
+            mission2 (str): mission of the first spacecraft, defaults to 'Swarm'
+
+        Returns:
+            ReturnedData:
+        """
+        try:
+            start_time = parse_datetime(start_time) if start_time else None
+            end_time = parse_datetime(end_time) if end_time else None
+        except TypeError:
+            raise TypeError(
+                "start_time and end_time must be datetime objects or ISO-8601 "
+                "date/time strings"
+            ) from None
+
+        if not (0 <= threshold <= 180):
+            raise ValueError("Invalid threshold value!")
+
+        spacecraft1 = self._fix_spacecraft(mission1, spacecraft1)
+        spacecraft2 = self._fix_spacecraft(mission2, spacecraft2)
+
+        self._check_mission_spacecraft(mission1, spacecraft1)
+        self._check_mission_spacecraft(mission2, spacecraft2)
+
+        if (mission1, spacecraft1) == (mission2, spacecraft2):
+            raise ValueError(
+                "The first and second spacecraft must not be the same!"
+            )
+
+        spacecraft_pair = tuple(sorted([
+            (mission1, spacecraft1), (mission2, spacecraft2)
+        ]))
+
+        if spacecraft_pair not in self.CONJUNCTION_MISISON_SPACECRAFT_PAIRS:
+            raise ValueError(
+                "Conjunctions not available for the requested "
+                "spacecraft pair {spacecraft_pair}!"
+            )
+
+        templatefile = TEMPLATE_FILES["get_conjunctions"]
+        template = JINJA2_ENVIRONMENT.get_template(templatefile)
+        request = template.render(
+            begin_time=start_time,
+            end_time=end_time,
+            spacecraft1=spacecraft1,
+            spacecraft2=spacecraft2,
+            mission1=mission1,
+            mission2=mission2,
+            threshold=threshold,
+        ).encode('UTF-8')
+
+        show_progress = False
+        leave_progress_bar = False
+        response = ReturnedDataFile(filetype="cdf")
+
+        response_handler = self._response_handler(
+            retdatafile=response,
+            show_progress=show_progress,
+            leave_progress_bar=leave_progress_bar,
+        )
+
+        self._get(
+            request=request,
+            asynchronous=False,
+            show_progress=show_progress,
+            leave_progress_bar=leave_progress_bar,
+            response_handler=response_handler,
+        )
+
+        return response

viresclient/_data_handling.py

@@ -216,11 +216,10 @@ def as_xarray_dataset(self, reshape=False):
             coords={"Timestamp":
                     self._cdftime_to_datetime(self.get_variable("Timestamp"))})
         # Add Spacecraft variable as Categorical to save memory
-        ds["Spacecraft"] = (("Timestamp",), pandas.Categorical(
-            self.get_variable("Spacecraft"), categories=ALLOWED_SPACECRFTS))
-        datanames = set(self.variables)
-        datanames.remove("Timestamp")
-        datanames.remove("Spacecraft")
+        if "Spacecraft" in self.variables:
+            ds["Spacecraft"] = (("Timestamp",), pandas.Categorical(
+                self.get_variable("Spacecraft"), categories=ALLOWED_SPACECRFTS))
+        datanames = set(self.variables) - {"Timestamp", "Spacecraft"}
         # Loop through each variable available and append them to the Dataset,
         #  attaching the Timestamp coordinate to each.
         # Attach dimension names based on the name of the variable,
@@ -297,40 +296,45 @@ def reshape_dataset(ds):
         # Create integer "Site" identifier based on SiteCode / IAGA_code
         sites = dict(enumerate(sorted(set(ds[codevar].values))))
         sites_inv = {v: k for k, v in sites.items()}
-        # Identify (V)OBS locations and mapping from integer "Site" identifier
-        pos_vars = ["Longitude", "Latitude", "Radius", codevar]
-        _ds_locs = next(iter(ds[pos_vars].groupby("Timestamp")))[1]
-        if len(sites) > 1:
-            _ds_locs = _ds_locs.drop(("Timestamp")).rename({"Timestamp": "Site"})
+        if len(sites) == 0:
+            _ds_locs = ds
         else:
-            _ds_locs = _ds_locs.drop(("Timestamp")).expand_dims("Site")
-        _ds_locs["Site"] = [sites_inv.get(code) for code in _ds_locs[codevar].values]
-        _ds_locs = _ds_locs.sortby("Site")
+            # Identify (V)OBS locations and mapping from integer "Site" identifier
+            pos_vars = ["Longitude", "Latitude", "Radius", codevar]
+            _ds_locs = next(iter(ds[pos_vars].groupby("Timestamp")))[1]
+            if len(sites) > 1:
+                _ds_locs = _ds_locs.drop(("Timestamp")).rename({"Timestamp": "Site"})
+            else:
+                _ds_locs = _ds_locs.drop(("Timestamp")).expand_dims("Site")
+            _ds_locs["Site"] = [sites_inv.get(code) for code in _ds_locs[codevar].values]
+            _ds_locs = _ds_locs.sortby("Site")
         # Create dataset initialised with the (V)OBS positional info as coords
         # and datavars (empty) reshaped to (Site, Timestamp, ...)
         t = numpy.unique(ds["Timestamp"])
         ds2 = xarray.Dataset(
             coords={
                 "Timestamp": t,
-                codevar: (("Site"), _ds_locs[codevar]),
-                "Latitude": ("Site", _ds_locs["Latitude"]),
-                "Longitude": ("Site", _ds_locs["Longitude"]),
-                "Radius": ("Site", _ds_locs["Radius"]),
+                codevar: (("Site"), _ds_locs[codevar].data),
+                "Latitude": ("Site", _ds_locs["Latitude"].data),
+                "Longitude": ("Site", _ds_locs["Longitude"].data),
+                "Radius": ("Site", _ds_locs["Radius"].data),
                 "NEC": ["N", "E", "C"]
             },
         )
         # (Dropping unused Spacecraft var)
         data_vars = set(ds.data_vars) - {"Latitude", "Longitude", "Radius", codevar, "Spacecraft"}
         N_sites = len(_ds_locs[codevar])
+        # Create empty data variables to be infilled
         for var in data_vars:
             shape = [N_sites, len(t), *ds[var].shape[1:]]
             ds2[var] = ("Site", *ds[var].dims), numpy.empty(shape, dtype=ds[var].dtype)
             ds2[var][...] = None
-        # Loop through each (V)OBS site to insert the datavars into ds2
-        for k, _ds in dict(ds.groupby(codevar)).items():
-            site = sites_inv.get(k)
-            for var in data_vars:
-                ds2[var][site, ...] = _ds[var].values
+        # Loop through each (V)OBS site to infill the data
+        if N_sites != 0:
+            for k, _ds in dict(ds.groupby(codevar)).items():
+                site = sites_inv.get(k)
+                for var in data_vars:
+                    ds2[var][site, ...] = _ds[var].values
         # Revert to using only the "SiteCode"/"IAGA_code" identifier
         ds2 = ds2.set_index({"Site": codevar})
         ds2 = ds2.rename({"Site": codevar})
@@ -521,6 +525,7 @@ def as_xarray(self, group=None, reshape=False):
                 ds = f.as_xarray_dataset(reshape=reshape)
         elif self.filetype == 'nc':
             ds = xarray.open_dataset(self._file.name, group=group)
+        ds.attrs["Sources"] = self.sources
         return ds
 
     @property