diff --git a/docs/DATA_IMPORT.md b/docs/DATA_IMPORT.md index aba9432..6a65108 100644 --- a/docs/DATA_IMPORT.md +++ b/docs/DATA_IMPORT.md @@ -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 @@ -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" | @@ -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" | @@ -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 @@ -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 @@ -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 diff --git a/krill/person/views.py b/krill/person/views.py index 881add3..0292c99 100644 --- a/krill/person/views.py +++ b/krill/person/views.py @@ -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): diff --git a/krill/sample/tests/test_views.py b/krill/sample/tests/test_views.py index 4e4db3b..b489293 100644 --- a/krill/sample/tests/test_views.py +++ b/krill/sample/tests/test_views.py @@ -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"') diff --git a/krill/templates/sample/list.html b/krill/templates/sample/list.html index a46e4cc..baaa60b 100644 --- a/krill/templates/sample/list.html +++ b/krill/templates/sample/list.html @@ -6,6 +6,11 @@
Browse and manage {{ model_name|lower }}
+ {% if model_type == 'sample' %} +A sample is a cell line or other specimen type. Each tube of it is an aliquot.
+ {% elif model_type == 'aliquot' %} +An aliquot is one tube: a single portion of a sample.
+ {% endif %}