Reorganized the imports to make it cleaner

solidago/src/solidago/__init__.py

@@ -1,3 +1,7 @@
 """Solidago library, robust and secure algorithms for the Tournesol platform"""
 
 from .__version__ import __version__
+
+from .privacy_settings import PrivacySettings
+from .judgments import Judgments
+from .scoring_model import ScoringModel

solidago/src/solidago/aggregation/__init__.py

@@ -1,40 +1,8 @@
-from abc import ABC, abstractmethod
-
-import pandas as pd
-
-from solidago.voting_rights import VotingRights
-from solidago.scoring_model import ScoringModel
-
-
-class Aggregation:
-    @abstractmethod
-    def __call__(
-        self, 
-        voting_rights: VotingRights,
-        user_models: dict[int, ScoringModel],
-        users: pd.DataFrame,
-        entities: pd.DataFrame
-    ) -> tuple[dict[int, ScoringModel], ScoringModel]:
-        """ Returns scaled user models
-        
-        Parameters
-        ----------
-        voting_rights: VotingRights
-            voting_rights[user, entity]: float
-        user_models: dict[int, ScoringModel]
-            user_models[user] is user's scoring model
-        users: DataFrame with columns
-            * user_id (int, index)
-            * trust_score (float)
-        entities: DataFrame with columns
-            * entity_id (int, ind)
-
-        Returns
-        -------
-        updated_user_models[user]: ScoringModel
-            Returns a scaled user model
-        global_model: ScoringModel
-            Returns a global scoring model
-        """
-        raise NotImplementedError
-
+""" Step 5 of the pipeline.
+    
+Aggregation combines the different user models to construct a global model.
+The aggregation may also adjust the user models to the learned global model.
+"""
+
+from .base import Aggregation
+from .standardized_qrmed import QuantileStandardizedQrMedian

solidago/src/solidago/aggregation/base.py

@@ -0,0 +1,40 @@
+from abc import ABC, abstractmethod
+
+import pandas as pd
+
+from solidago.voting_rights import VotingRights
+from solidago.scoring_model import ScoringModel
+
+
+class Aggregation:
+    @abstractmethod
+    def __call__(
+        self, 
+        voting_rights: VotingRights,
+        user_models: dict[int, ScoringModel],
+        users: pd.DataFrame,
+        entities: pd.DataFrame
+    ) -> tuple[dict[int, ScoringModel], ScoringModel]:
+        """ Returns scaled user models
+        
+        Parameters
+        ----------
+        voting_rights: VotingRights
+            voting_rights[user, entity]: float
+        user_models: dict[int, ScoringModel]
+            user_models[user] is user's scoring model
+        users: DataFrame with columns
+            * user_id (int, index)
+            * trust_score (float)
+        entities: DataFrame with columns
+            * entity_id (int, ind)
+
+        Returns
+        -------
+        updated_user_models[user]: ScoringModel
+            Returns a scaled user model
+        global_model: ScoringModel
+            Returns a global scoring model
+        """
+        raise NotImplementedError
+

solidago/src/solidago/aggregation/standardized_qrmed.py

@@ -1,6 +1,6 @@
 import pandas as pd
 
-from . import Aggregation
+from .base import Aggregation
 
 from solidago.voting_rights import VotingRights
 from solidago.scoring_model import ScoringModel

solidago/src/solidago/generative_model/test_data.py

@@ -1,6 +1,7 @@
+from solidago import PrivacySettings
+
 from solidago.voting_rights import VotingRights
 from solidago.scoring_model import DirectScoringModel
-from solidago.privacy_settings import PrivacySettings
 from solidago.judgments import DataFrameJudgments
 from solidago.pipeline import Pipeline
 

solidago/src/solidago/pipeline/__init__.py

@@ -7,24 +7,14 @@
 import pandas as pd
 import logging
 
-from solidago.privacy_settings import PrivacySettings
-from solidago.judgments import Judgments
-from solidago.voting_rights import VotingRights
-from solidago.scoring_model import ScoringModel
+from solidago import PrivacySettings, Judgments, ScoringModel
 
-from solidago.trust_propagation import TrustPropagation
-from solidago.trust_propagation.lipschitrust import LipschiTrust
-from solidago.voting_rights import VotingRightsAssignment
-from solidago.voting_rights.affine_overtrust import AffineOvertrust
-from solidago.preference_learning import PreferenceLearning
-from solidago.preference_learning.generalized_bradley_terry import UniformGBT
-from solidago.scaling import Scaling, ScalingCompose
-from solidago.scaling.mehestan import Mehestan
-from solidago.scaling.quantile_zero_shift import QuantileZeroShift
-from solidago.aggregation import Aggregation
-from solidago.aggregation.standardized_qrmed import QuantileStandardizedQrMedian
-from solidago.post_process import PostProcess
-from solidago.post_process.squash import Squash
+from solidago.trust_propagation import TrustPropagation, LipschiTrust
+from solidago.voting_rights import VotingRights, VotingRightsAssignment, AffineOvertrust
+from solidago.preference_learning import PreferenceLearning, UniformGBT
+from solidago.scaling import Scaling, ScalingCompose, Mehestan, QuantileZeroShift
+from solidago.aggregation import Aggregation, QuantileStandardizedQrMedian
+from solidago.post_process import PostProcess, Squash
 
 logger = logging.getLogger(__name__)
 

solidago/src/solidago/post_process/__init__.py

@@ -1,25 +1,8 @@
-from abc import ABC, abstractmethod
+""" Step 6 of the pipeline.
+    
+Post-process modifies the user and global models, typically with the goal
+of yielding more human-readible scores.
+"""
 
-from solidago.scoring_model import ScoringModel
-
-class PostProcess(ABC):
-    @abstractmethod
-    def __call__(
-        self, 
-        user_models: dict[int, ScoringModel],
-        global_model: ScoringModel
-    ) -> tuple[dict[int, ScoringModel], ScoringModel]:
-        """ Post-processes user models and global models,
-        typically to yield human-readible scores
-        
-        Parameters
-        ----------
-        user_models: user_model[user] should be a ScoringModel to post-process
-        global_model: ScoringModel to post-process
-        
-        Returns
-        -------
-        user_models: post-processed user models
-        global_model: post-processed global model
-        """
-        raise NotImplementedError
+from .base import PostProcess
+from .squash import Squash

solidago/src/solidago/post_process/base.py

@@ -0,0 +1,25 @@
+from abc import ABC, abstractmethod
+
+from solidago.scoring_model import ScoringModel
+
+class PostProcess(ABC):
+    @abstractmethod
+    def __call__(
+        self, 
+        user_models: dict[int, ScoringModel],
+        global_model: ScoringModel
+    ) -> tuple[dict[int, ScoringModel], ScoringModel]:
+        """ Post-processes user models and global models,
+        typically to yield human-readible scores
+        
+        Parameters
+        ----------
+        user_models: user_model[user] should be a ScoringModel to post-process
+        global_model: ScoringModel to post-process
+        
+        Returns
+        -------
+        user_models: post-processed user models
+        global_model: post-processed global model
+        """
+        raise NotImplementedError

solidago/src/solidago/post_process/squash.py

@@ -2,7 +2,7 @@
 
 import numpy as np
 
-from . import PostProcess
+from .base import PostProcess
 from solidago.scoring_model import ScoringModel, PostProcessedScoringModel
 
 

solidago/src/solidago/preference_learning/__init__.py

@@ -1,55 +1,11 @@
-from abc import ABC, abstractmethod
-from typing import Optional
-
-import pandas as pd
-import numpy as np
-
-from solidago.scoring_model import ScoringModel
-
-
-class PreferenceLearning(ABC):
-    @abstractmethod
-    def __call__(
-        self, 
-        user_judgments: dict[str, pd.DataFrame],
-        entities: pd.DataFrame
-    ) -> ScoringModel:
-        """ Learns a scoring model, given user judgments of entities
-        
-        Parameters
-        ----------
-        user_judgments: dict[str, pd.DataFrame]
-            May contain different forms of judgments, 
-            but most likely will contain "comparisons" and/or "assessments"
-        entities: DataFrame with columns
-            * entity_id: int, index
-            * May contain others, such as vector representation
-        """
-        raise NotImplementedError
-
-
-class ComparisonBasedPreferenceLearning(PreferenceLearning):
-    @abstractmethod
-    def comparison_learning(self, comparisons, entities) -> ScoringModel:
-        """ Learns only based on comparisons
-        
-        Parameters
-        ----------
-        comparisons: DataFrame with columns
-            * entity_a: int
-            * entity_b: int
-            * score: float
-        entities: DataFrame with columns
-            * entity_id: int, index
-            * May contain others, such as vector representation
-        """
-        raise NotImplementedError
-
-    def __call__(
-        self, 
-        user_judgments: dict[str, pd.DataFrame],
-        entities: pd.DataFrame
-    ) -> ScoringModel:
-        return self.comparison_learning(user_judgments["comparisons"], entities)
-
+""" Step 3 of the pipeline.
     
+Preference learning infers, for each user and based on their data,
+a model of the user's preferences.
+This corresponds to the idea of "algorithmic representatives", 
+which will participate in the digital democracy 
+to remedy users' lack of activity and reactivity.
+"""
+
+from .base import PreferenceLearning
+from .generalized_bradley_terry import UniformGBT

solidago/src/solidago/preference_learning/base.py

@@ -0,0 +1,55 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+import pandas as pd
+import numpy as np
+
+from solidago.scoring_model import ScoringModel
+
+
+class PreferenceLearning(ABC):
+    @abstractmethod
+    def __call__(
+        self, 
+        user_judgments: dict[str, pd.DataFrame],
+        entities: pd.DataFrame
+    ) -> ScoringModel:
+        """ Learns a scoring model, given user judgments of entities
+        
+        Parameters
+        ----------
+        user_judgments: dict[str, pd.DataFrame]
+            May contain different forms of judgments, 
+            but most likely will contain "comparisons" and/or "assessments"
+        entities: DataFrame with columns
+            * entity_id: int, index
+            * May contain others, such as vector representation
+        """
+        raise NotImplementedError
+
+
+class ComparisonBasedPreferenceLearning(PreferenceLearning):
+    @abstractmethod
+    def comparison_learning(self, comparisons, entities) -> ScoringModel:
+        """ Learns only based on comparisons
+        
+        Parameters
+        ----------
+        comparisons: DataFrame with columns
+            * entity_a: int
+            * entity_b: int
+            * score: float
+        entities: DataFrame with columns
+            * entity_id: int, index
+            * May contain others, such as vector representation
+        """
+        raise NotImplementedError
+
+    def __call__(
+        self, 
+        user_judgments: dict[str, pd.DataFrame],
+        entities: pd.DataFrame
+    ) -> ScoringModel:
+        return self.comparison_learning(user_judgments["comparisons"], entities)
+
+

solidago/src/solidago/preference_learning/generalized_bradley_terry.py

@@ -6,7 +6,7 @@
 from solidago.scoring_model import ScoringModel, DirectScoringModel
 from solidago.solvers.optimize import coordinate_descent
 
-from . import ComparisonBasedPreferenceLearning
+from .base import ComparisonBasedPreferenceLearning
 
 
 class GeneralizedBradleyTerry(ComparisonBasedPreferenceLearning):