Merge pull request #54 from SilverLabUCL/usage-docs-for-metadata

update usage docs to cover creating from metadata

Author: alessandrofelder

docs/usage.rst

@@ -3,7 +3,7 @@ Usage
 =====
 
 
-Two main programs are provided: ``labview2nwb`` and ``nwb_metadata_editor``.
+Three main programs are provided: ``labview2nwb``, ``metadata2nwb`` and ``nwb_metadata_editor``.
 
 ``labview2nwb`` imports Labview data to the NWB format.
 You need to provide it the path to the NWB file to create,
@@ -19,6 +19,17 @@ By default the import process will start by running a simple graphical editor,
 allowing you to input metadata required or recommended by the NWB format,
 but that is not available within the Labview data folder.
 
+``metadata2nwb`` creates a minimal NWB file by loading metadata describing
+an experiment from a YAML file. You need to provide it the path to the NWB file
+to create, the path to the metadata YAML file and optionally a user.
+The user must be mentioned in the metadata file. If there is only one user in the file,
+you don't need to specify them when running this. An example for a metadata YAML file
+can be found on the `PySilverLabNWB Github directory`__. Metadata YAML files are intended
+to be created, read and modified by users to quickly set up a new NWB file without
+having to go via the metadata editor.
+
+__ https://github.com/SilverLabUCL/PySilverLabNWB/blob/master/tests/data/meta_two_users.yaml
+
 ``nwb_metadata_editor`` runs the metadata editor in standalone mode.
 It is useful for setting up details of new researchers or new experiments,
 that can then be used quickly when importing experiment data.
@@ -28,16 +39,23 @@ Python library usage
 ====================
 
 The main class is ``silverlabnwb.NwbFile`` defined in ``nwb_file.py``.
-All its methods are documented with docstrings.
+All its methods are documented with docstrings. There are two entry points,
+``import_labview_folder`` and ``create_from_metadata``, which mirror the first
+two command line tools described above.
 
 Quick examples::
 
     from silverlabnwb import NwbFile
 
-    # Write a new file
+    # Write a new file from a LabView folder
     with NwbFile(nwb_path, mode='w') as nwb:
         nwb.import_labview_folder(labview_path)
 
+    # Write a new file from metadata
+    with NwbFile(nwb_path, mode='w') as nwb:
+        nwb.create_from_metadata(metadata_path, user)
+
     # Read an existing file
     with NwbFile(nwb_path) as nwb:
         print('Opened NWB with ID {}'.format(nwb['/identifier']))
+

src/silverlabnwb/nwb_file.py

@@ -102,7 +102,7 @@ def import_labview_folder(self, folder_path, compress=True):
         self.import_labview_data(folder_path, folder_name, speed_data, expt_start_time)
         self.log('All data imported')
 
-    def create_from_metadata(self, metadata_file, user=None, session_id=None):
+    def create_from_metadata(self, metadata_file, user=None):
         """Create a base NWB file containing only experimental metadata."""
         assert self.nwb_open_mode == 'w', ("Can only create a file if opening "
                                            "in 'w' mode")