Update docs for self.clean_s_name() function

tsjzz · Jul 4, 2021 · a4c277b · a4c277b
1 parent 3bc7afc
commit a4c277b
Showing 1 changed file with 24 additions and 3 deletions.
diff --git a/docs/modules.md b/docs/modules.md
@@ -534,16 +534,37 @@ To do this, you should use the `self.clean_s_name()` function, as
 this will prepend the directory name if requested on the command line:
 
 ```python
-input_fname = s[3] # Or parsed however
-s_name = self.clean_s_name(input_fname, f['root'])
+for f in self.find_log_files('mymod'):
+    input_fname, data = self.my_custom_parsing(f) # Or parsed however
+    s_name = self.clean_s_name(input_fname, f)
 ```
 
-This function has already been applied to the contents of `f['s_name']`.
+This function has already been applied to the contents of `f['s_name']`,
+so it is only required when using something different for the sample identifier.
 
 > `self.clean_s_name()` **must** be used on sample names parsed from the file
 > contents. Without it, features such as prepending directories (`--dirs`)
 > will not work.
 
+The second argument should be the dictionary returned by the `self.find_log_files()` function.
+The root path is used for `--dirs` and the search pattern key is used
+for fine-grained configuration of the config option `use_filename_as_sample_name`.
+
+If you are using non-standard values for the logfile root, filename or search pattern
+key, these can be specified. The function def looks like this:
+
+```python
+def clean_s_name(self, s_name, f=None, root=None, filename=None, seach_pattern_key=None):
+```
+
+A tyical example is when the sample name is the log file directory.
+In this case, the root should be the dirname of that directory.
+This is non-standard, and would be specified as follows:
+
+```python
+s_name = self.clean_s_name(f["root"], f, root=os.path.dirname(f["root"]))
+```
+
 ### Identical sample names
 
 If modules find samples with identical names, then the previous sample