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
20 changes: 9 additions & 11 deletions docs/DATA_IMPORT.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,9 @@ This guide explains how to structure CSV files for importing sample data into Kr

Krill supports importing sample data via CSV files. The import process creates:
- **Sources**: Sample sources/origins
- **Samples**: Cell lines or sample types
- **Samples**: Cell lines or other specimen types (the `Cell Line` column becomes a Sample in Krill)
- **Storage Hierarchy**: Sites → Devices (freezers) → Shelves → Racks → Boxes
- **Aliquots**: Individual sample aliquots
- **Tubes**: Individual tubes within aliquots
- **Aliquots**: One per physical tube. An aliquot is a single portion of a sample
- **Locations**: Physical storage positions within boxes

## File Format Requirements
Expand Down Expand Up @@ -53,7 +52,7 @@ The CSV file must include the following columns (in any order):
| Column Name | Required | Description | Example |
|------------|----------|-------------|---------|
| `Source` | Yes | Name of the sample source/origin | "Example Lab" |
| `Cell Line` | Yes | Name/identifier of the cell line or sample | "MM134" |
| `Cell Line` | Yes | Name of the cell line or other specimen type. It becomes a Sample in Krill | "MM134" |
| `Experiment #` | No | Experiment identifier | "EXP_001" |
| `Sample Notes` | No | Notes about the sample | "Legacy sample from 2017" |
| `Site` | No | Name of the storage site/location | "Main Lab", "Satellite Facility" |
Expand All @@ -63,7 +62,7 @@ The CSV file must include the following columns (in any order):
| `Position 3` | No | Row position within the box (1-based) | "1" |
| `Position 4` | No | Column position within the box (1-based) | "5" |
| `Aliquot Type` | Yes | Type of aliquot | "Cells", "DNA", "RNA" |
| `Number of Aliquots Total` | Yes | Total number of tubes/aliquots | "6" |
| `Number of Aliquots Total` | Yes | How many aliquots (tubes) this row represents | "6" |
| `Disposition` | Yes | Current status of the aliquot | "stored", "in_use", "exhausted", "disposed" (or legacy aliases) |
| `Passage Number` | No | Passage when the aliquot was frozen, stored as written on the aliquot | "p8", "p20EV p39+4-5" |
| `Lab Member` | No | Initials of who prepared the aliquot | "JS" |
Expand Down Expand Up @@ -138,9 +137,9 @@ How `Position 1` and `Position 2` map onto the hierarchy is set by the optional
- Examples: "Cells", "DNA", "RNA", "Plasma", etc.

### Number of Aliquots Total
- Determines how many tubes are created for this aliquot
- Determines how many aliquots (tubes) are created for the row
- Must be a positive integer
- Each tube gets a sequential tube number (1, 2, 3, ...)
- The row's box position (`Position 3` and `Position 4`) is stored on the first of them
- If empty or invalid, defaults to 1

### Disposition
Expand Down Expand Up @@ -205,9 +204,8 @@ For each row in your CSV:
- Site → Device → Shelf → Rack → Box
4. **AliquotType** (if new)
5. **AliquotDisposition** (if new)
6. **Aliquot** (one per row)
7. **AliquotTubes** (one per `Number of Aliquots Total`)
8. **AliquotLocation** (if Position 3 and Position 4 provided)
6. **Aliquots** (one per `Number of Aliquots Total`; each is one tube)
7. **AliquotLocation** (if Position 3 and Position 4 provided)

### Duplicate Handling

Expand All @@ -226,7 +224,7 @@ For each row in your CSV:
### Issue: Samples imported but no storage locations
**Solution**: Ensure `Freezer Name`, `Position 1`, and `Position 2` are provided. `Position 3` and `Position 4` are optional but both must be present together.

### Issue: Wrong number of tubes created
### Issue: Wrong number of aliquots created
**Solution**: Check the `Number of Aliquots Total` column. It must be a positive integer. Empty values default to 1.

### Issue: Disposition not recognized
Expand Down
2 changes: 1 addition & 1 deletion krill/person/views.py
Original file line number Diff line number Diff line change
Expand Up @@ -281,7 +281,7 @@ def is_xlsx_file(path):
class DataImportForm(forms.Form):
csv_file = forms.FileField(
label='Data File',
help_text='Upload a CSV or XLSX file with sample data (for XLSX, the first sheet is used). Expected columns: Source;Cell Line;Experiment #;Sample Notes;Site;Freezer Name;Position 1;Position 2;Position 3;Position 4;Aliquot Type;Number of Aliquots Total;Disposition (Site is optional, defaults to "Default Site")'
help_text='Upload a CSV or XLSX file with sample data (for XLSX, the first sheet is used). Each Cell Line becomes a Sample, and each tube becomes an aliquot. Expected columns: Source;Cell Line;Experiment #;Sample Notes;Site;Freezer Name;Position 1;Position 2;Position 3;Position 4;Aliquot Type;Number of Aliquots Total;Disposition (Site is optional, defaults to "Default Site")'
)

def clean_csv_file(self):
Expand Down
27 changes: 27 additions & 0 deletions krill/sample/tests/test_views.py
Original file line number Diff line number Diff line change
Expand Up @@ -810,3 +810,30 @@ def test_aliquot_search_invalid_page_size_falls_back_to_50(self):
response = self.client.get(reverse('sample:aliquot_search') + '?page_size=999')
self.assertEqual(response.status_code, 200)
self.assertEqual(response.context['aliquots'].paginator.per_page, 50)


class SampleWordingAndExperimentTest(SampleViewTest):
"""A sample is a cell line or other specimen type; an aliquot is one tube. Experiment is editable."""

def test_sample_list_explains_samples_and_aliquots(self):
self.client.force_login(self.user)
page = self.client.get(reverse('sample:sample_list'))
self.assertContains(page, 'A sample is a cell line or other specimen type')
page = self.client.get(reverse('sample:sample_list'), {'type': 'aliquot'})
self.assertContains(page, 'An aliquot is one tube')

def test_create_form_offers_the_experiment_field_and_saves_it(self):
self.client.force_login(self.user)
url = reverse('sample:sample_create') + '?type=sample'
self.assertContains(self.client.get(url), 'name="experiment"')
response = self.client.post(url, {
'name': 'MCF7', 'experiment': 'EXP_W21B', 'source': self.source.pk,
'notes': '', 'access_level': 'all_members',
})
self.assertIn(response.status_code, (200, 302))
self.assertEqual(Sample.objects.get(name='MCF7').experiment, 'EXP_W21B')

def test_detail_page_shows_the_experiment_field_for_editing(self):
self.client.force_login(self.user)
page = self.client.get(reverse('sample:detail', kwargs={'type': 'sample', 'pk': self.sample.pk}))
self.assertContains(page, 'name="experiment"')
5 changes: 5 additions & 0 deletions krill/templates/sample/list.html
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,11 @@
<div class="list-header">
<h1>{{ model_name }}</h1>
<p>Browse and manage {{ model_name|lower }}</p>
{% if model_type == 'sample' %}
<p class="list-hint">A sample is a cell line or other specimen type. Each tube of it is an aliquot.</p>
{% elif model_type == 'aliquot' %}
<p class="list-hint">An aliquot is one tube: a single portion of a sample.</p>
{% endif %}
</div>

<!-- Filter toolbar (aliquot) / search card (other types) -->
Expand Down
Loading