Date handling
Note
Partial dates are currently only supported by the monkeypox instance. For SARS-CoV-2, the year
and month
fields do not exist.
The date
field returns and the dateFrom
and dateTo
parameters expect a string formatted as YYYY-MM-DD (e.g., 2022-05-29). There are however samples for which we do not know the exact date but only a partial date: e.g., only the year or the year and the month. In those cases, the date
is considered as unknown and will return a null
. That means that the query dateFrom=2022-01-01
will not return samples for which we do not know the exact date but only that it is from May 2022.
To support partial dates, LAPIS additionally has the fields year
and month
. They are returned by the details
endpoint and can be used as an aggregation field (e.g., fields=year,month
is possible). Further, LAPIS offers yearFrom
, yearTo
, yearMonthFrom
and yearMonthTo
filters. yearMonth
has to be formatted as YYYY-MM. For example, the queries yearFrom=2022
and yearMonthFrom=2022-05
will include all samples from May 2022.
Background
Why is the query dateFrom=2022-01-01
not returning samples from May 2022 that don’t have an exact date? The reason is that the following (desirable) property would be violated:
For t0 < t1:
aggregated(dateFrom=t0)
= aggregated(dateFrom=t0,dateTo=t1) + aggregated(dateFrom=t1+1)
= sum(aggregated(dateFrom=t0,fields=date))