simplify fromarray, sample_rate is not required

Author: Teque5

README.md

@@ -50,9 +50,15 @@ import numpy as np
 import sigmf
 
 data = np.array([0.1 + 0.2j, 0.3 + 0.4j], dtype=np.complex64)
-meta = sigmf.fromarray(data, sample_rate=48000)
+meta = sigmf.fromarray(data)
+# optional additional metadata
+meta.sample_rate = 8000
+meta.description = "sample recording"
+meta.add_capture(start_index=0, metadata={sigmf.FREQUENCY_KEY: 915e6})
 # creates recording.sigmf-data and recording.sigmf-meta
 meta.tofile("recording")
+# or create compressed archive
+meta.tofile("recording.sigmf.gz")
 ```
 
 ### Docs

docs/source/quickstart.rst

@@ -62,7 +62,12 @@ Save a Numpy array as a SigMF Recording
     data = np.zeros(1024, dtype=np.complex64)
 
     # create SigMFFile from array — datatype is inferred from the numpy array
-    meta = sigmf.fromarray(data, sample_rate=48000, frequency=915e6)
+    meta = sigmf.fromarray(data)
+
+    # optional additional metadata
+    meta.sample_rate = 48000
+    meta.description = "an example recording"
+    meta.add_capture(start_index=0, metadata={sigmf.FREQUENCY_KEY: 915e6})
 
     # write to separate .sigmf-meta and .sigmf-data files
     meta.tofile("example")

sigmf/sigmffile.py

@@ -1322,12 +1322,12 @@ def get_dataset_filename_from_metadata(meta_fn, metadata=None):
     return None
 
 
-def fromarray(data, sample_rate, frequency=None, global_info=None):
+def fromarray(data):
     """
     Create a SigMFFile from a numpy array.
 
-    Convenience function that infers the SigMF datatype from the numpy dtype,
-    creates an in-memory SigMFFile with a single capture at index 0. The
+    Convenience function that infers the SigMF datatype from the numpy dtype
+    and creates an in-memory SigMFFile with a single capture at index 0. The
     returned object can then be written to disk using ``tofile()`` or
     ``archive()``. For full control over captures, annotations, and global
     fields, use ``SigMFFile`` directly.
@@ -1336,12 +1336,6 @@ def fromarray(data, sample_rate, frequency=None, global_info=None):
     ----------
     data : np.ndarray
         Signal samples.
-    sample_rate : float
-        Sample rate in Hz.
-    frequency : float, optional
-        Center frequency in Hz for the capture.
-    global_info : dict, optional
-        Additional global metadata fields to include.
 
     Returns
     -------
@@ -1351,37 +1345,26 @@ def fromarray(data, sample_rate, frequency=None, global_info=None):
     Examples
     --------
     >>> import numpy as np
-    >>> import tempfile
+    >>> import sigmf, tempfile
     >>> from pathlib import Path
-    >>> data = np.random.randn(1000) + 1j * np.random.randn(1000)
-    >>> meta = fromarray(data, sample_rate=1e6, frequency=915e6) # returns SigMFFile
+    >>> data = (np.random.randn(16) + 1j * np.random.randn(16))
+    >>> meta = sigmf.fromarray(data)
+    >>> meta.sample_rate = 1e6                                            # set global fields via attribute
+    >>> meta.add_capture(0, metadata={sigmf.FREQUENCY_KEY: 915e6})       # add capture metadata
+    >>> meta.add_annotation(0, length=len(data), metadata={sigmf.LABEL_KEY: 'example'})  # add annotation
     >>> tmpdir = Path(tempfile.mkdtemp())
     >>> meta.tofile(tmpdir / 'recording')        # creates recording.sigmf-meta and recording.sigmf-data
     >>> meta.tofile(tmpdir / 'recording.sigmf')  # creates recording.sigmf archive
     """
-    import io
-
     # create in-memory data buffer
     data_buffer = io.BytesIO()
     data_buffer.write(data.tobytes())
     data_buffer.seek(0)
 
-    # build metadata
-    info = {
-        keys.DATATYPE_KEY: get_data_type_str(data),
-        keys.SAMPLE_RATE_KEY: sample_rate,
-    }
-    if global_info is not None:
-        info.update(global_info)
-
-    capture_meta = None
-    if frequency is not None:
-        capture_meta = {keys.FREQUENCY_KEY: frequency}
-
     # create sigmffile object with in-memory buffer
-    meta = SigMFFile(global_info=info)
+    meta = SigMFFile(global_info={keys.DATATYPE_KEY: get_data_type_str(data)})
     meta.set_data_file(data_buffer=data_buffer)
-    meta.add_capture(0, metadata=capture_meta)
+    meta.add_capture(0)
 
     return meta
 

tests/test_sigmffile.py

@@ -20,7 +20,20 @@
 from sigmf import SigMFFile, error, utils
 from sigmf.sigmffile import _DeprecatingKey, _SigMFDeprecatingMeta
 
-from .testdata import *
+from .testdata import (
+    TEST_FLOAT32_DATA,
+    TEST_METADATA,
+    TEST_U8_DATA0,
+    TEST_U8_DATA1,
+    TEST_U8_DATA2,
+    TEST_U8_DATA3,
+    TEST_U8_DATA4,
+    TEST_U8_META0,
+    TEST_U8_META1,
+    TEST_U8_META2,
+    TEST_U8_META3,
+    TEST_U8_META4,
+)
 
 
 class TestClassMethods(unittest.TestCase):
@@ -140,8 +153,10 @@ def test_set_data_file_with_annotations(self):
 
 class TestMultichannel(unittest.TestCase):
     def setUp(self):
-        # in order to check shapes we need some positive number of samples to work with
-        # number of samples should be lowest common factor of num_channels
+        """
+        In order to check shapes we need some positive number of samples to work with.
+        Number of samples should be lowest common factor of num_channels.
+        """
         self.raw_count = 16
         self.lut = {
             "i8": np.int8,
@@ -534,19 +549,13 @@ def tearDown(self):
 
     def test_basic_creation(self):
         """test creating SigMFFile from array"""
-        meta = sigmf.fromarray(TEST_FLOAT32_DATA, sample_rate=4000)
-        self.assertEqual(meta.get_global_field(sigmf.SAMPLE_RATE_KEY), 4000)
+        meta = sigmf.fromarray(TEST_FLOAT32_DATA)
         self.assertEqual(meta.get_global_field(sigmf.DATATYPE_KEY), "rf32_le")
         np.testing.assert_array_equal(TEST_FLOAT32_DATA, meta[:])
 
-    def test_with_frequency(self):
-        """test that frequency kwarg populates capture metadata"""
-        meta = sigmf.fromarray(TEST_FLOAT32_DATA, sample_rate=4000, frequency=915e6)
-        self.assertEqual(meta.get_capture_info(0).get("core:frequency"), 915e6)
-
     def test_write_separate_files(self):
         """test writing to separate meta and data files"""
-        meta = sigmf.fromarray(TEST_FLOAT32_DATA, sample_rate=4000)
+        meta = sigmf.fromarray(TEST_FLOAT32_DATA)
         path = self.temp_dir / "basic"
         meta.tofile(str(path))
         self.assertTrue((self.temp_dir / "basic.sigmf-data").exists())
@@ -556,7 +565,7 @@ def test_write_separate_files(self):
 
     def test_write_archive(self):
         """test writing to uncompressed archive"""
-        meta = sigmf.fromarray(TEST_FLOAT32_DATA, sample_rate=4000)
+        meta = sigmf.fromarray(TEST_FLOAT32_DATA)
         path = self.temp_dir / "archived.sigmf"
         meta.tofile(str(path))
         self.assertTrue((self.temp_dir / "archived.sigmf").exists())
@@ -567,19 +576,11 @@ def test_write_archive(self):
 
     def test_write_compressed_archive(self):
         """test writing to compressed archive"""
-        meta = sigmf.fromarray(TEST_FLOAT32_DATA, sample_rate=4000)
+        meta = sigmf.fromarray(TEST_FLOAT32_DATA)
         path = self.temp_dir / "comp.sigmf.xz"
         meta.tofile(str(path))
         self.assertTrue((self.temp_dir / "comp.sigmf.xz").exists())
         self.assertFalse((self.temp_dir / "comp.sigmf-data").exists())
         self.assertFalse((self.temp_dir / "comp.sigmf-meta").exists())
         loopback = sigmf.fromfile(str(path))
         np.testing.assert_array_equal(TEST_FLOAT32_DATA, loopback[:])
-
-    def test_with_global_info(self):
-        """test that global_info dict is merged into metadata"""
-        meta = sigmf.fromarray(
-            TEST_FLOAT32_DATA, sample_rate=4000, global_info={"core:author": "test_author", "core:description": "test"}
-        )
-        self.assertEqual(meta.get_global_field("core:author"), "test_author")
-        self.assertEqual(meta.get_global_field("core:description"), "test")