[Documentation] Basic SSCWeb module documentation

Also renamed get_orbit to get_trajectory which seems better

Signed-off-by: Alexis Jeandet <alexis.jeandet@member.fsf.org>

docs/user/sscweb/sscweb.rst

@@ -3,3 +3,39 @@ SSCWEB
 
 .. toctree::
    :maxdepth: 1
+
+
+`SSCWeb <https://sscweb.gsfc.nasa.gov/>`_ provides trajectories for our solar system space objects such as planets, moons and spacecrafts
+in different coordinate systems. It's integration into speasy makes easy to get any available object trajectory on any time range.
+
+Basics: Getting data from SSCWeb module
+---------------------------------------
+
+First you need to ensure that the trajectory you want to get is available with this module. The easiest solution is use
+speasy dynamic inventory so you will always get an up to date inventory:
+
+    >>> import speasy as spz
+    >>> # Let's only print the first 10 trajectories
+    >>> print(list(spz.inventory.flat_inventories.ssc.parameters.keys())[:10])
+    ['ace', 'active', 'aec', 'aed', 'aee', 'aerocube6a', 'aerocube6b', 'aim', 'akebono', 'alouette1']
+
+Note that you can also use your python terminal completion and browse `spz.inventory.data_tree.ssc.Trajectories` to find
+your trajectory.
+Once you have found your trajectory, you may also want to chose in which coordinates system your data will be downloaded.
+The following coordinates systems are available: **geo**, **gm**, **gse**, **gsm**, **sm**, **geitod**, **geij2000**. By default gse is used.
+Now you can get your trajectory:
+
+    >>> import speasy as spz
+    >>> # Let's assume you wanted to get MMS1 trajectory
+    >>> mms1_traj = spz.ssc.get_trajectory(spz.inventory.data_tree.ssc.Trajectories.mms1, "2018-01-01", "2018-02-01", 'gsm')
+    >>> mms1_traj.columns
+    ['X', 'Y', 'Z']
+    >>> mms1_traj.data
+    <Quantity [[57765.77891127, 39928.64689416, 36127.69757491],
+               [57636.78726753, 39912.67690181, 36075.18117495],
+               [57507.67093183, 39896.65117739, 36022.43945697],
+               ...,
+               [74135.04374424,   741.72325874, 27240.73393024],
+               [74007.246673  ,   795.05699457, 27220.37053627],
+               [73879.18392451,   848.35181084, 27199.87604795]] km>
+

speasy/__init__.py

@@ -24,7 +24,7 @@
 __PROVIDERS__ = {
     'amda': amda.get_data,
     'cdaweb': cda.get_data,
-    'sscweb': ssc.get_orbit
+    'sscweb': ssc.get_trajectory
 }
 
 
@@ -84,7 +84,7 @@ def get_data(product: str or SpeasyIndex, start_time=None, stop_time=None, **kwa
 
 
 def get_orbit(body: str, start_time, stop_time, coordinate_system: str = 'gse', **kwargs) -> SpeasyVariable:
-    return ssc.get_orbit(body, start_time, stop_time, coordinate_system=coordinate_system, **kwargs)
+    return ssc.get_trajectory(body, start_time, stop_time, coordinate_system=coordinate_system, **kwargs)
 
 
 def list_providers() -> List[str]:

speasy/webservices/amda/ws.py

@@ -409,7 +409,7 @@ def parameter_range(self, parameter_id: str or AMDAParameterIndex or AMDADataset
 
         >>> import speasy as spz
         >>> spz.amda.parameter_range("imf")
-        <DateTimeRange: 1997-09-02T00:00:12+00:00 -> 2022-01-08T23:59:56+00:00>
+        <DateTimeRange: 1997-09-02T00:00:12+00:00 -> ...>
 
         """
         if not len(flat_inventories.amda.parameters):

speasy/webservices/ssc/__init__.py

@@ -78,8 +78,8 @@ def version(self, product):
         return 2
 
     # Wrapper to ensure that whatever the source (Proxy, Cache, SSCWeb) the returned variable is in km
-    def get_orbit(self, product: str, start_time: datetime, stop_time: datetime, coordinate_system: str = 'gse',
-                  debug=False, **kwargs) -> Optional[SpeasyVariable]:
+    def get_trajectory(self, product: str, start_time: datetime, stop_time: datetime, coordinate_system: str = 'gse',
+                       debug=False, **kwargs) -> Optional[SpeasyVariable]:
         var = self._get_orbit(product=product, start_time=start_time, stop_time=stop_time,
                               coordinate_system=coordinate_system, debug=debug, **kwargs)
         if var:

tests/test_sscweb.py

@@ -57,10 +57,10 @@ def tearDown(self):
         }
     )
     def test_get_orbit(self, kw):
-        result = self.ssc.get_orbit(**kw,
-                                    debug=True,
-                                    disable_cache=True,
-                                    disable_proxy=True)
+        result = self.ssc.get_trajectory(**kw,
+                                         debug=True,
+                                         disable_cache=True,
+                                         disable_proxy=True)
         self.assertIsNotNone(result)
         self.assertGreater(len(result), 0)
         self.assertGreater(60., kw["start_time"].timestamp() - result.time[0])
@@ -69,8 +69,8 @@ def test_get_orbit(self, kw):
     def test_get_data_from_cache_preserve_unit(self):
         # https://github.com/SciQLop/speasy/issues/7
         for _ in range(3):
-            result = self.ssc.get_orbit('moon', datetime(2006, 1, 8, 1, 0, 0, tzinfo=timezone.utc),
-                                        datetime(2006, 1, 8, 2, 0, 0, tzinfo=timezone.utc))
+            result = self.ssc.get_trajectory('moon', datetime(2006, 1, 8, 1, 0, 0, tzinfo=timezone.utc),
+                                             datetime(2006, 1, 8, 2, 0, 0, tzinfo=timezone.utc))
             self.assertIs(type(result.values), units.quantity.Quantity)
 
     def test_get_observatories(self):
@@ -82,4 +82,4 @@ def test_get_observatories(self):
           {'unknown_arg': 10})
     def test_raises_if_user_passes_unexpected_kwargs_to_get_orbit(self, kwargs):
         with self.assertRaises(TypeError):
-            self.ssc.get_orbit('moon', "2018-01-01", "2018-01-02", **kwargs)
+            self.ssc.get_trajectory('moon', "2018-01-01", "2018-01-02", **kwargs)