Command history save and load

CHANGELOG.md

@@ -1,4 +1,6 @@
 # calour changelog
+## Version 2024.6.1
+* Add command_history file to Experiment read and save. When saving, a NAME_history.txt file is created with the command history used to create the Experiment. When loading, can supply a call_history="XXX" parameter to load the call history file into the loaded Experiment.
 
 ## Version 2024.5.30
 add mRNAExperiment class for handling rna-seq data. interactive heatmap gene information is via the rna_calour module using Harmonizome server (https://maayanlab.cloud/Harmonizome)

calour/__init__.py

@@ -19,7 +19,7 @@
 
 
 __credits__ = "https://github.com/biocore/calour/graphs/contributors"
-__version__ = "2024.5.30"
+__version__ = "2024.6.1"
 
 __all__ = ['read', 'read_amplicon', 'read_ms', 'read_qiime2',
            'Experiment', 'AmpliconExperiment', 'MS1Experiment','mRNAExperiment',

calour/io.py

@@ -345,6 +345,7 @@ def _read_metadata(ids, f, kwargs):
 
 @ds.get_sectionsf('io.read')
 def read(data_file, sample_metadata_file=None, feature_metadata_file=None,
+         call_history_file=None,
          description='', sparse=True,
          data_file_type='biom', data_file_sep=',', sample_in_row=False,
          sample_id_proc=None, feature_id_proc=None,
@@ -366,6 +367,8 @@ def read(data_file, sample_metadata_file=None, feature_metadata_file=None,
         metadata).
     feature_metadata_file : str, default=None
         File path to feature metadata.
+    call_history_file : str, default=None
+        File path to the call history file (one line per command, generated by Experiment.save() )
     description : str
         description of the experiment
     sparse : bool
@@ -475,9 +478,15 @@ def read(data_file, sample_metadata_file=None, feature_metadata_file=None,
         exp.normalize(total=normalize, inplace=True)
 
     # initialize the call history
-    param = ['{0!s}={1!r}'.format(k, v) for k, v in fparams.items()]
-    exp._call_history = ['{0}({1})'.format('read_amplicon', ','.join(param))]
+    exp._call_history = []
+    # if we have a command history file, load it
+    if call_history_file is not None:
+        old_call_history = read_call_history(call_history_file)
+        exp._call_history.extend(old_call_history)
 
+    param = ['{0!s}={1!r}'.format(k, v) for k, v in fparams.items()]
+    exp._call_history.append('{0}({1})'.format('read', ','.join(param)))
+
     logger.info('Loaded %d samples, %d features' % (exp.shape[0], exp.shape[1]))
 
     return exp
@@ -524,10 +533,6 @@ def read_amplicon(data_file, sample_metadata_file=None,
     if normalize is not None:
         exp.normalize(total=normalize, axis=0, inplace=True)
 
-    # initialize the call history
-    param = ['{0!s}={1!r}'.format(k, v) for k, v in fparams.items()]
-    exp._call_history = ['{0}({1})'.format('read_amplicon', ','.join(param))]
-
     return exp
 
 
@@ -732,7 +737,7 @@ def read_ms(data_file, sample_metadata_file=None, feature_metadata_file=None, gn
 
     # initialize the call history
     param = ['{0!s}={1!r}'.format(k, v) for k, v in fparams.items()]
-    exp._call_history = ['{0}({1})'.format('read_amplicon', ','.join(param))]
+    exp._call_history.append(['{0}({1})'.format('read_ms', ','.join(param))])
     return exp
 
 
@@ -776,6 +781,39 @@ def save(exp: Experiment, prefix, fmt='hdf5'):
     exp.save_biom('%s.biom' % prefix, fmt=fmt)
     exp.sample_metadata.to_csv('%s_sample.txt' % prefix, sep='\t')
     exp.feature_metadata.to_csv('%s_feature.txt' % prefix, sep='\t')
+    exp.save_call_history('%s_history.txt' % prefix)
+
+
+def save_call_history(exp: Experiment, f):
+    '''Save experiment call history to file
+    Save the command history used to generate the experiment to a file.
+    History file is a text file with one line per call to a calour function.
+
+    Parameters
+    ----------
+    f : str
+        the file name to save to
+    '''
+    with open(f, 'w') as f:
+        for cline in exp._call_history:
+            f.write('%s\n' % cline)
+
+
+def read_call_history(f):
+    '''Load the call history from a file
+
+    Parameters
+    ----------
+    f : str
+        the file name to load from
+
+    Returns
+    -------
+    list of str
+        the call history
+    '''
+    with open(f, 'r') as f:
+        return [x.strip() for x in f]
 
 
 def save_biom(exp: Experiment, f, fmt='hdf5', add_metadata='taxonomy'):