edc-timepoint

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

edc-timepoint

Lock a "timepoint" from further editing once data is cleaned and reviewed.

With module edc_timepoint a data manager or supervisor is able to flag a model instance, that represents a timepoint, as closed to further edit. A good candidate for a "timepoint" model is one that is used to cover other data collection, such as an edc_appointment.Appointment. When the appointment status is set to something like 'complete' the timepoint status is set to closed and no further edits are allowed for data covered by that appointment.

Configuring the Timepoint Model

Select a model that represent a timepoint. The model should at least have a `datetime` field and a `status` field. For example `Appointment`:


.. code-block:: python

    class Appointment(TimepointModelMixin, BaseUuidModel):

        appt_datetime = models.DateTimeField(
            verbose_name='Appointment date and time')

        appt_status = models.CharField(
            verbose_name='Status',
            choices=APPT_STATUS,
            max_length=25,
            default='NEW')

The ``TimepointModelMixin`` adds fields and methods prefixed as ``timepoint_<something>``. There is also a signal that is loaded in the ``AppConfig.ready`` that resets the timepoint attributes should ``Appointment.appt_status`` change from ``DONE``.

Only field ``timepoint_status`` is meant to be edited by the user. The other ``timepoint_<something>`` are managed automatically.

In your projects ``apps.py`` subclass ``edc_timepoint.apps.AppConfig`` and declare ``Appointment`` as a timepoint model by creating a ``Timepoint`` instance and appending it to ``AppConfig.timepoints``:

.. code-block:: python

    from django.apps import AppConfig as DjangoAppConfig

    from edc_timepoint.apps import AppConfig as EdcTimepointAppConfigParent
    from edc_timepoint.timepoint import Timepoint


    class AppConfig(DjangoAppConfig):
        name = 'example'

    class EdcTimepointAppConfig(EdcTimepointAppConfigParent):
        timepoints = TimepointCollection(
            timepoints=[Timepoint(
                model='example.appointment',
                datetime_field='appt_datetime',
                status_field='appt_status',
                closed_status='DONE')])

The user updates the ``Appointment`` normally closing it when the appointment is done. Then a data manager or supervisor can close the ``Appointment`` to further edit once the data has been reviewed.

To close the ``Appointment`` to further edit the code needs to call the ``timepoint_close_timepoint`` method:

.. code-block:: python

    appointment = Appointment.objects.create(**options)
    appointment.appt_status = 'DONE'
    appointment.timepoint_close_timepoint()

If the ``appointment.appt_status`` is not ``DONE`` when ``timepoint_close_timepoint`` is called, a ``TimepointError`` is raised.

If the appointment is successfully closed to further edit, any attempts to call ``appointment.save()`` will raise a ``TimepointError``.

The ``Appointment`` may be re-opened for edit by calling method ``timepoint_open_timepoint``.

Configuring others to use the Timepoint Model

Continuing with the example above where Appointment is the timepoint model.

To prevent further edits to models related to Appointment, configure the model with the TimepointLookupModelMixin and the TimepointLookup class. These models will refer to the timepoint model on save.

For example:

.. code-block:: python

class VisitTimepointLookup(TimepointLookup):
    timepoint_related_model_lookup = 'appointment'

class VisitModel(TimepointLookupModelMixin, BaseUuidModel):

    timepoint_lookup_cls = VisitTimepointLookup

    appointment = models.ForeignKey(Appointment)

    report_datetime = models.DateTimeField(
        default=timezone.now)

If the timepoint model's timepoint_status is closed, any attempt to create or modify VisitModel will raise a TimepointClosed exception.

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

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

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

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