added documentation and tests requested by review of #76

Author: betaBison

gnss_lib_py/parsers/navdata.py

@@ -15,7 +15,25 @@
 
 class NavData():
     """gnss_lib_py specific class for handling data.
-    Uses numpy for speed combined with pandas like intuitive indexing
+
+    Uses numpy for speed combined with pandas like intuitive indexing.
+
+    Can either be initialized empty, with a csv file by setting
+    ``csv_path``, a Pandas DataFrame by setting ``pandas_df`` or by a
+    Numpy array by setting ``numpy_array``.
+
+    Parameters
+    ----------
+    csv_path : string
+        Path to csv file containing data
+    pandas_df : pd.DataFrame
+        Data used to initialize NavData instance.
+    numpy_array : np.ndarray
+        Numpy array containing data used to initialize NavData
+        instance.
+    **kwargs : args
+        Additional arguments (e.g. ``sep`` or ``header``) passed into
+        ``pd.read_csv`` if csv_path is not None.
 
     Attributes
     ----------
@@ -89,7 +107,8 @@ def from_pandas_df(self, pandas_df):
 
         Parameters
         ----------
-        pandas_df : pd.DataFrame of data
+        pandas_df : pd.DataFrame
+            Data used to initialize NavData instance.
         """
 
         if not isinstance(pandas_df, pd.DataFrame):
@@ -112,7 +131,8 @@ def from_numpy_array(self, numpy_array):
         Parameters
         ----------
         numpy_array : np.ndarray
-            Numpy array containing data
+            Numpy array containing data used to initialize NavData
+            instance.
 
         """
 
@@ -128,7 +148,10 @@ def from_numpy_array(self, numpy_array):
             self[str(row_num)] = numpy_array[row_num,:]
 
     def concat(self, navdata=None, axis=1, inplace=False):
-        """Concatenates new rows or new columns to existing NavData.
+        """Concatenates second NavData instance by row or column.
+
+        Concatenates a second NavData instance to the existing NavData
+        instance by either row or column.
 
         Each type of data is included in a row, so adding new rows with
         ``axis=0``, means adding new types of data. Concat requires that
@@ -164,11 +187,11 @@ def concat(self, navdata=None, axis=1, inplace=False):
         """
 
         if not isinstance(navdata,NavData):
-            raise TypeError("new concat data must be a NavData instance.")
+            raise TypeError("concat input data must be a NavData instance.")
 
         if axis == 0: # concatenate new rows
             if len(self) != len(navdata):
-                raise RuntimeError("new concat data must be same " \
+                raise RuntimeError("concat input data must be same " \
                                  + "length to concatenate new rows.")
             if not inplace:
                 new_navdata = self.copy()

tests/parsers/test_android.py

@@ -308,20 +308,25 @@ def test_android_concat(derived, pd_df):
     # extract and combine gps and glonass data
     gps_data = derived.where("gnss_id","gps")
     glonass_data = derived.where("gnss_id","glonass")
-    combined_navdata = gps_data.concat(glonass_data)
+    gps_glonass_navdata = gps_data.concat(glonass_data)
+    glonass_gps_navdata = glonass_data.concat(gps_data)
 
     # combine using pandas
     gps_df = pd_df[pd_df["constellationType"]==1]
     glonass_df = pd_df[pd_df["constellationType"]==3]
-    combined_df = pd.concat((gps_df,glonass_df))
-
-    # check a few rows to make sure they're equal
-    np.testing.assert_array_equal(combined_navdata["raw_pr_m"],
-                                  combined_df["rawPrM"])
-    np.testing.assert_array_equal(combined_navdata["raw_pr_sigma_m"],
-                                  combined_df["rawPrUncM"])
-    np.testing.assert_array_equal(combined_navdata["intersignal_bias_m"],
-                                  combined_df["isrbM"])
+    gps_glonass_df = pd.concat((gps_df,glonass_df))
+    glonass_gps_df = pd.concat((glonass_df,gps_df))
+
+    for combined_navdata, combined_df in [(gps_glonass_navdata, gps_glonass_df),
+                                          (glonass_gps_navdata, glonass_gps_df)]:
+
+        # check a few rows to make sure they're equal
+        np.testing.assert_array_equal(combined_navdata["raw_pr_m"],
+                                      combined_df["rawPrM"])
+        np.testing.assert_array_equal(combined_navdata["raw_pr_sigma_m"],
+                                      combined_df["rawPrUncM"])
+        np.testing.assert_array_equal(combined_navdata["intersignal_bias_m"],
+                                      combined_df["isrbM"])
 
 def test_imu_raw(android_raw_path):
     """Test that AndroidRawImu initialization

tests/parsers/test_navdata.py

@@ -1345,6 +1345,18 @@ def test_concat(df_simple):
                                   check_index_type=False,
                                   check_dtype=False)
 
+    # concatenate empty NavData
+    navdata = NavData().concat(navdata_1,axis=1)
+    pd.testing.assert_frame_equal(df_simple.sort_index(axis=1),
+                                  navdata.pandas_df().sort_index(axis=1),
+                                  check_index_type=False,
+                                  check_dtype=False)
+    navdata = navdata_1.concat(NavData(),axis=1)
+    pd.testing.assert_frame_equal(df_simple.sort_index(axis=1),
+                                  navdata.pandas_df().sort_index(axis=1),
+                                  check_index_type=False,
+                                  check_dtype=False)
+
     # test multiple rows with the same name
     navdata_long = navdata_1.copy()
     for count in range(13):
@@ -1407,6 +1419,16 @@ def test_concat_fails(df_simple):
     assert "same length" in str(excinfo.value)
     assert "concat" in str(excinfo.value)
 
+    with pytest.raises(RuntimeError) as excinfo:
+        navdata_1.concat(NavData(),axis=0)
+    assert "same length" in str(excinfo.value)
+    assert "concat" in str(excinfo.value)
+
+    with pytest.raises(RuntimeError) as excinfo:
+        NavData().concat(navdata_1,axis=0)
+    assert "same length" in str(excinfo.value)
+    assert "concat" in str(excinfo.value)
+
 @pytest.mark.parametrize("rows",
                         [None,
                         ['names', 'integers', 'floats', 'strings'],