Implements MetaboLights slicer and test; updates to mtbls.md doc #1

isatools/io/mtbls.md

@@ -3,25 +3,36 @@ Intended usage of mtbls.py functionality:
 ```python
 from isatools.io import mtbls
 
-my_study_as_isa_json = mtbls.load('MTBLS1')
-factor_names = get_factor_names(my_study_as_isa_json)
+study_id = 'MTBLS1'
+
+factor_names = mtbls.get_factor_names(study_id)
 # response:
-# ['gender', 'age']
+# {'Gender', 'Age'}
+
+if 'Gender' in factor_names:
+    factor_values = mtbls.get_factor_values(study_id, 'Gender')
+    # response:
+    # {'Male', 'Female'}
 
-if 'gender' in factor_names:
-    query = { "gender": "male" }
-    samples_and_files = get_samples_and_files(my_study_as_isa_json, factor_query=query)
+    query = { "Gender": "Male" }
+    samples_and_files = mtbls.get_data_files(study_id, factor_query=query)
     # response:
-    #  {
-    #     “sample_1": [“data_uri_1", “data_uri_2", …],
-    #      “sample_2": [“data_uri_1", “data_uri_2", …]
-    #  }
+    #  [
+    #     {
+    #        'sample': 'ADG10003u_007'},
+    #        'data_files': ['ADG10003u_007.zip'],
+    #        'query_used': {'Gender': 'Male'}
+    #     }, ...
+    #  ]
 
-    for sample, files_in_sample in samples_and_files.items():
-        for file in files_in_sample:
-            # do something with the file, should be an ftp URL.
+    for sample_and_files in samples_and_files:
+        sample_name = sample_and_files['sample']
+        data_files = sample_and_files['data_files']
+        for data_file in data_files:
+            # do something with the file name, e.g. make it an ftp URL.
 ```
-The slicer needs to produce:
-
-- A reduced ISA file after the slicing.
+The slicer produces:
 - The list of URLs for Raw data files/study files to be downloaded by another tool.
+
+The slicer needs to produce:
+- A reduced ISA file after the slicing.