From 197a1d491fbffcd2dc3d04a4e1940ab4b63d14be Mon Sep 17 00:00:00 2001 From: Hardik Ojha <44747868+kidrahahjo@users.noreply.github.com> Date: Wed, 24 Feb 2021 23:38:16 +0530 Subject: [PATCH 01/28] Add aggregation docs without FlowGroups --- docs/source/aggregation.rst | 151 ++++++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 docs/source/aggregation.rst diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst new file mode 100644 index 00000000..e9b61bf6 --- /dev/null +++ b/docs/source/aggregation.rst @@ -0,0 +1,151 @@ +.. _aggregation: + +=========== +Aggregation +=========== + +This chapter provides information about the passing aggregates of jobs to operation functions. + + +.. _aggregator_definition: + +aggregator +========== + +An :class:`~flow.aggregator` is used as a decorator for an operation function which acts like an +entry point to define the type of aggregation to perform while submitting or running the operation +function. + +.. code-block:: python + + # project.py + from flow import FlowProject, aggregator + + class Project(FlowProject): + pass + + @aggregator() + @Project.operation + def op1(*jobs): + pass + + @Project.operation + def op2(job): + pass + + if __name__ == '__main__': + Project().main() + +By default, if :class:`~flow.aggregator` is used as a decorator, aggregate of all the jobs present +in the project will be created. In the above example, ``op1`` can be referred to as an *aggregate operation* +where all the jobs present in the project are passed as arbitraty arguments (or ``*args``) and ``op2`` is a *normal operation* +where only a single job is passed as a parameter. + + +.. _types_of_aggregation: + +Types of Aggregation +==================== + +Currently **signac-flow** allows users to aggregate jobs by: + +- Grouping them on state point key, an iterable of state point keys whose values define the + groupings, or an arbitrary callable of :class:`~signac.contrib.job.Job`. +- Generating aggregates of a given size. +- Using custom aggregator function when greater flexibility is needed. + +Group By +--------- + +:class:`~flow.aggregator.groupby` allows users to aggregate jobs by grouping them on +state point key, an iterable of state point keys whose values define the groupings, +or an arbitrary callable of :class:`~signac.contrib.job.Job`. + +.. code-block:: python + + @aggregator.groupby('temperature') + @Project.operation + def op3(*jobs): + pass + +In the above example, the jobs will get aggregated based on the state point **temperature**. +So, all the jobs having the same value of **temperature** in their state point will be aggregated together. + +Groups Of +--------- + +:class:`~flow.aggregator.groupsof` allows users to aggregate jobs by generating aggregates of a given size. + +.. code-block:: python + + @aggregator.groupsof(2) + @Project.operation + def op4(job1, job2): + pass + +In the above example, the jobs will get aggregated in groups of 2 and hence, only two jobs will +be passed as parameters at once. + +.. note:: + + In case the number of jobs in the project is odd, there will be one aggregate containing only a single + job and hence users should be careful while defining the parameters for an *aggregate operation*. + +Sorting jobs for aggregation +---------------------------- + +**signac-flow** allows users to define the sorting order of jobs before creating the aggregates with the +help of ``sort_by`` parameter and the sorting order can be defined with the help of ``sort_ascending`` parameter. + +.. code-block:: python + + @aggregator.groupsof(2, sort_by='temperature', sort_ascending=False) + @Project.operation + def op5(job1, job2): + pass + +.. note:: + + In the above example, all the jobs will be sorted by the state point parameter ``temperature`` in descending + order and then be aggregated as groups of 2. + +Selecting jobs for aggregation +------------------------------ +**signac-flow** allows users to selectively choose which jobs to pass into operation functions. + +.. code-block:: python + + @aggregator(select=lambda job: job.sp.temperature > 0) + @Project.operation + def op6(job1, job2): + pass + + +.. _aggregate_id: + +Aggregate ID +============ + +Similar to the concept of a job id, an aggregate id is a unique hash identifying an aggregate of jobs. +The aggregate id is sensitive to the order of the jobs in the aggregate + +.. note:: + + The id of an aggregate containing one job is that job's id. + +In order to distinguish between aggregate id and a job id, for an aggregate of more than one job +the aggregate id of that aggregate will always have a prefix ``agg-``. + +Users can generate the aggregate id of an aggregate using :meth:`flow.get_aggregate_id`. + +.. tip:: + + Users can also pass an aggregate id to the ``--job-id`` command-line flag provided by **signac-flow** + in ``run``, ``submit``, and ``exec``. + + +.. _aggregation_with_flow_groups: + +Aggregation with FlowGroups +=========================== + From 61f9c0809c493fb339808f81e38c32d2ac0d34e4 Mon Sep 17 00:00:00 2001 From: Hardik Ojha <44747868+kidrahahjo@users.noreply.github.com> Date: Wed, 24 Feb 2021 23:52:34 +0530 Subject: [PATCH 02/28] Add documentation for aggregation with FlowGroups --- docs/source/aggregation.rst | 38 ++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index e9b61bf6..9fad1ed4 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -47,7 +47,7 @@ where only a single job is passed as a parameter. Types of Aggregation ==================== -Currently **signac-flow** allows users to aggregate jobs by: +Currently, **signac-flow** allows users to aggregate jobs by: - Grouping them on state point key, an iterable of state point keys whose values define the groupings, or an arbitrary callable of :class:`~signac.contrib.job.Job`. @@ -149,3 +149,39 @@ Users can generate the aggregate id of an aggregate using :meth:`flow.get_aggreg Aggregation with FlowGroups =========================== +In order to associate aggregator object with a :py:class:`FlowGroup`, **signac-flow** provides a +``aggregator_obj`` parameter in :meth:`~flow.FlowProject.make_group`. By default, no aggregation takes +place for a :py:class:`FlowGroup`. + +.. note:: + + Currently, **signac-flow** only allows single :class:`~flow.aggregator` per group, i.e. all the operations present + in a :py:class:`FlowGroup` will be using a same :class:`~flow.aggregator` object. + +.. code-block:: python + + # project.py + from flow import FlowProject, aggregator + + class Project(FlowProject): + pass + + group = Project.make_group('agg-group', aggregator_obj=aggregator()) + + @group + @aggregator() + @Project.operation + def op1(*jobs): + pass + + @group + @Project.operation + def op2(*jobs): + pass + + if __name__ == '__main__': + Project().main() + +In the above example, when the group ``agg-group`` is executed, all the jobs +in the project are passed as arbitrary arguments for ``op1`` and ``op2``. But if only ``op2`` is +executed, only a single job is passed as a parameter. From b65f9f37bfa6478200ecd5711b63a12851fb80bb Mon Sep 17 00:00:00 2001 From: Hardik Ojha <44747868+kidrahahjo@users.noreply.github.com> Date: Sat, 22 May 2021 00:51:46 +0530 Subject: [PATCH 03/28] Address reviews and update docs with current API --- docs/source/aggregation.rst | 55 ++++++++++++++----------------------- 1 file changed, 20 insertions(+), 35 deletions(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index 9fad1ed4..5de5fd01 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -12,9 +12,7 @@ This chapter provides information about the passing aggregates of jobs to operat aggregator ========== -An :class:`~flow.aggregator` is used as a decorator for an operation function which acts like an -entry point to define the type of aggregation to perform while submitting or running the operation -function. +An :class:`~flow.aggregator` is used as a decorator for an operation function which acts as an entry point to define the type of aggregation to perform while submitting or running the operation function. .. code-block:: python @@ -36,10 +34,8 @@ function. if __name__ == '__main__': Project().main() -By default, if :class:`~flow.aggregator` is used as a decorator, aggregate of all the jobs present -in the project will be created. In the above example, ``op1`` can be referred to as an *aggregate operation* -where all the jobs present in the project are passed as arbitraty arguments (or ``*args``) and ``op2`` is a *normal operation* -where only a single job is passed as a parameter. +By default, if :class:`~flow.aggregator` is used as a decorator, aggregate of all the jobs present in the project will be created. +In the above example, ``op1`` can be referred to as an *aggregate operation* where all the jobs present in the project are passed as arbitraty arguments (or ``*args``) and ``op2`` is a *normal operation* where only a single job is passed as a parameter. .. _types_of_aggregation: @@ -49,17 +45,14 @@ Types of Aggregation Currently, **signac-flow** allows users to aggregate jobs by: -- Grouping them on state point key, an iterable of state point keys whose values define the - groupings, or an arbitrary callable of :class:`~signac.contrib.job.Job`. +- Grouping them on state point key, an iterable of state point keys whose values define the groupings, or an arbitrary callable of :class:`~signac.contrib.job.Job`. - Generating aggregates of a given size. - Using custom aggregator function when greater flexibility is needed. Group By --------- -:class:`~flow.aggregator.groupby` allows users to aggregate jobs by grouping them on -state point key, an iterable of state point keys whose values define the groupings, -or an arbitrary callable of :class:`~signac.contrib.job.Job`. +:class:`~flow.aggregator.groupby` allows users to aggregate jobs by grouping them on state point key, an iterable of state point keys whose values define the groupings, or an arbitrary callable of :class:`~signac.contrib.job.Job`. .. code-block:: python @@ -80,22 +73,20 @@ Groups Of @aggregator.groupsof(2) @Project.operation - def op4(job1, job2): + def op4(job1, job2=None): pass -In the above example, the jobs will get aggregated in groups of 2 and hence, only two jobs will -be passed as parameters at once. +In the above example, the jobs will get aggregated in groups of 2 and hence, up to two jobs will be passed as parameters at once. .. note:: - In case the number of jobs in the project is odd, there will be one aggregate containing only a single - job and hence users should be careful while defining the parameters for an *aggregate operation*. + In case the number of jobs in the project is odd, there will be one aggregate containing only a single job and hence users should be careful while defining the parameters for an *aggregate operation*. Sorting jobs for aggregation ---------------------------- -**signac-flow** allows users to define the sorting order of jobs before creating the aggregates with the -help of ``sort_by`` parameter and the sorting order can be defined with the help of ``sort_ascending`` parameter. +**signac-flow** allows users to define the sorting order of jobs before creating the aggregates with the help of ``sort_by`` parameter and the sorting order can be defined with the help of ``sort_ascending`` parameter. +By default, when no `sort_by` parameter is specified, the order of the jobs will be decided by the order in which the jobs are iterated in a **signac** project. .. code-block:: python @@ -106,11 +97,11 @@ help of ``sort_by`` parameter and the sorting order can be defined with the help .. note:: - In the above example, all the jobs will be sorted by the state point parameter ``temperature`` in descending - order and then be aggregated as groups of 2. + In the above example, all the jobs will be sorted by the state point parameter ``temperature`` in descending order and then be aggregated as groups of 2. Selecting jobs for aggregation ------------------------------ + **signac-flow** allows users to selectively choose which jobs to pass into operation functions. .. code-block:: python @@ -127,21 +118,20 @@ Aggregate ID ============ Similar to the concept of a job id, an aggregate id is a unique hash identifying an aggregate of jobs. -The aggregate id is sensitive to the order of the jobs in the aggregate +The aggregate id is sensitive to the order of the jobs in the aggregate. + .. note:: The id of an aggregate containing one job is that job's id. -In order to distinguish between aggregate id and a job id, for an aggregate of more than one job -the aggregate id of that aggregate will always have a prefix ``agg-``. +In order to distinguish between aggregate id and a job id, for an aggregate of more than one job the aggregate id of that aggregate will always have a prefix ``agg-``. Users can generate the aggregate id of an aggregate using :meth:`flow.get_aggregate_id`. .. tip:: - Users can also pass an aggregate id to the ``--job-id`` command-line flag provided by **signac-flow** - in ``run``, ``submit``, and ``exec``. + Users can also pass an aggregate id to the ``--job-id`` command-line flag provided by **signac-flow** in ``run``, ``submit``, and ``exec``. .. _aggregation_with_flow_groups: @@ -149,14 +139,11 @@ Users can generate the aggregate id of an aggregate using :meth:`flow.get_aggreg Aggregation with FlowGroups =========================== -In order to associate aggregator object with a :py:class:`FlowGroup`, **signac-flow** provides a -``aggregator_obj`` parameter in :meth:`~flow.FlowProject.make_group`. By default, no aggregation takes -place for a :py:class:`FlowGroup`. +In order to associate aggregator object with a :py:class:`FlowGroup`, **signac-flow** provides a ``group_aggregator`` parameter in :meth:`~flow.FlowProject.make_group`. By default, no aggregation takes place for a :py:class:`FlowGroup`. .. note:: - Currently, **signac-flow** only allows single :class:`~flow.aggregator` per group, i.e. all the operations present - in a :py:class:`FlowGroup` will be using a same :class:`~flow.aggregator` object. + Currently, **signac-flow** only allows single :class:`~flow.aggregator` per group, i.e., all the operations present in a :py:class:`FlowGroup` will be using the same :class:`~flow.aggregator` object. .. code-block:: python @@ -166,7 +153,7 @@ place for a :py:class:`FlowGroup`. class Project(FlowProject): pass - group = Project.make_group('agg-group', aggregator_obj=aggregator()) + group = Project.make_group('agg-group', group_aggregator=aggregator()) @group @aggregator() @@ -182,6 +169,4 @@ place for a :py:class:`FlowGroup`. if __name__ == '__main__': Project().main() -In the above example, when the group ``agg-group`` is executed, all the jobs -in the project are passed as arbitrary arguments for ``op1`` and ``op2``. But if only ``op2`` is -executed, only a single job is passed as a parameter. +In the above example, when the group ``agg-group`` is executed, all the jobs in the project are passed as arbitrary arguments for ``op1`` and ``op2``. But if only ``op2`` is executed, only a single job is passed as a parameter. From cc7de692b26ced05a8ff2de0f2874166682167d7 Mon Sep 17 00:00:00 2001 From: Hardik Ojha <44747868+kidrahahjo@users.noreply.github.com> Date: Sat, 22 May 2021 01:03:54 +0530 Subject: [PATCH 04/28] Improve wordings --- docs/source/aggregation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index 5de5fd01..2d38d458 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -80,7 +80,7 @@ In the above example, the jobs will get aggregated in groups of 2 and hence, up .. note:: - In case the number of jobs in the project is odd, there will be one aggregate containing only a single job and hence users should be careful while defining the parameters for an *aggregate operation*. + In case the number of jobs in the project is odd, there will be one aggregate containing only a single job and hence users should be careful while passing non-default arguments in an *aggregate operation*. Sorting jobs for aggregation ---------------------------- From 5d4b5c65c776c1c91cc8862d93989805b07d4be2 Mon Sep 17 00:00:00 2001 From: Hardik Ojha <44747868+kidrahahjo@users.noreply.github.com> Date: Sun, 23 May 2021 00:53:33 +0530 Subject: [PATCH 05/28] Address code review --- docs/source/aggregation.rst | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index 2d38d458..f4ef5201 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -12,8 +12,7 @@ This chapter provides information about the passing aggregates of jobs to operat aggregator ========== -An :class:`~flow.aggregator` is used as a decorator for an operation function which acts as an entry point to define the type of aggregation to perform while submitting or running the operation function. - +An :class:`~flow.aggregator` is used as a decorator for operation functions which allows users to aggregate jobs and pass them as arguments in the operation functions. .. code-block:: python # project.py @@ -34,9 +33,12 @@ An :class:`~flow.aggregator` is used as a decorator for an operation function wh if __name__ == '__main__': Project().main() -By default, if :class:`~flow.aggregator` is used as a decorator, aggregate of all the jobs present in the project will be created. -In the above example, ``op1`` can be referred to as an *aggregate operation* where all the jobs present in the project are passed as arbitraty arguments (or ``*args``) and ``op2`` is a *normal operation* where only a single job is passed as a parameter. +If :class:`~flow.aggregator` is used with the default arguments, an aggregate of all the jobs present in the project will be created. +In the above example, ``op1`` can be referred to as an *aggregate operation* where all the jobs present in the project are passed as arbitraty arguments (or ``*args``) and ``op2`` is a *normal operation* where only a single job is passed as an argument. + +.. note:: + For an aggregate operation, all the other functionalities like :class:`~flow.FlowProject.pre`, :class:`~flow.FlowProject.post`, callable directives, etc., are required to take the same number of jobs as the operation as arguments. .. _types_of_aggregation: @@ -76,7 +78,7 @@ Groups Of def op4(job1, job2=None): pass -In the above example, the jobs will get aggregated in groups of 2 and hence, up to two jobs will be passed as parameters at once. +In the above example, the jobs will get aggregated in groups of 2 and hence, up to two jobs will be passed as arguments at once. .. note:: @@ -86,7 +88,7 @@ Sorting jobs for aggregation ---------------------------- **signac-flow** allows users to define the sorting order of jobs before creating the aggregates with the help of ``sort_by`` parameter and the sorting order can be defined with the help of ``sort_ascending`` parameter. -By default, when no `sort_by` parameter is specified, the order of the jobs will be decided by the order in which the jobs are iterated in a **signac** project. +By default, when no ``sort_by`` parameter is specified, the order of the jobs will be decided by the order in which the jobs are iterated in a **signac** project. .. code-block:: python @@ -139,7 +141,8 @@ Users can generate the aggregate id of an aggregate using :meth:`flow.get_aggreg Aggregation with FlowGroups =========================== -In order to associate aggregator object with a :py:class:`FlowGroup`, **signac-flow** provides a ``group_aggregator`` parameter in :meth:`~flow.FlowProject.make_group`. By default, no aggregation takes place for a :py:class:`FlowGroup`. +In order to associate aggregator object with a :py:class:`FlowGroup`, **signac-flow** provides a ``group_aggregator`` parameter in :meth:`~flow.FlowProject.make_group`. +By default, no aggregation takes place for a :py:class:`FlowGroup`. .. note:: @@ -169,4 +172,5 @@ In order to associate aggregator object with a :py:class:`FlowGroup`, **signac-f if __name__ == '__main__': Project().main() -In the above example, when the group ``agg-group`` is executed, all the jobs in the project are passed as arbitrary arguments for ``op1`` and ``op2``. But if only ``op2`` is executed, only a single job is passed as a parameter. +In the above example, when the group ``agg-group`` is executed using ``python project.py run -o agg-group``, all the jobs in the project are passed as arbitrary arguments for both, ``op1`` and ``op2``. +But if ``op2`` is executed using ``python project.py run -o op2``, only a single job is passed as an argument because no :class:`~flow.aggregator` is associated with the operation function ``op2``. From 120db74027967b378ce3393e5ed6b2391cad910a Mon Sep 17 00:00:00 2001 From: Hardik Ojha <44747868+kidrahahjo@users.noreply.github.com> Date: Thu, 24 Jun 2021 23:25:54 +0530 Subject: [PATCH 06/28] Improvements to doc --- docs/source/aggregation.rst | 40 +++++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index f4ef5201..0eb9fae3 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -12,7 +12,10 @@ This chapter provides information about the passing aggregates of jobs to operat aggregator ========== -An :class:`~flow.aggregator` is used as a decorator for operation functions which allows users to aggregate jobs and pass them as arguments in the operation functions. +An :class:`~flow.aggregator` is used as a decorator for operation functions which accept a variable number of positional arguments, ``*jobs``. +The argument ``*jobs`` is unpacked into an *aggregate*, defined as an ordered tuple of jobs. +See also the Python documentation about :ref:`argument unpacking `. + .. code-block:: python # project.py @@ -24,7 +27,7 @@ An :class:`~flow.aggregator` is used as a decorator for operation functions whic @aggregator() @Project.operation def op1(*jobs): - pass + print("Number of jobs in aggregate:", len(jobs)) @Project.operation def op2(job): @@ -33,12 +36,12 @@ An :class:`~flow.aggregator` is used as a decorator for operation functions whic if __name__ == '__main__': Project().main() -If :class:`~flow.aggregator` is used with the default arguments, an aggregate of all the jobs present in the project will be created. -In the above example, ``op1`` can be referred to as an *aggregate operation* where all the jobs present in the project are passed as arbitraty arguments (or ``*args``) and ``op2`` is a *normal operation* where only a single job is passed as an argument. +If :class:`~flow.aggregator` is used with the default arguments, it will create a single aggregate containing all the jobs present in the project. +In the example above, ``op1`` is an *aggregate operation* where all the jobs present in the project are passed as a variable number of positional arguments (via ``*jobs``), while ``op2`` is a normal operation where only a single job is passed as an argument. .. note:: - For an aggregate operation, all the other functionalities like :class:`~flow.FlowProject.pre`, :class:`~flow.FlowProject.post`, callable directives, etc., are required to take the same number of jobs as the operation as arguments. + For an aggregate operation, all conditions like :class:`~flow.FlowProject.pre` or :class:`~flow.FlowProject.post`, callable directives, and other features are required to take the same number of jobs as the operation as arguments. .. _types_of_aggregation: @@ -52,18 +55,18 @@ Currently, **signac-flow** allows users to aggregate jobs by: - Using custom aggregator function when greater flexibility is needed. Group By ---------- +-------- :class:`~flow.aggregator.groupby` allows users to aggregate jobs by grouping them on state point key, an iterable of state point keys whose values define the groupings, or an arbitrary callable of :class:`~signac.contrib.job.Job`. .. code-block:: python - @aggregator.groupby('temperature') + @aggregator.groupby("temperature") @Project.operation def op3(*jobs): pass -In the above example, the jobs will get aggregated based on the state point **temperature**. +In the above example, the jobs will be aggregated based on the state point key ``"temperature"``. So, all the jobs having the same value of **temperature** in their state point will be aggregated together. Groups Of @@ -82,24 +85,27 @@ In the above example, the jobs will get aggregated in groups of 2 and hence, up .. note:: - In case the number of jobs in the project is odd, there will be one aggregate containing only a single job and hence users should be careful while passing non-default arguments in an *aggregate operation*. + In case the number of jobs in the project in this example is odd, there will be one aggregate containing only a single job. + In general, the last aggregate from :class:`~flow.aggregator.groupsof` will contain the remaining jobs if the aggregate size does not evenly divide the number of jobs in the project. + Users should be careful while passing non-default arguments in an *aggregate operation*. Sorting jobs for aggregation ---------------------------- -**signac-flow** allows users to define the sorting order of jobs before creating the aggregates with the help of ``sort_by`` parameter and the sorting order can be defined with the help of ``sort_ascending`` parameter. -By default, when no ``sort_by`` parameter is specified, the order of the jobs will be decided by the order in which the jobs are iterated in a **signac** project. +Aggregators allow users to define the sorting order of jobs with the ``sort_by`` parameter. +The sorting order can be defined with the ``sort_ascending`` parameter. +By default, when no ``sort_by`` parameter is specified, the order of the jobs will be decided by the iteration order of the **signac** project. .. code-block:: python @aggregator.groupsof(2, sort_by='temperature', sort_ascending=False) @Project.operation - def op5(job1, job2): + def op5(*jobs): pass .. note:: - In the above example, all the jobs will be sorted by the state point parameter ``temperature`` in descending order and then be aggregated as groups of 2. + In the above example, all the jobs will be sorted by the state point parameter ``"temperature"`` in descending order and then be aggregated as groups of 2. Selecting jobs for aggregation ------------------------------ @@ -110,7 +116,7 @@ Selecting jobs for aggregation @aggregator(select=lambda job: job.sp.temperature > 0) @Project.operation - def op6(job1, job2): + def op6(*jobs): pass @@ -146,7 +152,7 @@ By default, no aggregation takes place for a :py:class:`FlowGroup`. .. note:: - Currently, **signac-flow** only allows single :class:`~flow.aggregator` per group, i.e., all the operations present in a :py:class:`FlowGroup` will be using the same :class:`~flow.aggregator` object. + All the operations in a :py:class:`FlowGroup` will use the same :class:`~flow.aggregator` object provided to the group's ``group_aggregator`` parameter. .. code-block:: python @@ -172,5 +178,5 @@ By default, no aggregation takes place for a :py:class:`FlowGroup`. if __name__ == '__main__': Project().main() -In the above example, when the group ``agg-group`` is executed using ``python project.py run -o agg-group``, all the jobs in the project are passed as arbitrary arguments for both, ``op1`` and ``op2``. -But if ``op2`` is executed using ``python project.py run -o op2``, only a single job is passed as an argument because no :class:`~flow.aggregator` is associated with the operation function ``op2``. +In the above example, when the group ``agg-group`` is executed using ``python project.py run -o agg-group``, all the jobs in the project are passed as positional arguments for both ``op1`` and ``op2``. +If ``op2`` is executed using ``python project.py run -o op2``, only a single job is passed as an argument because no :class:`~flow.aggregator` is associated with the operation function ``op2``. From c527af3ecd578cf1350a521adfb2f3c770e341ff Mon Sep 17 00:00:00 2001 From: Hardik Ojha <44747868+kidrahahjo@users.noreply.github.com> Date: Thu, 24 Jun 2021 23:41:46 +0530 Subject: [PATCH 07/28] Improve wording --- docs/source/aggregation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index 0eb9fae3..fba0196d 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -92,7 +92,7 @@ In the above example, the jobs will get aggregated in groups of 2 and hence, up Sorting jobs for aggregation ---------------------------- -Aggregators allow users to define the sorting order of jobs with the ``sort_by`` parameter. +Aggregators allow users to sort the jobs before creating aggregates with the ``sort_by`` parameter. The sorting order can be defined with the ``sort_ascending`` parameter. By default, when no ``sort_by`` parameter is specified, the order of the jobs will be decided by the iteration order of the **signac** project. From a2fa6d80890bf9cafa9ec5d328d9bc2519cfed89 Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Fri, 25 Jun 2021 10:07:27 -0500 Subject: [PATCH 08/28] Update docs/source/aggregation.rst Co-authored-by: Carl Simon Adorf --- docs/source/aggregation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index fba0196d..ea5860a3 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -4,7 +4,7 @@ Aggregation =========== -This chapter provides information about the passing aggregates of jobs to operation functions. +This chapter provides information about passing aggregates of jobs to operation functions. .. _aggregator_definition: From 971d82802ecd02343ddb41a0262d995862f6eca5 Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Fri, 25 Jun 2021 10:15:18 -0500 Subject: [PATCH 09/28] Update docs/source/aggregation.rst Co-authored-by: Carl Simon Adorf --- docs/source/aggregation.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index ea5860a3..ac0375f3 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -48,11 +48,13 @@ In the example above, ``op1`` is an *aggregate operation* where all the jobs pre Types of Aggregation ==================== -Currently, **signac-flow** allows users to aggregate jobs by: +Currently, **signac-flow** allows users to aggregate jobs in the following ways: -- Grouping them on state point key, an iterable of state point keys whose values define the groupings, or an arbitrary callable of :class:`~signac.contrib.job.Job`. -- Generating aggregates of a given size. -- Using custom aggregator function when greater flexibility is needed. +- _All jobs_: All of the project's jobs are passed to the operation function. +- _Group by state point key(s)_: The aggregates are grouped by one or more state point keys. +- _Group by arbitrary key-function_: The aggregates are grouped by keys determined by a key-function that expects an instance of :class:`~.signac.contrib.job.Job` and return the grouping key. +- Grouping into aggregates of a specific size. +- Using a completely custom aggregator function when even greater flexibility is needed. Group By -------- From 5a3804e11679320bf793e0f7f66093ddcd2d4c6b Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Fri, 25 Jun 2021 10:17:48 -0500 Subject: [PATCH 10/28] Update docs/source/aggregation.rst Co-authored-by: Carl Simon Adorf --- docs/source/aggregation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index ac0375f3..c820c30f 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -89,7 +89,7 @@ In the above example, the jobs will get aggregated in groups of 2 and hence, up In case the number of jobs in the project in this example is odd, there will be one aggregate containing only a single job. In general, the last aggregate from :class:`~flow.aggregator.groupsof` will contain the remaining jobs if the aggregate size does not evenly divide the number of jobs in the project. - Users should be careful while passing non-default arguments in an *aggregate operation*. + If a remainder is expected and valid, users should make sure that the operation function can be called with the reduced number of arguments (e.g. by using `*jobs*` or providing default arguments as shown above). Sorting jobs for aggregation ---------------------------- From 12833617aa1fcc2aecaff3b3c30006fdab06c371 Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Fri, 25 Jun 2021 10:18:33 -0500 Subject: [PATCH 11/28] Update docs/source/aggregation.rst --- docs/source/aggregation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index c820c30f..2709a364 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -89,7 +89,7 @@ In the above example, the jobs will get aggregated in groups of 2 and hence, up In case the number of jobs in the project in this example is odd, there will be one aggregate containing only a single job. In general, the last aggregate from :class:`~flow.aggregator.groupsof` will contain the remaining jobs if the aggregate size does not evenly divide the number of jobs in the project. - If a remainder is expected and valid, users should make sure that the operation function can be called with the reduced number of arguments (e.g. by using `*jobs*` or providing default arguments as shown above). + If a remainder is expected and valid, users should make sure that the operation function can be called with the reduced number of arguments (e.g. by using ``*jobs`` or providing default arguments as shown above). Sorting jobs for aggregation ---------------------------- From 5d64f3f8497ea8033483b663da91f503821d72a2 Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Fri, 25 Jun 2021 10:30:13 -0500 Subject: [PATCH 12/28] Update docs/source/aggregation.rst --- docs/source/aggregation.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index 2709a364..9b363468 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -50,9 +50,9 @@ Types of Aggregation Currently, **signac-flow** allows users to aggregate jobs in the following ways: -- _All jobs_: All of the project's jobs are passed to the operation function. -- _Group by state point key(s)_: The aggregates are grouped by one or more state point keys. -- _Group by arbitrary key-function_: The aggregates are grouped by keys determined by a key-function that expects an instance of :class:`~.signac.contrib.job.Job` and return the grouping key. +- *All jobs*: All of the project's jobs are passed to the operation function. +- *Group by state point key(s)*: The aggregates are grouped by one or more state point keys. +- *Group by arbitrary key function*: The aggregates are grouped by keys determined by a key-function that expects an instance of :class:`~.signac.contrib.job.Job` and return the grouping key. - Grouping into aggregates of a specific size. - Using a completely custom aggregator function when even greater flexibility is needed. From 76ec6d40c67ce6493fac834aac51369f70ebd23b Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Fri, 25 Jun 2021 10:31:16 -0500 Subject: [PATCH 13/28] Update docs/source/aggregation.rst --- docs/source/aggregation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index 9b363468..e6857bae 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -59,7 +59,7 @@ Currently, **signac-flow** allows users to aggregate jobs in the following ways: Group By -------- -:class:`~flow.aggregator.groupby` allows users to aggregate jobs by grouping them on state point key, an iterable of state point keys whose values define the groupings, or an arbitrary callable of :class:`~signac.contrib.job.Job`. +:class:`~flow.aggregator.groupby` allows users to aggregate jobs by grouping them by a state point key, an iterable of state point keys whose values define the groupings, or an arbitrary callable of :class:`~signac.contrib.job.Job`. .. code-block:: python From c82be52188f3a1129f42b525120ad8b7a9b1a39d Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Fri, 25 Jun 2021 10:31:52 -0500 Subject: [PATCH 14/28] Update docs/source/aggregation.rst --- docs/source/aggregation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index e6857bae..d78d5ce2 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -100,7 +100,7 @@ By default, when no ``sort_by`` parameter is specified, the order of the jobs wi .. code-block:: python - @aggregator.groupsof(2, sort_by='temperature', sort_ascending=False) + @aggregator.groupsof(2, sort_by="temperature", sort_ascending=False) @Project.operation def op5(*jobs): pass From 7ffd383a9e135051e2d128e49b344a563c1d1cb9 Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Fri, 25 Jun 2021 10:33:27 -0500 Subject: [PATCH 15/28] Update docs/source/aggregation.rst --- docs/source/aggregation.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index d78d5ce2..6ee43855 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -113,6 +113,7 @@ Selecting jobs for aggregation ------------------------------ **signac-flow** allows users to selectively choose which jobs to pass into operation functions. +This can be used to generate aggregates from only the selected jobs, excluding any jobs that do not meet the selection criteria. .. code-block:: python From 35cbf3baac5fe63ecfc3004e5ef999c4fee1934c Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Fri, 25 Jun 2021 10:34:26 -0500 Subject: [PATCH 16/28] Update docs/source/aggregation.rst --- docs/source/aggregation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index 6ee43855..4456a69d 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -165,7 +165,7 @@ By default, no aggregation takes place for a :py:class:`FlowGroup`. class Project(FlowProject): pass - group = Project.make_group('agg-group', group_aggregator=aggregator()) + group = Project.make_group("agg-group", group_aggregator=aggregator()) @group @aggregator() From c00bb86e02012fe4fd5806af174b08120784cf2f Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Fri, 25 Jun 2021 10:34:43 -0500 Subject: [PATCH 17/28] Update docs/source/aggregation.rst --- docs/source/aggregation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index 4456a69d..fe92caf6 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -178,7 +178,7 @@ By default, no aggregation takes place for a :py:class:`FlowGroup`. def op2(*jobs): pass - if __name__ == '__main__': + if __name__ == "__main__": Project().main() In the above example, when the group ``agg-group`` is executed using ``python project.py run -o agg-group``, all the jobs in the project are passed as positional arguments for both ``op1`` and ``op2``. From 49c31f22c831924202035b92ff13e54d827ce04f Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Fri, 25 Jun 2021 10:37:10 -0500 Subject: [PATCH 18/28] Update docs/source/aggregation.rst --- docs/source/aggregation.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index fe92caf6..ced21a90 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -182,4 +182,5 @@ By default, no aggregation takes place for a :py:class:`FlowGroup`. Project().main() In the above example, when the group ``agg-group`` is executed using ``python project.py run -o agg-group``, all the jobs in the project are passed as positional arguments for both ``op1`` and ``op2``. +If ``op1`` is executed using ``python project.py run -o op1``, all the jobs in the project are passed as positional arguments because a :class:`~flow.aggregator` is associated with the operation function ``op1`` (separately from the aggregator used for ``agg-group``). If ``op2`` is executed using ``python project.py run -o op2``, only a single job is passed as an argument because no :class:`~flow.aggregator` is associated with the operation function ``op2``. From 375b3cd746faaedd8b036fe85f7088fe6bdf8c68 Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Fri, 25 Jun 2021 10:37:40 -0500 Subject: [PATCH 19/28] Update docs/source/aggregation.rst --- docs/source/aggregation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index ced21a90..249a1f65 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -33,7 +33,7 @@ See also the Python documentation about :ref:`argument unpacking Date: Fri, 25 Jun 2021 10:47:14 -0500 Subject: [PATCH 20/28] Update docs/source/aggregation.rst --- docs/source/aggregation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index 249a1f65..78e44818 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -136,7 +136,7 @@ The aggregate id is sensitive to the order of the jobs in the aggregate. The id of an aggregate containing one job is that job's id. -In order to distinguish between aggregate id and a job id, for an aggregate of more than one job the aggregate id of that aggregate will always have a prefix ``agg-``. +In order to distinguish between an aggregate id and a job id, the id of aggregates with more than one job will always have a prefix ``agg-``. Users can generate the aggregate id of an aggregate using :meth:`flow.get_aggregate_id`. From 573eb104b97087a09ca71f56179616b6480f23c1 Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Fri, 25 Jun 2021 10:47:48 -0500 Subject: [PATCH 21/28] Update docs/source/aggregation.rst --- docs/source/aggregation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index 78e44818..ac31dd32 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -150,7 +150,7 @@ Users can generate the aggregate id of an aggregate using :meth:`flow.get_aggreg Aggregation with FlowGroups =========================== -In order to associate aggregator object with a :py:class:`FlowGroup`, **signac-flow** provides a ``group_aggregator`` parameter in :meth:`~flow.FlowProject.make_group`. +In order to associate an aggregator object with a :py:class:`FlowGroup`, **signac-flow** provides a ``group_aggregator`` parameter in :meth:`~flow.FlowProject.make_group`. By default, no aggregation takes place for a :py:class:`FlowGroup`. .. note:: From 16b1c97e95f45add8715d46c77d7d976c4bb9c2e Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Sat, 26 Jun 2021 10:42:30 -0500 Subject: [PATCH 22/28] Explain that operations are like aggregate operations acting on aggregates of one job. Co-authored-by: Carl Simon Adorf --- docs/source/aggregation.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index ac31dd32..4012f132 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -37,7 +37,12 @@ See also the Python documentation about :ref:`argument unpacking Date: Sat, 26 Jun 2021 13:50:38 -0500 Subject: [PATCH 23/28] Add aggregation to table of contents. --- docs/source/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/index.rst b/docs/source/index.rst index 41a3dbe4..9438a1e9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -48,6 +48,7 @@ If you are new to **signac**, the best place to start is to read the :ref:`intro environments templates flow-group + aggregation indexing collections configuration From d16f43a61165e379a105f191732d1c9ddf79e24a Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Sat, 26 Jun 2021 13:52:37 -0500 Subject: [PATCH 24/28] Rename section to match FlowGroup. --- docs/source/aggregation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index 4012f132..29227a92 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -9,7 +9,7 @@ This chapter provides information about passing aggregates of jobs to operation .. _aggregator_definition: -aggregator +Definition ========== An :class:`~flow.aggregator` is used as a decorator for operation functions which accept a variable number of positional arguments, ``*jobs``. From 9cd9995e932bb26f5b231ace590a199a972cd138 Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Sat, 26 Jun 2021 13:53:33 -0500 Subject: [PATCH 25/28] Unitalicize. --- docs/source/aggregation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index 29227a92..a154ff13 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -41,7 +41,7 @@ In the example above, ``op1`` is an *aggregate operation* where all the jobs pre .. tip:: - The concept of aggregation may be easier to understand if one realizes that "normal" operation functions are equivalent to *aggregate operation* functions with an aggregate group size of one job. + The concept of aggregation may be easier to understand if one realizes that "normal" operation functions are equivalent to aggregate operation functions with an aggregate group size of one job. .. note:: From 23576c60d1233d278a3fe9ea629f1137b27fb75a Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Sat, 26 Jun 2021 13:55:49 -0500 Subject: [PATCH 26/28] Fix links to pre/post. --- docs/source/aggregation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index a154ff13..b2094f2d 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -46,7 +46,7 @@ In the example above, ``op1`` is an *aggregate operation* where all the jobs pre .. note:: - For an aggregate operation, all conditions like :class:`~flow.FlowProject.pre` or :class:`~flow.FlowProject.post`, callable directives, and other features are required to take the same number of jobs as the operation as arguments. + For an aggregate operation, all conditions like :py:func:`~flow.FlowProject.pre` or :py:func:`~flow.FlowProject.post`, callable directives, and other features are required to take the same number of jobs as the operation as arguments. .. _types_of_aggregation: From abd7544c5f3f51a90763bbc2874bd280ac470db9 Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Sat, 26 Jun 2021 14:01:02 -0500 Subject: [PATCH 27/28] Fix intersphinx references. --- docs/source/aggregation.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index b2094f2d..e0a7c9dc 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -46,7 +46,7 @@ In the example above, ``op1`` is an *aggregate operation* where all the jobs pre .. note:: - For an aggregate operation, all conditions like :py:func:`~flow.FlowProject.pre` or :py:func:`~flow.FlowProject.post`, callable directives, and other features are required to take the same number of jobs as the operation as arguments. + For an aggregate operation, all conditions like :func:`~flow.FlowProject.pre` or :func:`~flow.FlowProject.post`, callable directives, and other features are required to take the same number of jobs as the operation as arguments. .. _types_of_aggregation: @@ -64,7 +64,7 @@ Currently, **signac-flow** allows users to aggregate jobs in the following ways: Group By -------- -:class:`~flow.aggregator.groupby` allows users to aggregate jobs by grouping them by a state point key, an iterable of state point keys whose values define the groupings, or an arbitrary callable of :class:`~signac.contrib.job.Job`. +:meth:`~flow.aggregator.groupby` allows users to aggregate jobs by grouping them by a state point key, an iterable of state point keys whose values define the groupings, or an arbitrary callable of :class:`~signac.contrib.job.Job`. .. code-block:: python @@ -79,7 +79,7 @@ So, all the jobs having the same value of **temperature** in their state point w Groups Of --------- -:class:`~flow.aggregator.groupsof` allows users to aggregate jobs by generating aggregates of a given size. +:meth:`~flow.aggregator.groupsof` allows users to aggregate jobs by generating aggregates of a given size. .. code-block:: python @@ -93,7 +93,7 @@ In the above example, the jobs will get aggregated in groups of 2 and hence, up .. note:: In case the number of jobs in the project in this example is odd, there will be one aggregate containing only a single job. - In general, the last aggregate from :class:`~flow.aggregator.groupsof` will contain the remaining jobs if the aggregate size does not evenly divide the number of jobs in the project. + In general, the last aggregate from :meth:`~flow.aggregator.groupsof` will contain the remaining jobs if the aggregate size does not evenly divide the number of jobs in the project. If a remainder is expected and valid, users should make sure that the operation function can be called with the reduced number of arguments (e.g. by using ``*jobs`` or providing default arguments as shown above). Sorting jobs for aggregation @@ -143,11 +143,11 @@ The aggregate id is sensitive to the order of the jobs in the aggregate. In order to distinguish between an aggregate id and a job id, the id of aggregates with more than one job will always have a prefix ``agg-``. -Users can generate the aggregate id of an aggregate using :meth:`flow.get_aggregate_id`. +Users can generate the aggregate id of an aggregate using :func:`flow.get_aggregate_id`. .. tip:: - Users can also pass an aggregate id to the ``--job-id`` command-line flag provided by **signac-flow** in ``run``, ``submit``, and ``exec``. + Users can also pass an aggregate id to the ``--job-id`` command line flag provided by **signac-flow** in ``run``, ``submit``, and ``exec``. .. _aggregation_with_flow_groups: @@ -155,12 +155,12 @@ Users can generate the aggregate id of an aggregate using :meth:`flow.get_aggreg Aggregation with FlowGroups =========================== -In order to associate an aggregator object with a :py:class:`FlowGroup`, **signac-flow** provides a ``group_aggregator`` parameter in :meth:`~flow.FlowProject.make_group`. -By default, no aggregation takes place for a :py:class:`FlowGroup`. +In order to associate an aggregator object with a :class:`~flow.project.FlowGroup`, **signac-flow** provides a ``group_aggregator`` parameter in :meth:`~flow.FlowProject.make_group`. +By default, no aggregation takes place for a :class:`FlowGroup`. .. note:: - All the operations in a :py:class:`FlowGroup` will use the same :class:`~flow.aggregator` object provided to the group's ``group_aggregator`` parameter. + All the operations in a :class:`~flow.project.FlowGroup` will use the same :class:`~flow.aggregator` object provided to the group's ``group_aggregator`` parameter. .. code-block:: python From aca675248d6486053f3a7840af8ae98c5e64b507 Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Sat, 26 Jun 2021 14:05:12 -0500 Subject: [PATCH 28/28] Use :py: role prefix for consistency with other docs. --- docs/source/aggregation.rst | 26 +++++++++++++------------- docs/source/flow-project.rst | 2 +- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/source/aggregation.rst b/docs/source/aggregation.rst index e0a7c9dc..00c66f20 100644 --- a/docs/source/aggregation.rst +++ b/docs/source/aggregation.rst @@ -12,7 +12,7 @@ This chapter provides information about passing aggregates of jobs to operation Definition ========== -An :class:`~flow.aggregator` is used as a decorator for operation functions which accept a variable number of positional arguments, ``*jobs``. +An :py:class:`~flow.aggregator` is used as a decorator for operation functions which accept a variable number of positional arguments, ``*jobs``. The argument ``*jobs`` is unpacked into an *aggregate*, defined as an ordered tuple of jobs. See also the Python documentation about :ref:`argument unpacking `. @@ -36,7 +36,7 @@ See also the Python documentation about :ref:`argument unpacking