Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
- [Database Setup](database.md) - SQLite and PostgreSQL configuration

## Using Krill
- [Searching samples and aliquots](../krill/sample/README.md) - search the lists, filter by field, chips and pills
- [Reports and storage audits](../krill/reports/README.md) - spot-check storage, resume and review audits, alerts

## Deployment (`deployment/`)
Expand Down
39 changes: 39 additions & 0 deletions krill/sample/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Samples and aliquots

A **sample** is a cell line or other specimen. An **aliquot** is one portion of it. This page covers finding things in the lists.

## Searching the Aliquots list

Open **Samples > Aliquots**. The toolbar is one row: a search box, **Sample**, **Passage**, **More filters**, **Search** and **New Aliquot**.

### Search everything
The first box looks in every field (sample name, experiment, notes, type, disposition, passage, lab member, sample date, box, freezer and aliquot number). Type several words and **every word must match something**, so `hela p8` finds the p8 aliquots of HeLa. Put words in "quotes" to match them as one phrase. A number, with or without `#`, also matches the aliquot number.

### Search by field
Fill in a field to aim at it. **Every field you fill in must match**, so Sample `HeLa` with Passage `P8` gives only the P8 aliquots of HeLa.

| Field | Where | How it matches |
|---|---|---|
| Sample | toolbar | part of the sample name, ignoring case; every word must appear |
| Passage | toolbar | **exactly**, ignoring case: `P8` finds `P8` and `p8`, not `P80`. End with `*` to match the start: `P8*` finds `P8`, `P80`, `P8+3` |
| Lab member | More filters | part of a name, username or initials |
| Date from / Date to | More filters | on or after, and on or before. The same date in both means that day. Aliquots with no sample date are never included, and the page says how many were left out |
| Location | More filters | part of a freezer or box name |
| Aliquot number | More filters | the exact number, with or without `#` |
| Disposition, Type | More filters | pick one |

**More filters** opens by itself when one of its fields is in use, and shows how many are.

### Chips, clearing and sharing
Each active filter shows as a chip under the toolbar, for example "Passage is P8". Click its **x** to remove just that one. With two or more chips, **Clear all** removes every filter, the search words and the pills, and keeps how the list is sorted. When nothing matches, the page lists the filters in use, each with a link that removes it.

The search is kept in the page address, so you can bookmark it or send the link. The field parameters are `f_sample`, `f_passage`, `f_member`, `f_date_from`, `f_date_to`, `f_location` and `f_number`, plus the existing `disposition`, `aliquot_type` and `q`.

### Pills
Two on/off pills sit under the toolbar: **Checked out by me** (with a count) and **Hide exhausted**. They combine with everything above.

## Searching the Samples list
The Samples list has the search box plus **Source**, **Experiment** and **Notes** fields (all part-of matches), the **Low count** pill, and the same chips and Clear all.

## For developers
Each list describes its filter fields once in `sample/list_filters.py` (a `FilterSpec`: name, label, kind, hint, inline or in the More panel). From that one description come the query filters, the inputs (`templates/sample/_filter_fields.html`), the chips and Clear all (`_filter_chips.html`) and the empty-result suggestions. To add a field to a list, add a `FilterField`; to give another list the same bar, define a spec for it and call `spec.apply` and `spec.bind` from its view. Treat the parameter names as stable, because people bookmark them. Tests are in `sample/tests/test_field_filters.py`.
264 changes: 264 additions & 0 deletions krill/sample/list_filters.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,264 @@
"""Field filters for list pages ("Sample X with Passage Y").

Each list describes its filter fields once, as a FilterSpec. From that one description come:
- the query filters (spec.apply),
- the inputs on the page (spec.bind(request).inline / .more),
- the removable chips, the Clear all link, and the suggestions shown when nothing matches.

Every filled-in field must match (AND). The query parameter names are part of the page address, so
people can bookmark and share a search; treat them as stable.

Matching rules:
contains case-insensitive; every word must appear, and "quoted words" keep their spacing
exact the whole value, ignoring case
passage exact, ignoring case; a trailing * matches the start instead (P8* finds P8, P80, P8+3)
number an exact aliquot number, with or without a leading #
date_from on or after; date_to on or before (aliquots with no date never match either)
select one of a fixed list of choices
"""
import re
from dataclasses import dataclass
from datetime import date
from typing import Callable, Optional, Tuple

from django.db.models import Q

CONTAINS = 'contains'
EXACT = 'exact'
PASSAGE = 'passage'
NUMBER = 'number'
DATE_FROM = 'date_from'
DATE_TO = 'date_to'
SELECT = 'select'

DATE_KINDS = (DATE_FROM, DATE_TO)
_WORDS = re.compile(r'"([^"]+)"|(\S+)')


def split_words(text):
"""'hela p8 "cell line"' -> ['hela', 'p8', 'cell line']"""
return [quoted or word for quoted, word in _WORDS.findall(text or '') if (quoted or word).strip()]


def parse_date(value):
try:
return date.fromisoformat(value)
except (TypeError, ValueError):
return None


@dataclass(frozen=True)
class FilterField:
param: str # query parameter, e.g. 'f_sample'
label: str # shown next to the input and in chips
kind: str
paths: Tuple[str, ...] = () # model lookups to search (OR across paths)
placeholder: str = ''
hint: str = '' # one line under the label in the More panel
inline: bool = False # shown in the toolbar row (otherwise in More)
verb: str = '' # chip wording override, e.g. 'contain' for "Notes contain x"
choices: Optional[Callable] = None # SELECT: () -> [(value, label)]
select_filter: Optional[Callable] = None # SELECT: (queryset, value) -> queryset


@dataclass(frozen=True)
class Chip:
text: str
remove_url: str


class BoundField:
"""A field with its current value, ready for a template."""

def __init__(self, field, value):
self.field = field
self.param = field.param
self.label = field.label
self.kind = field.kind
self.value = value
self.placeholder = field.placeholder
self.hint = field.hint
self.is_select = field.kind == SELECT
self.is_date = field.kind in DATE_KINDS
self.choices = []
if self.is_select:
self.choices = [(v, label, str(v) == value) for v, label in field.choices()]


class FilterBar:
def __init__(self, inline, more, chips, clear_all_url):
self.inline = inline
self.more = more
self.chips = chips
self.clear_all_url = clear_all_url
self.more_active = sum(1 for f in more if f.value)
# The rules for the inline fields, repeated at the top of the More panel
self.inline_hints = [(f.label, f.hint) for f in inline if f.hint]
self.has_filters = bool(chips)
self.show_clear_all = len(chips) >= 2


class FilterSpec:
def __init__(self, fields, reset_params=()):
self.fields = list(fields)
# Other parameters that "Clear all" also removes (the search phrase, pills, ...)
self.reset_params = tuple(reset_params)

# --- reading the request --------------------------------------------------

@staticmethod
def value_of(query, field):
return (query.get(field.param) or '').strip()

def active(self, query):
"""[(field, value)] for the fields that are filled in and mean something."""
result = []
for field in self.fields:
value = self.value_of(query, field)
if not value:
continue
if field.kind in DATE_KINDS and parse_date(value) is None:
continue
if field.kind == PASSAGE and value.rstrip('*').strip() == '':
continue
if field.kind == SELECT and not self._select_matches(field, value):
continue
result.append((field, value))
return result

@staticmethod
def _select_matches(field, value):
return any(str(v) == value for v, _ in field.choices())

# --- filtering ------------------------------------------------------------

def apply(self, queryset, query, skip_kinds=(), only_kinds=None):
for field, value in self.active(query):
if field.kind in skip_kinds or (only_kinds is not None and field.kind not in only_kinds):
continue
queryset = self._filter(queryset, field, value)
return queryset

@staticmethod
def _filter(queryset, field, value):
kind = field.kind
if kind == CONTAINS:
for word in split_words(value):
match = Q()
for path in field.paths:
match |= Q(**{f'{path}__icontains': word})
queryset = queryset.filter(match)
return queryset
if kind == EXACT:
match = Q()
for path in field.paths:
match |= Q(**{f'{path}__iexact': value})
return queryset.filter(match)
if kind == PASSAGE:
path = field.paths[0]
if value.endswith('*'):
return queryset.filter(**{f'{path}__istartswith': value.rstrip('*').strip()})
return queryset.filter(**{f'{path}__iexact': value})
if kind == NUMBER:
number = value.lstrip('#')
return queryset.filter(pk=int(number)) if number.isdigit() else queryset.none()
if kind == DATE_FROM:
return queryset.filter(**{f'{field.paths[0]}__gte': parse_date(value)})
if kind == DATE_TO:
return queryset.filter(**{f'{field.paths[0]}__lte': parse_date(value)})
if kind == SELECT:
return field.select_filter(queryset, value)
return queryset

# --- what the page shows --------------------------------------------------

@staticmethod
def chip_text(field, value):
kind = field.kind
if kind in DATE_KINDS:
return f'{field.label} {value}'
if kind == SELECT:
label = next((label for v, label in field.choices() if str(v) == value), value)
return f'{field.label}: {label}'
if kind == PASSAGE:
return f'{field.label} starts with {value.rstrip("*").strip()}' if value.endswith('*') else f'{field.label} is {value}'
if kind in (EXACT, NUMBER):
return f'{field.label} is {value}'
return f'{field.label} {field.verb or "contains"} {value}'

@staticmethod
def url_without(request, *params):
"""The current address minus some parameters, back on page 1."""
query = request.GET.copy()
query.pop('page', None)
for param in params:
query.pop(param, None)
encoded = query.urlencode()
return f'?{encoded}' if encoded else request.path

def bind(self, request, extra_chips=()):
"""Everything a template needs. extra_chips are (text, parameter) pairs for filters this spec
does not own, such as the search phrase; they are shown first."""
chips = [Chip(text, self.url_without(request, param)) for text, param in extra_chips]
for field, value in self.active(request.GET):
chips.append(Chip(self.chip_text(field, value), self.url_without(request, field.param)))
everything = [f.param for f in self.fields] + list(self.reset_params)
bound = [BoundField(field, self.value_of(request.GET, field)) for field in self.fields]
return FilterBar(
inline=[b for b in bound if b.field.inline],
more=[b for b in bound if not b.field.inline],
chips=chips,
clear_all_url=self.url_without(request, *everything),
)


# --- the lists ---------------------------------------------------------------

def _disposition_choices():
from .models.aliquot import AliquotDisposition
return list(AliquotDisposition.DISPOSITION_CHOICES)


def _type_choices():
from .models.aliquot import AliquotType
return [(str(t.pk), t.name) for t in AliquotType.objects.order_by('name')]


ALIQUOT_FILTERS = FilterSpec(
[
FilterField('f_sample', 'Sample', CONTAINS, ('sample__name',), inline=True,
placeholder='Sample', hint='Part of the sample name.'),
FilterField('f_passage', 'Passage', PASSAGE, ('passage',), inline=True,
placeholder='Passage',
hint='Matches exactly, ignoring case: P8 finds P8 and p8, not P80. End with * to match the start, for example P8*.'),
FilterField('f_member', 'Lab member', CONTAINS,
('lab_member_initials', 'lab_member__first_name', 'lab_member__last_name', 'lab_member__username'),
placeholder='Name or initials', hint='Name or initials.'),
FilterField('f_date_from', 'Date from', DATE_FROM, ('sample_date',),
hint='On or after. Aliquots with no sample date are left out.'),
FilterField('f_date_to', 'Date to', DATE_TO, ('sample_date',),
hint='On or before. Aliquots with no sample date are left out.'),
FilterField('f_location', 'Location', CONTAINS,
('location__box__name', 'location__box__rack__shelf__device__name'),
placeholder='Freezer or box', hint='Part of a freezer or box name.'),
FilterField('f_number', 'Aliquot number', NUMBER, ('pk',),
placeholder='e.g. 1234', hint='The exact aliquot number.'),
FilterField('disposition', 'Disposition', SELECT, choices=_disposition_choices,
select_filter=lambda qs, value: qs.filter(disposition__disposition_type=value)),
FilterField('aliquot_type', 'Type', SELECT, choices=_type_choices,
select_filter=lambda qs, value: qs.filter(aliquot_type_id=int(value))),
],
reset_params=('q', 'sample', 'checked_out_by', 'hide_finished', 'low_count'),
)

SAMPLE_FILTERS = FilterSpec(
[
FilterField('f_source', 'Source', CONTAINS, ('source__name',), inline=True,
placeholder='Source', hint='Part of the source name.'),
FilterField('f_experiment', 'Experiment', CONTAINS, ('experiment',), inline=True,
placeholder='Experiment', hint='Part of the experiment text.'),
FilterField('f_notes', 'Notes', CONTAINS, ('notes',), inline=True, verb='contain',
placeholder='Notes', hint='Part of the notes.'),
],
reset_params=('q', 'checked_out_by', 'hide_finished', 'low_count'),
)
Loading
Loading