Minor updates

Author: Old-Shatterhand

datasail/routine.py

@@ -38,7 +38,7 @@ def tech2oneD(tech: str) -> tuple[str, str]:
         raise ValueError(f"Technique {tech} is not a two-dimensional technique.")
 
 
-def datasail_main(**kwargs) -> Optional[Tuple[Dict, Dict, Dict]]:
+def datasail_main(**kwargs) -> Optional[Tuple[Optional[Dict], Optional[Dict], Optional[Dict]]]:
     """
     Main routine of DataSAIL. Here the parsed input is aggregated into structures and then split and saved.
 
@@ -157,6 +157,10 @@ def datasail_main(**kwargs) -> Optional[Tuple[Dict, Dict, Dict]]:
                             map_[technique].append({})
                         map_[technique][run].update(pre_map[one_d_tech])
 
+    if all(len(e_run) == 0 for e_techs in e_name_split_map.values() for e_run in e_techs) and \
+            all(len(f_run) == 0 for f_techs in f_name_split_map.values() for f_run in f_techs):
+        LOGGER.error("No assignments could be made for any technique! Please check your input data and values for cluster-numbers, delta, and epsilon.")
+        return None, None, None
     LOGGER.info("Store results")
 
     # infer interaction assignment from entity assignment if necessary and possible

datasail/sail.py

@@ -119,14 +119,11 @@ def validate_args(**kwargs) -> Dict[str, object]:
         error("The filepath to the weights of the E-data is invalid.", 8, kwargs[KW_CLI])
     if kwargs[KW_E_STRAT] is not None and isinstance(kwargs[KW_E_STRAT], Path) and not kwargs[KW_E_STRAT].is_file():
         error("The filepath to the stratification of the E-data is invalid.", 11, kwargs[KW_CLI])
-    if kwargs[KW_E_SIM] is not None and isinstance(kwargs[KW_E_SIM], str) and kwargs[KW_E_SIM].lower() not in SIM_ALGOS:
-        kwargs[KW_E_SIM] = Path(kwargs[KW_E_SIM])
+    if kwargs[KW_E_SIM] is not None and (isinstance(kwargs[KW_E_SIM], Path) or kwargs[KW_E_SIM].lower() not in SIM_ALGOS):
         if not kwargs[KW_E_SIM].is_file():
             error(f"The similarity metric for the E-data seems to be a file-input but the filepath is invalid.",
                   9, kwargs[KW_CLI])
-    if kwargs[KW_E_DIST] is not None and isinstance(kwargs[KW_E_DIST], str) and \
-            kwargs[KW_E_DIST].lower() not in DIST_ALGOS:
-        kwargs[KW_E_DIST] = Path(kwargs[KW_E_DIST])
+    if kwargs[KW_E_DIST] is not None and (isinstance(kwargs[KW_E_DIST], Path) or kwargs[KW_E_DIST].lower() not in DIST_ALGOS):
         if not kwargs[KW_E_DIST].is_file():
             error(f"The distance metric for the E-data seems to be a file-input but the filepath is invalid.",
                   10, kwargs[KW_CLI])
@@ -142,13 +139,11 @@ def validate_args(**kwargs) -> Dict[str, object]:
         error("The filepath to the weights of the F-data is invalid.", 14, kwargs[KW_CLI])
     if kwargs[KW_E_STRAT] is not None and isinstance(kwargs[KW_E_STRAT], Path) and not kwargs[KW_E_STRAT].is_file():
         error("The filepath to the stratification of the E-data is invalid.", 20, kwargs[KW_CLI])
-    if kwargs[KW_F_SIM] is not None and isinstance(kwargs[KW_F_SIM], str) and kwargs[KW_F_SIM].lower() not in SIM_ALGOS:
-        kwargs[KW_F_SIM] = Path(kwargs[KW_F_SIM])
+    if kwargs[KW_F_SIM] is not None and (isinstance(kwargs[KW_F_SIM], Path) or kwargs[KW_F_SIM].lower() not in SIM_ALGOS):
         if not kwargs[KW_F_SIM].is_file():
             error(f"The similarity metric for the F-data seems to be a file-input but the filepath is invalid.",
                   15, kwargs[KW_CLI])
-    if kwargs[KW_F_DIST] is not None and isinstance(kwargs[KW_F_DIST], str) and \
-            kwargs[KW_F_DIST].lower() not in DIST_ALGOS:
+    if kwargs[KW_F_DIST] is not None and (isinstance(kwargs[KW_F_DIST], Path) or kwargs[KW_F_DIST].lower() not in DIST_ALGOS):
         if not kwargs[KW_F_DIST].is_file():
             error(f"The distance metric for the F-data seems to be a file-input but the filepath is invalid.",
                   16, kwargs[KW_CLI])

docs/faq.rst

@@ -11,22 +11,22 @@ conference discussions, GitHub issues, or other occasions. If you don't find hel
 Theoretical and Conceptional Questions
 --------------------------------------
 
-Does training on DataSAIL splits produce better generalizing models?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+1. Does training on DataSAIL splits produce better generalizing models?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Yes, training on DataSAIL splits generally leads to better generalizing models. The DataSAIL splits are designed to reduce information leakage between splits.
 Therefore, when used for hyperparameter tuning, they help in selecting models (and their hyperparameter) that generalize better to unseen data.
 
-What are the limitations of DataSAIL?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+2. What are the limitations of DataSAIL?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The most time and memory consuming step in DataSAIL is the clustering of the data. For most datatypes, this is done by third-party programms such as FoldSeek, 
 DIAMOND, or MASH. In that case, DataSAIL has no influence on the runtime and memory consumption. The user may provide their own commandline arguments to these 
 programs. 
 
 Practical Questions
 -------------------
 
-How can I relax the split constraints if DataSAIL fails to find a solution?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+1. How can I relax the split constraints if DataSAIL fails to find a solution?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Sometimes, DataSAIL is unable to solve the split problem and might output a message like:
 
 .. code-block:: shell
@@ -43,3 +43,14 @@ DataSAIL compiles your input into multiple variables and constraints that for a
 
 - If you are already on :code:`v1.2.0` or newer, you can set the :code:`epsilon` value to higher numbers. Default is :code:`0.05` but anything up to :code:`0.2` 
   or :code:`0.3` is totally reasonable. If you use stratification, you also need to set :code:`delta` to a higher value as both values are connected in that scenario.
+
+2. DataSAIL shows a log message stating the found solution is :code:`optimal_inaccurate`. What does that mean?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This message just means, that the solver in DataSAIL found a solution, but the optimization did not finish and was terminated because of the timeout. 
+Therefore, the solution is not guaranteed to be optimal, but it is still a valid solution that satisfies all constraints and is in most cases close to optimal. 
+Therefore, you can use that :code:`optimal_inaccurate` solution without problems.
+
+3. I set :code:`runs>1` but DataSAIL outputs the same splits each time. Why is that?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When you set the :code:`runs` variable to values greater than :code:`1`, DataSAIL will shuffle the dataset inbetween splitting rounds to run the optimization from different initializations.
+But since many datasets have a unique optimal solution, DataSAIL might find the same solution multiple times and output it mutliple times.