Merge pull request #1069 from vantage6/feature/studies

Feature/studies

docs/function-docs/client.rst

@@ -14,6 +14,10 @@ vantage6.client
    :members:
    :show-inheritance:
 
+.. automodule:: vantage6.client.subclients.study
+   :members:
+   :show-inheritance:
+
 .. automodule:: vantage6.client.subclients.algorithm
    :members:
    :show-inheritance:

docs/function-docs/server.rst

@@ -98,7 +98,7 @@ vantage6.server.resource.common.output_schema
     still the case (there that module is rewritten)
 
 .. automodule:: vantage6.server.resource.common.output_schema
-    :members: HATEOASModelSchema, create_one_to_many_link
+    :members:
 
 vantage6.server.resource.common.auth_helper
 +++++++++++++++++++++++++++++++++++++++++++

docs/introduction/introduction.rst

@@ -83,6 +83,10 @@ their relationships.
 -  For each collaboration, each participating organization needs a
    **node** to compute tasks. When a collaboration is created, accounts are also created
    for the nodes so that they can securely communicate with the server.
+-  Collaborations can contain **studies**. A study is a subset of organizations from the
+   collaboration that are involved in a specific research question. By setting up
+   studies, it can be easier to send tasks to a subset of the organizations in a
+   collaboration and to keep track of the results of these analyses.
 -  Each organization has zero or more **users** who can perform certain
    actions.
 -  The permissions of the user are defined by the assigned **rules**.
@@ -110,26 +114,33 @@ in multiple collaborations.
     left to right direction
 
     rectangle Collaboration
-    rectangle Organization
     rectangle Node
+    rectangle Organization
+    rectangle Study
     rectangle Task
     rectangle Result
     rectangle User
     rectangle Role
     rectangle Rule
 
-    Collaboration "n" -- "n" Organization
-    Organization "1" -left- "n" Node
     Collaboration "1" -- "n" Node
+    Collaboration "n" -- "n" Organization
+    Collaboration "1" -- "n" Study
+    Collaboration "1" -- "n" Task
+
+    Study "n" -left- "n" Organization
+    Study "1" -right- "n" Task
+
+    Node "n" -right- "1" Organization
 
     Organization "1" -- "n" User
     Organization "0" -- "n" Role
+    Task "1" -- "n" Result
+
     User "n" -left- "n" Role
     Role "n" -- "n" Rule
     User "n" -- "n" Rule
 
-    Collaboration "1" -- "n" Task
-    Task "1" -- "n" Result
 
 A simple federated average algorithm
 ------------------------------------

docs/server/permissions.rst

@@ -14,7 +14,7 @@ decorators that are placed on the API endpoints. These decorators check if the
 entity that is trying to access the endpoint is allowed to do so. For example,
 you may see the following decorators on an endpoint:
 
-* ``@only_for(['user', 'container']``: only accessible to users and algorithm
+* ``@only_for(('user', 'container'))``: only accessible to users and algorithm
   containers
 * ``@with_user``: only accessible to users
 

vantage6-algorithm-tools/vantage6/algorithm/client/__init__.py

@@ -46,6 +46,7 @@ def __init__(self, token: str, *args, **kwargs) -> None:
         self.databases = container_identity.get("databases", [])
         self.node_id = container_identity.get("node_id")
         self.collaboration_id = container_identity.get("collaboration_id")
+        self.study_id = container_identity.get("study_id")
         self.organization_id = container_identity.get("organization_id")
         self.log.info(
             f"Container in collaboration_id={self.collaboration_id} \n"
@@ -61,6 +62,7 @@ def __init__(self, token: str, *args, **kwargs) -> None:
         self.organization = self.Organization(self)
         self.collaboration = self.Collaboration(self)
         self.node = self.Node(self)
+        self.study = self.Study(self)
 
         self._access_token = token
 
@@ -377,6 +379,7 @@ def create(
                     "name": name,
                     "image": self.parent.image,
                     "collaboration_id": self.parent.collaboration_id,
+                    "study_id": self.parent.study_id,
                     "description": description,
                     "organizations": organization_json_list,
                     "databases": self.parent.databases,
@@ -583,9 +586,13 @@ def list(self) -> list[dict]:
             list[dict]
                 List of organizations in the collaboration.
             """
+            if self.parent.study_id:
+                params = {"study_id": self.parent.study_id}
+            else:
+                params = {"collaboration_id": self.parent.collaboration_id}
             return self.parent._multi_page_request(
                 endpoint="organization",
-                params={"collaboration_id": self.parent.collaboration_id},
+                params=params,
             )
 
     class Collaboration(ClientBase.SubClient):
@@ -620,3 +627,42 @@ def get(self) -> dict:
                 running on.
             """
             return self.parent.request(f"node/{self.parent.node_id}")
+
+    class Study(ClientBase.SubClient):
+        """
+        Get information about the study or studies.
+        """
+
+        def get(self, id_) -> dict:
+            """
+            Get the study data by ID.
+
+            Parameters
+            ----------
+            id_: int
+                ID of the study to retrieve
+
+            Returns
+            -------
+            dict
+                Dictionary containing study data.
+            """
+            return self.parent.request(f"study/{id_}")
+
+        def list(self) -> list[dict]:
+            """
+            Obtain all studies in the collaboration.
+
+            The container runs in a node which is part of a single
+            collaboration, which may contain zero or more studies. This method retrieves
+            all studies that are part of the collaboration.
+
+            Returns
+            -------
+            list[dict]
+                List of studies in the collaboration.
+            """
+            return self.parent._multi_page_request(
+                endpoint="study",
+                params={"collaboration_id": self.parent.collaboration_id},
+            )