Metadata-Version: 2.1
Name: edc-randomization
Version: 0.3.52
Summary: Randomization classes for clinicedc/edc
Home-page: https://github.com/clinicedc/edc-randomization
Author: Erik van Widenfelt
Author-email: ew2789@gmail.com
License: GPL license, see LICENSE
Keywords: django Edc randomization,clinicedc,clinical trials
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS

|pypi| |actions| |codecov| |downloads|

edc-randomization
=================

Randomization objects for clinicedc projects

Overview
++++++++

The ``Randomizer`` class emulates the randomization of a clincial trial participant in
realtime. This module doesn't actually `randomize` in realtime. Instead, a CSV file is
prepared in advance by the statistician. This CSV file lists the order in which subjects
are to be randomized. The ``Randomizer`` class initially imports the entire list in order
into a ``model``. When a subject is to be randomized, the ``Randomizer`` class selects
the next available row from the model.

A very basic ``randomization_list.csv`` prepared in advance might look like this::

    site_name,sid,assignment
    temeke,1000,active
    temeke,1001,active
    temeke,1002,placebo
    temeke,1003,active
    temeke,1004,placebo
    temeke,1005,placebo
    ...

For large multisite trials this may be thousands of lines ordered using some type of block
randomization.

This module will import (only once) all rows from the CSV file into a model. The ``Randomizer``
class selects and allocates in order by site_name one row per participant from the model.

.. code-block:: python

    randomizer_cls = site_randomizers.get("default")
    randomizer_cls.randomize(subject_identifier=subject_identifier, ...)
    # or just:
    site_randomizers.randomize("default", subject_identifier=subject_identifier, ...)

Usually, the ``Randomizer`` class is instantiated in a ``signal`` once the subject's
eligibility is confirmed and the subject's informed consent is submitted. A
`signal` attached to the subject's informed consent is a good place to do this assuming the sequence
of events are 1) pass eligibility criteria, 2) complete informed consent, 3) `randomize` and
issue study identifier 4) start baseline visit.

.. code-block:: python

    @receiver(
        post_save,
        weak=False,
        sender=SubjectConsent,
        dispatch_uid="subject_consent_on_post_save",
    )
    def subject_consent_on_post_save(sender, instance, raw, created, **kwargs):
        if not raw:
            if created:
                ...
                # randomize
                site_randomizers.randomize(
                    "default",
                    subject_identifier=instance.subject_identifier,
                    report_datetime=instance.consent_datetime,
                    site=instance.site,
                    user=instance.user_created,
                )
                ...


Registering a randomizer
++++++++++++++++++++++++
The default ``Randomizer`` class is ``edc_randomization.randomizer.Randomizer``. Unless you
indicate otherwise, it will be automatically registered with the site controller,
``site_randomizers`` with the name ``default``. It is recommended you access the ``Randomizer``
class through ``site_randomizers`` instead of directly importing.

.. code-block:: python

    randomizer_cls = site_randomizers.get("default")


Customizing the default randomizer
++++++++++++++++++++++++++++++++++

Some attributes of the default ``Randomizer`` class can be customized using ``settings`` attributes:

.. code-block:: python

    EDC_RANDOMIZATION_LIST_PATH = 'path/to/csv_file'
    EDC_RANDOMIZATION_ASSIGNMENT_MAP = {
        "intervention": 1,
        "control": 2,
        }
    EDC_RANDOMIZATION_ASSIGNMENT_DESCRIPTION_MAP = {
        "intervention": "Fluconazole plus flucytosine",
        "control": "Fluconazole"
        }

Creating a custom randomizer
++++++++++++++++++++++++++++

If you need to customize further, create a custom ``Randomizer`` class.

In the example below, ``gender`` is added for a trial stratified by ``gender``.

Custom ``Randomizer`` classes live in ``randomizers.py`` in the root of your app. The
``site_randomizers`` controller will ``autodiscover`` them.

.. code-block:: python

    # my_app/randomizers.py

    @register()
    class MyRandomizer(Randomizer):
        name = "my_randomizer"
        model = "edc_randomization.myrandomizationlist"
        randomization_list_path = tmpdir
        assignment_map = {"Intervention": 1, "Control": 0}
        assignment_description_map = {"Intervention": "Fluconazole plus flucytosine", "Control": "Fluconazole"}
        extra_csv_fieldnames = ["gender"]

        def __init__(self, gender=None, **kwargs):
            self.gender = gender
            super().__init__(**kwargs)

        @property
        def extra_required_instance_attrs(self):
            return dict(gender=self.gender)

        @property
        def extra_model_obj_options(self):
            return dict(gender=self.gender)

        @classmethod
        def get_extra_list_display(cls):
            return [(4, "gender")]


The ``register()`` decorator registers the custom class with ``site_randomizers``.

With a custom randomizer, the default ``Randomizer`` class is no longer needed,
update settings to prevent the default class from registering.

Use the settings attribute:

.. code-block:: python

    EDC_RANDOMIZATION_REGISTER_DEFAULT_RANDOMIZER = False

Confirm this by checking the ``site_randomizers``:

.. code-block:: python

    >>> randomizer_cls = site_randomizers.get("default")
    NotRegistered: A Randomizer class by this name ...

    >>> randomizer_cls = site_randomizers.get("my_randomizer")
    >>> randomizer_cls.name
    "my_randomizer"


Manually Importing from CSV
+++++++++++++++++++++++++++
A ``Randomizer`` class will call ``import_list`` when it is instantiated
for the first time. If you want to load the CSV file manually,
import the ``Randomizer`` class and call ``import_list()``.


.. code-block:: python

   >>> randomizer_cls = site_randomizers.get("my_randomizer")
   >>> randomizer_cls.import_list()
   Import CSV data
     Randomizer:
       -  Name: my_randomizer
       -  Assignments: {'active': 1, 'placebo': 2}
       -  Model: edc_randomization.myrandomizationlist
       -  Path: /home/me/.etc/randomization_list.csv
       -  Imported 5 SIDs for randomizer `my_randomizer` into model `edc_randomization.myrandomizationlist`
          from /home/me/.etc/randomization_list.csv.
       -  Verified OK.


Manually Export to CSV
++++++++++++++++++++++

.. code-block:: python

    >>> from edc_randomization.utils import export_randomization_list
    >>> export_randomization_list(randomizer_name="default",path="~/", username="erikvw")

If the user does not have permissions to view the randomizationlist table, a ``RandomizationListExporterError`` will be raised:

.. code-block:: python

    RandomizationListExporterError: User `erikvw` does not have permission to view 'edc_randomization.randomizationlist'


.. |pypi| image:: https://img.shields.io/pypi/v/edc-randomization.svg
    :target: https://pypi.python.org/pypi/edc-randomization

.. |actions| image:: https://github.com/clinicedc/edc-randomization/actions/workflows/build.yml/badge.svg
  :target: https://github.com/clinicedc/edc-randomization/actions/workflows/build.yml

.. |codecov| image:: https://codecov.io/gh/clinicedc/edc-randomization/branch/develop/graph/badge.svg
  :target: https://codecov.io/gh/clinicedc/edc-randomization

.. |downloads| image:: https://pepy.tech/badge/edc-randomization
   :target: https://pepy.tech/project/edc-randomization
