Metadata-Version: 2.2
Name: edc-facility
Version: 1.0.2
Summary: Define clinic facilities for clinicedc/edc projects
Home-page: https://github.com/clinicedc/edc-facility
Author: Erik van Widenfelt
Author-email: ew2789@gmail.com
License: GPL license, see LICENSE
Keywords: django Edc clinic facility clinicedc,clinical trials
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.1
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Requires-Python: >=3.12
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS
Requires-Dist: arrow

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


edc-facility
------------

Loading holidays
++++++++++++++++

To load the list of holidays into the system:

.. code-block:: python

    python manage.py import_holidays


Customizing appointment scheduling by ``Facility``
++++++++++++++++++++++++++++++++++++++++++++++++++

Appointment scheduling can be customized per ``facility`` or clinic:

Add each facility to ``app_config.facilities`` specifying the facility ``name``, ``days`` open and the maximum number of ``slots`` available per day:

.. code-block:: python

    from edc_facility.apps import AppConfig as EdcAppointmentAppConfig

    class AppConfig(EdcAppointmentAppConfig):

        facilities = {
            'clinic1': Facility(name='clinic', days=[MO, TU, WE, TH, FR], slots=[100, 100, 100, 100, 100])}
            'clinic2': Facility(name='clinic', days=[MO, WE, FR], slots=[30, 30, 30])}

To schedule an appointment that falls on a day that the clinic is open, isn't a holiday and isn't already over-booked:

.. code-block:: python

    from edc_utils import get_utcnow
    from .facility import Facility

    suggested_datetime = get_utcnow()
    available_datetime = facility.available_datetime(suggested_datetime)


If holidays are entered (in model ``Holiday``) and the appointment lands on a holiday, the appointment date is incremented forward to an allowed weekday. Assuming ``facility`` is configured in ``app_config`` to only schedule appointments on [TU, TH]:

.. code-block:: python

    from datetime import datetime
    from dateutil.relativedelta import TU, TH
    from django.conf import settings
    from django.utils import timezone
    from zoneifo import ZoneInfo

    from .facility import Facility
    from .models import Holiday

    Holiday.objects.create(
        name='Id-ul-Adha (Feast of the Sacrifice)',
        date=date(2015, 9, 24)
    )
    suggested_datetime = datetime(2015, 9, 24, tzinfo=ZoneInfo("UTC"))  # TH
    available_datetime = facility.available_datetime(suggested_datetime)
    print(available_datetime)  # 2015-09-29 00:00:00, TU

The maximum number of possible scheduling slots per day is configured in ``app_config``. As with the holiday example above, the appointment date will be incremented forward to a day with an available slot.


System checks
+++++++++++++
* ``edc_facility.001`` Holiday file not set! settings.HOLIDAY_FILE not defined.
* ``edc_facility.002`` Holiday file not found.
* ``edc_facility.003`` Holiday table is empty. Run management command 'import_holidays'.
* ``edc_facility.004`` No Holidays have been defined for this country.


HealthFacility model
++++++++++++++++++++

The ``HealthFacility`` model is used by ``edc-next-appointment`` when reporting the next routine
appointment for a participant. This is important for trials that collect data at routine clinic appointments
not set by the research staff or defined by the protocol.

See also ``edc-next-appointment``.

If you need to customize the model, declare the concrete model locally in your app. You can use the mixins to build
your own classes.

You'll also need to update ``settings`` to tell ``edc_facility`` where the custom model is::

    EDC_FACILITY_HEALTH_FACILITY_MODEL = "myapp.healthfacility"


For example:

.. code-block:: python

    # models.py
    class HealthFacility(SiteModelMixin, HealthFacilityModelMixin, BaseUuidModel):

        objects = Manager()
        on_site = CurrentSiteManager()
        history = HistoricalRecords()

        class Meta(SiteModelMixin.Meta, BaseUuidModel.Meta):
            verbose_name = "Health Facility"
            verbose_name_plural = "Health Facilities"

.. code-block:: python

    # forms.py
    class HealthFacilityForm(FormValidatorMixin, forms.ModelForm):
        form_validator_cls = HealthFacilityFormValidator

        class Meta:
            model = HealthFacility
            fields = "__all__"

.. code-block:: python

    # admin.py
    @admin.register(HealthFacility, site=intecomm_facility_admin)
    class HealthFacilityAdmin(
        HealthFacilityModelAdminMixin,
        SiteModelAdminMixin,
        BaseModelAdminMixin,
    ):
        form = HealthFacilityForm

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

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

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

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