ebird-api-data 0.1.0__py3-none-any.whl

ebird/api/data/models/__init__.py

@@ -0,0 +1,21 @@
+from .checklist import Checklist
+from .country import Country
+from .county import County
+from .filter import Filter
+from .location import Location
+from .observation import Observation
+from .observer import Observer
+from .species import Species
+from .state import State
+
+__all__ = (
+    "Checklist",
+    "Country",
+    "County",
+    "Filter",
+    "Location",
+    "Observation",
+    "Observer",
+    "Species",
+    "State",
+)

ebird/api/data/models/checklist.py

@@ -0,0 +1,178 @@
+from django.db import models
+from django.utils.translation import gettext_lazy as _
+
+
+class Checklist(models.Model):
+    class Meta:
+        verbose_name = _("checklist")
+        verbose_name_plural = _("checklists")
+
+    created = models.DateTimeField(
+        blank=True,
+        null=True,
+        help_text=_("The date and time the checklist was added to eBird."),
+        verbose_name=_("created"),
+    )
+
+    edited = models.DateTimeField(
+        blank=True,
+        null=True,
+        help_text=_("The date and time the eBird checklist was last edited."),
+        verbose_name=_("edited"),
+    )
+
+    published = models.BooleanField(
+        help_text=_("Is the checklist published?"),
+        verbose_name=_("published"),
+    )
+
+    identifier = models.TextField(
+        unique=True,
+        verbose_name=_("identifier"),
+        help_text=_("The unique identifier for the checklist."),
+    )
+
+    country = models.ForeignKey(
+        "data.Country",
+        related_name="checklists",
+        on_delete=models.PROTECT,
+        verbose_name=_("country"),
+        help_text=_("The country where the checklist was made."),
+    )
+
+    state = models.ForeignKey(
+        "data.State",
+        related_name="checklists",
+        on_delete=models.PROTECT,
+        verbose_name=_("state"),
+        help_text=_("The state where the checklist was made."),
+    )
+
+    county = models.ForeignKey(
+        "data.County",
+        blank=True,
+        null=True,
+        related_name="checklists",
+        on_delete=models.PROTECT,
+        verbose_name=_("county"),
+        help_text=_("The county where the checklist was made."),
+    )
+
+    location = models.ForeignKey(
+        "data.Location",
+        related_name="checklists",
+        on_delete=models.PROTECT,
+        verbose_name=_("location"),
+        help_text=_("The location where checklist was made."),
+    )
+
+    observer = models.ForeignKey(
+        "data.Observer",
+        related_name="checklists",
+        on_delete=models.PROTECT,
+        verbose_name=_("observer"),
+        help_text=_("The person who submitted the checklist."),
+    )
+
+    observer_count = models.IntegerField(
+        blank=True,
+        null=True,
+        verbose_name=_("observer count"),
+        help_text=_("The total number of observers."),
+    )
+
+    species_count = models.IntegerField(
+        blank=True,
+        null=True,
+        verbose_name=_("species count"),
+        help_text=_("The number of species reported."),
+    )
+
+    date = models.DateField(
+        db_index=True,
+        verbose_name=_("date"),
+        help_text=_("The date the checklist was started."),
+    )
+
+    time = models.TimeField(
+        blank=True,
+        null=True,
+        verbose_name=_("time"),
+        help_text=_("The time the checklist was started."),
+    )
+
+    started = models.DateTimeField(
+        blank=True,
+        db_index=True,
+        null=True,
+        verbose_name=_("date & time"),
+        help_text=_("The date and time the checklist was started."),
+    )
+
+    protocol_code = models.TextField(
+        blank=True,
+        verbose_name=_("protocol code"),
+        help_text=_("The code used to identify the protocol."),
+    )
+
+    project_code = models.TextField(
+        blank=True,
+        verbose_name=_("project code"),
+        help_text=_("The code used to identify the project (portal)."),
+    )
+
+    duration = models.IntegerField(
+        blank=True,
+        null=True,
+        verbose_name=_("duration"),
+        help_text=_("The number of minutes spent counting."),
+    )
+
+    distance = models.DecimalField(
+        blank=True,
+        null=True,
+        decimal_places=3,
+        max_digits=6,
+        verbose_name=_("distance"),
+        help_text=_("The distance, in metres, covered while travelling."),
+    )
+
+    area = models.DecimalField(
+        blank=True,
+        null=True,
+        decimal_places=3,
+        max_digits=6,
+        verbose_name=_("area"),
+        help_text=_("The area covered, in hectares."),
+    )
+
+    complete = models.BooleanField(
+        default=False,
+        verbose_name=_("complete"),
+        help_text=_("All species seen are reported."),
+    )
+
+    comments = models.TextField(
+        blank=True,
+        verbose_name=_("comments"),
+        help_text=_("Any comments about the checklist."),
+    )
+
+    url = models.URLField(
+        blank=True,
+        verbose_name=_("url"),
+        help_text=_("URL where the original checklist can be viewed."),
+    )
+
+    data = models.JSONField(
+        verbose_name=_("Data"),
+        help_text=_("Data describing a Checklist."),
+        default=dict,
+        blank=True,
+    )
+
+    def __repr__(self) -> str:
+        return str(self.identifier)
+
+    def __str__(self) -> str:
+        return str(self.identifier)

ebird/api/data/models/country.py

@@ -0,0 +1,29 @@
+from django.db import models
+from django.utils.translation import gettext_lazy as _
+
+
+class Country(models.Model):
+    class Meta:
+        verbose_name = _("country")
+        verbose_name_plural = _("countries")
+
+    code = models.CharField(
+        max_length=2,
+        db_index=True,
+        verbose_name=_("code"),
+        help_text=_("The code used to identify the country."),
+    )
+
+    name = models.TextField(
+        verbose_name=_("name"), help_text=_("The name of the country.")
+    )
+
+    place = models.TextField(
+        verbose_name=_("place"), help_text=_("The hierarchical name of the country.")
+    )
+
+    def __repr__(self) -> str:
+        return str(self.code)
+
+    def __str__(self) -> str:
+        return str(self.name)

ebird/api/data/models/county.py

@@ -0,0 +1,29 @@
+from django.db import models
+from django.utils.translation import gettext_lazy as _
+
+
+class County(models.Model):
+    class Meta:
+        verbose_name = _("county")
+        verbose_name_plural = _("counties")
+
+    code = models.CharField(
+        max_length=10,
+        db_index=True,
+        verbose_name=_("code"),
+        help_text=_("The code used to identify the county."),
+    )
+
+    name = models.TextField(
+        verbose_name=_("name"), help_text=_("The name of the county.")
+    )
+
+    place = models.TextField(
+        verbose_name=_("place"), help_text=_("The hierarchical name of the county.")
+    )
+
+    def __repr__(self) -> str:
+        return str(self.code)
+
+    def __str__(self) -> str:
+        return str(self.name)

ebird/api/data/models/filter.py

@@ -0,0 +1,71 @@
+import logging
+
+from django.db import models
+from django.utils.translation import gettext_lazy as _
+
+from .observation import Observation
+
+log = logging.getLogger(__name__)
+
+
+class Filter(models.Model):
+    class Meta:
+        verbose_name = _("filter")
+        verbose_name_plural = _("filters")
+
+    enabled = models.BooleanField(
+        help_text=_("Is the filter active?"),
+        verbose_name=_("enabled"),
+    )
+
+    name = models.TextField(
+        verbose_name=_("name"), help_text=_("The name of the filter.")
+    )
+
+    species = models.ForeignKey(
+        "data.Species",
+        related_name="filtered_on",
+        on_delete=models.CASCADE,
+        verbose_name=_("species"),
+        help_text=_("The species used to find matching Observations."),
+    )
+
+    location = models.ForeignKey(
+        "data.Location",
+        blank=True,
+        null=True,
+        related_name="filtered_on",
+        on_delete=models.CASCADE,
+        verbose_name=_("location"),
+        help_text=_("The location used to find matching Observations."),
+    )
+
+    update_species = models.ForeignKey(
+        "data.Species",
+        related_name="filtered_by",
+        on_delete=models.CASCADE,
+        verbose_name=_("update species"),
+        help_text=_("Matching Observations are updated to this species."),
+    )
+
+    def __repr__(self) -> str:
+        return str(self.name)
+
+    def __str__(self) -> str:
+        return str(self.name)
+
+    def apply(self):
+        count = 0
+        filters = models.Q()
+
+        if self.species:
+            filters &= models.Q(species=self.species)
+        if self.location:
+            filters &= models.Q(location=self.location)
+
+        for observation in Observation.objects.filter(filters):
+            observation.species = self.update_species
+            observation.save()
+            count += 1
+
+        return count

ebird/api/data/models/location.py

@@ -0,0 +1,153 @@
+from django.db import models
+from django.utils.translation import gettext_lazy as _
+
+
+class Location(models.Model):
+    """
+    Location defines the location where the observations in a Checklist
+    were made.
+
+    Design Notes
+    ------------
+    Rather than use country, subnational1 and subnational2 from the eBird API,
+    the names country, state and county from the eBird Basic Dataset were used.
+    Originally the models were designed so data from either source could be
+    loaded, but since the schemas did not overlap completely that meant quite
+    a few fields were optional. This dual-purpose role was discarded and the
+    models were changed to specifically support the eBird API. The names, state
+    and county were kept because they were shorter, and it was easier to remember
+    the order.
+
+    The hierarchy: country, state, country describes the administrative, but not
+    the geographical/ecological organisation. Being able to identify groups of
+    related locations in a national park or Important Bird Areas, or groups of
+    counties or states is useful to find out what has been seen in a given area.
+    Additional models for Area, Island and Region were considered but ultimately
+    rejected for three main reasons:
+
+    1. For hotspots it is easy to map locations to an Area or Island, however
+       about 40% of all locations (for Portugal) are personal or private, even
+       when the hotspot is well known, or should have been well known. Unless
+       these were ignored, that would mean an on-going effort to add these
+       locations to the relevant groups. For even a small country or area the
+       effort is enormous. Autocorrecting location should be possible but that
+       would mean defining boundaries for each hotspot. There was talk of eBird
+       doing that but again the effort would be enormous.
+
+    2. If the hierarchy is extended to add new levels, then the codes used by
+       eBird, US, US-NY, US-NY-109 would need to be changed to incorporate
+       the new levels, since it makes finding related locations easy. The
+       alternative is to create the hierarchy using foreign keys. Again that
+       create a considerable administrative burden.
+
+    3. Grouping locations, countries, or states is mainly for usability,
+       however for small numbers of each, adding form controls that support
+       multi-select can be used as a workaround / viable alternative, and
+       even provide more flexibility.
+
+    On the second point, it might be worth adopting an alternative hierarchy
+    such as the NUTS3 system used in the European Union, which has an extra
+    level. It also uses hierarchical codes, e.g. PT1, PT15, PT15D. Counties
+    are the smallest areas, and are shared by both systems, so it is easy to
+    map eBird codes to NUTS codes.
+
+    Optimisations
+    -------------
+    A Checklist has a Location, but the hierarchy was flattened so the County,
+    State and Country are duplicated on the Checklist model to reduce the
+    number of joins, and so speed up queries. Similarly, Location, County, State,
+    and Country are duplicated on Observation for the same reason.
+
+    """
+
+    class Meta:
+        verbose_name = _("location")
+        verbose_name_plural = _("locations")
+
+    identifier = models.TextField(
+        unique=True,
+        verbose_name=_("identifier"),
+        help_text=_("The unique identifier for the location."),
+    )
+
+    original = models.TextField(
+        verbose_name=_("original name"),
+        help_text=_("The original name of the location from eBird."),
+    )
+
+    name = models.TextField(
+        verbose_name=_("name"),
+        help_text=_("The display name of the location."),
+    )
+
+    country = models.ForeignKey(
+        "data.Country",
+        related_name="locations",
+        on_delete=models.PROTECT,
+        verbose_name=_("country"),
+        help_text=_("The country for the location."),
+    )
+
+    state = models.ForeignKey(
+        "data.State",
+        related_name="locations",
+        on_delete=models.PROTECT,
+        verbose_name=_("state"),
+        help_text=_("The state for the location."),
+    )
+
+    county = models.ForeignKey(
+        "data.County",
+        blank=True,
+        null=True,
+        related_name="locations",
+        on_delete=models.PROTECT,
+        verbose_name=_("county"),
+        help_text=_("The county for the location."),
+    )
+
+    latitude = models.DecimalField(
+        blank=True,
+        null=True,
+        decimal_places=7,
+        max_digits=9,
+        verbose_name=_("latitude"),
+        help_text=_("The decimal latitude of the location, relative to the equator."),
+    )
+
+    longitude = models.DecimalField(
+        blank=True,
+        null=True,
+        decimal_places=7,
+        max_digits=10,
+        verbose_name=_("longitude"),
+        help_text=_(
+            "The decimal longitude of the location, relative to the prime meridian."
+        ),
+    )
+
+    url = models.URLField(
+        blank=True,
+        verbose_name=_("url"),
+        help_text=_("URL of the location page on eBird."),
+    )
+
+    hotspot = models.BooleanField(
+        blank=True,
+        null=True,
+        verbose_name=_("is hotspot"),
+        help_text=_("Is the location a hotspot."),
+    )
+
+    data = models.JSONField(
+        verbose_name=_("Data"),
+        help_text=_("Data describing a Location."),
+        default=dict,
+        blank=True,
+    )
+
+    def __repr__(self) -> str:
+        return str(self.identifier)
+
+    def __str__(self) -> str:
+        return self.name

ebird/api/data/models/observation.py

@@ -0,0 +1,189 @@
+import json
+import logging
+
+from json import JSONDecodeError
+
+from django.core.validators import MinValueValidator
+from django.db import models
+from django.utils.translation import get_language
+from django.utils.translation import gettext_lazy as _
+
+log = logging.getLogger(__name__)
+
+
+class Observation(models.Model):
+    class Meta:
+        verbose_name = _("observation")
+        verbose_name_plural = _("observations")
+
+    edited = models.DateTimeField(
+        blank=True,
+        null=True,
+        help_text=_("The date and time the eBird checklist was last edited."),
+        verbose_name=_("edited"),
+    )
+
+    published = models.BooleanField(
+        help_text=_("Is the observation published?"),
+        verbose_name=_("published"),
+    )
+
+    identifier = models.TextField(
+        unique=True,
+        verbose_name=_("identifier"),
+        help_text=_("A global unique identifier for the observation."),
+    )
+
+    checklist = models.ForeignKey(
+        "data.Checklist",
+        related_name="observations",
+        on_delete=models.CASCADE,
+        verbose_name=_("checklist"),
+        help_text=_("The checklist this observation belongs to."),
+    )
+
+    species = models.ForeignKey(
+        "data.Species",
+        related_name="observations",
+        on_delete=models.PROTECT,
+        verbose_name=_("species"),
+        help_text=_("The identified species."),
+    )
+
+    observer = models.ForeignKey(
+        "data.Observer",
+        related_name="observations",
+        on_delete=models.PROTECT,
+        verbose_name=_("observer"),
+        help_text=_("The person who made the observation."),
+    )
+
+    country = models.ForeignKey(
+        "data.Country",
+        related_name="observations",
+        on_delete=models.PROTECT,
+        verbose_name=_("country"),
+        help_text=_("The country where the observation was made."),
+    )
+
+    state = models.ForeignKey(
+        "data.State",
+        related_name="observations",
+        on_delete=models.PROTECT,
+        verbose_name=_("state"),
+        help_text=_("The state where the observation was made."),
+    )
+
+    county = models.ForeignKey(
+        "data.County",
+        blank=True,
+        null=True,
+        related_name="observations",
+        on_delete=models.PROTECT,
+        verbose_name=_("county"),
+        help_text=_("The county where the observation was made."),
+    )
+
+    location = models.ForeignKey(
+        "data.Location",
+        related_name="observations",
+        on_delete=models.PROTECT,
+        verbose_name=_("location"),
+        help_text=_("The location where the observation was made."),
+    )
+
+    date = models.DateField(
+        db_index=True,
+        verbose_name=_("date"),
+        help_text=_("The date the observation was made."),
+    )
+
+    time = models.TimeField(
+        blank=True,
+        null=True,
+        verbose_name=_("time"),
+        help_text=_("The time the observation was made."),
+    )
+
+    started = models.DateTimeField(
+        blank=True,
+        db_index=True,
+        null=True,
+        verbose_name=_("date & time"),
+        help_text=_("The date and time the observation was made."),
+    )
+
+    count = models.IntegerField(
+        validators=[MinValueValidator(0)],
+        verbose_name=_("count"),
+        help_text=_("The number of birds seen."),
+    )
+
+    audio = models.BooleanField(
+        default=False,
+        verbose_name=_("has audio"),
+        help_text=_("Have audio recordings been uploaded to the Macaulay library."),
+    )
+
+    photo = models.BooleanField(
+        default=False,
+        verbose_name=_("has photos"),
+        help_text=_("Have photos been uploaded to the Macaulay library."),
+    )
+
+    video = models.BooleanField(
+        default=False,
+        verbose_name=_("has video"),
+        help_text=_("Have video recordings been uploaded to the Macaulay library."),
+    )
+
+    approved = models.BooleanField(
+        default=True,
+        verbose_name=_("Approved"),
+        help_text=_("Has the observation been accepted."),
+    )
+
+    reason = models.TextField(
+        blank=True,
+        verbose_name=_("Reason"),
+        help_text=_(
+            "The reason given for the observation to be marked as not approved."
+        ),
+    )
+
+    comments = models.TextField(
+        blank=True,
+        verbose_name=_("comments"),
+        help_text=_("Any comments about the observation."),
+    )
+
+    urn = models.TextField(
+        blank=True,
+        verbose_name=_("URN"),
+        help_text=_("The globally unique identifier for the observation."),
+    )
+
+    data = models.JSONField(
+        verbose_name=_("Data"),
+        help_text=_("Data describing an Observation."),
+        default=dict,
+        blank=True,
+    )
+
+    def __repr__(self) -> str:
+        return str(self.identifier)
+
+    def __str__(self) -> str:
+        return str(self.identifier)
+
+    def get_reason(self) -> str:
+        try:
+            data = json.loads(self.reason)
+            reason = data.get(get_language(), "")
+        except JSONDecodeError:
+            log.error("Incorrect JSON for Observation reason: %s", self.id)
+            reason = ""
+        return reason
+
+    def has_media(self):
+        return self.audio or self.photo or self.video