feat: Support creating Lightcycler Sample Sheets for Absolute Quantification (#55)

Author: simbig

.php-cs-fixer.php

@@ -9,4 +9,7 @@
     ->ignoreDotFiles(true)
     ->ignoreVCS(true);
 
-return risky($finder);
+$config = risky($finder);
+$config->setCacheFile(__DIR__ . '/.build/php-cs-fixer/cache');
+
+return $config;

CHANGELOG.md

@@ -9,6 +9,13 @@ See [GitHub releases](https://github.com/mll-lab/php-utils/releases).
 
 ## Unreleased
 
+## v5.17.0
+
+### Added
+
+- Support creating Lightcycler Sample Sheets for Absolute Quantification https://github.com/mll-lab/php-utils/pull/55
+- Accept `iterable $data` in `CSVArray::toCSV` https://github.com/mll-lab/php-utils/pull/55
+
 ## v5.16.0
 
 ### Added

Makefile

@@ -3,7 +3,7 @@ it: fix stan test ## Run the commonly used targets
 
 .PHONY: help
 help: ## Displays this list of targets with descriptions
-	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(firstword $(MAKEFILE_LIST)) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}'
+	@grep --extended-regexp '^[a-zA-Z0-9_-]+:.*?## .*$$' $(firstword $(MAKEFILE_LIST)) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}'
 
 setup: vendor ## Set up the repository
 
@@ -23,7 +23,7 @@ rector: vendor
 .PHONY: php-cs-fixer
 php-cs-fixer:
 	mkdir --parents .build/php-cs-fixer
-	vendor/bin/php-cs-fixer fix --cache-file=.build/php-cs-fixer/cache
+	vendor/bin/php-cs-fixer fix
 
 .PHONY: stan
 stan: vendor ## Runs a static analysis with phpstan
@@ -37,5 +37,5 @@ test: vendor ## Runs auto-review, unit, and integration tests with phpunit
 
 vendor: composer.json
 	composer validate --strict
-	composer install
+	composer update
 	composer normalize

phpstan.neon

@@ -18,3 +18,5 @@ parameters:
   - '#Unsafe usage of new static.*#'
   # Not in older PHPUnit versions
   - '#Attribute class PHPUnit\\Framework\\Attributes\\DataProvider does not exist\.#'
+  # Allows assert() calls to assist IDE autocompletion
+  - message: '#Call to function assert\(\) with true.* will always evaluate to true\.#'

rector.php

@@ -24,7 +24,7 @@
         Rector\PHPUnit\CodeQuality\Rector\Class_\PreferPHPUnitSelfCallRector::class,
     ])
     ->withSkip([
-        Rector\PHPUnit\CodeQuality\Rector\MethodCall\AssertCountWithZeroToAssertEmptyRector::class, // sloppy
+        Rector\PHPUnit\CodeQuality\Rector\Class_\RemoveDataProviderParamKeysRector::class, // breaks tests
         Rector\PHPUnit\CodeQuality\Rector\Class_\PreferPHPUnitThisCallRector::class, // breaks tests
         Rector\CodeQuality\Rector\Concat\JoinStringConcatRector::class => [
             __DIR__ . '/tests/CSVArrayTest.php', // keep `\r\n` for readability

src/CSVArray.php

@@ -46,18 +46,18 @@ public static function toArray(string $csv, string $delimiter = ';', string $enc
         return $result;
     }
 
-    /** @param array<int, array<string, CSVPrimitive>> $data */
-    public static function toCSV(array $data, string $delimiter = ';', string $lineSeparator = "\r\n"): string
+    /** @param iterable<array<string, CSVPrimitive>> $data */
+    public static function toCSV(iterable $data, string $delimiter = ';', string $lineSeparator = StringUtil::WINDOWS_NEWLINE): string
     {
-        if ($data === []) {
-            throw new \Exception('Array is empty');
-        }
-
         // Use the keys of the array as the headers of the CSV
         $headerItem = Arr::first($data);
-        if (! is_array($headerItem)) {
-            throw new \Exception('Missing column headers.');
+        if ($headerItem === null) {
+            throw new \Exception('Expected $data to contain at least one item.');
         }
+        assert(
+            is_array($headerItem), // @phpstan-ignore function.alreadyNarrowedType (necessary for older PHPStan/Illuminate versions)
+            'Expected $data to contain arrays.'
+        );
         $headerKeys = array_keys($headerItem);
 
         $content = str_putcsv($headerKeys, $delimiter) . $lineSeparator;

src/LightcyclerSampleSheet/AbsoluteQuantificationSample.php

@@ -0,0 +1,64 @@
+<?php declare(strict_types=1);
+
+namespace MLL\Utils\LightcyclerSampleSheet;
+
+use MLL\Utils\Microplate\Coordinates;
+use MLL\Utils\Microplate\CoordinateSystem12x8;
+
+class AbsoluteQuantificationSample
+{
+    public string $sampleName;
+
+    public string $filterCombination;
+
+    public string $hexColor;
+
+    public string $sampleType;
+
+    /** Key used to determine replication grouping - samples with the same key will replicate to the first occurrence */
+    public string $replicationOfKey;
+
+    public ?int $concentration;
+
+    public function __construct(
+        string $sampleName,
+        string $filterCombination,
+        string $hexColor,
+        string $sampleType,
+        string $replicationOfKey,
+        ?int $concentration
+    ) {
+        $this->sampleName = $sampleName;
+        $this->filterCombination = $filterCombination;
+        $this->hexColor = $hexColor;
+        $this->sampleType = $sampleType;
+        $this->replicationOfKey = $replicationOfKey;
+        $this->concentration = $concentration;
+    }
+
+    public static function formatConcentration(?int $concentration): ?string
+    {
+        if ($concentration === null) {
+            return null;
+        }
+
+        $exponent = (int) floor(log10(abs($concentration)));
+        $mantissa = $concentration / (10 ** $exponent);
+
+        return number_format($mantissa, 2) . 'E' . $exponent;
+    }
+
+    /** @return array<string, string|null> */
+    public function toSerializableArray(string $coordinatesString, string $replicationOfCoordinate): array
+    {
+        return [
+            'General:Pos' => Coordinates::fromString($coordinatesString, new CoordinateSystem12x8())->toString(),
+            'General:Sample Name' => $this->sampleName,
+            'General:Repl. Of' => $replicationOfCoordinate,
+            'General:Filt. Comb.' => $this->filterCombination,
+            'Sample Preferences:Color' => RandomHexGenerator::LIGHTCYCLER_COLOR_PREFIX . $this->hexColor,
+            'Abs Quant:Sample Type' => $this->sampleType,
+            'Abs Quant:Concentration' => self::formatConcentration($this->concentration),
+        ];
+    }
+}

src/LightcyclerSampleSheet/AbsoluteQuantificationSheet.php

@@ -0,0 +1,49 @@
+<?php declare(strict_types=1);
+
+namespace MLL\Utils\LightcyclerSampleSheet;
+
+use Illuminate\Support\Collection;
+use MLL\Utils\CSVArray;
+
+class AbsoluteQuantificationSheet
+{
+    /** @param Collection<string, AbsoluteQuantificationSample> $samples */
+    public function generate(Collection $samples): string
+    {
+        $replicationMapping = $this->calculateReplicationMapping($samples);
+
+        $data = $samples->map(fn (AbsoluteQuantificationSample $well, string $coordinateFromKey): array => $well->toSerializableArray(
+            $coordinateFromKey,
+            $replicationMapping[$coordinateFromKey]
+        ));
+
+        return CSVArray::toCSV($data, "\t");
+    }
+
+    /**
+     * Calculate replication mapping based on replicationOfKey.
+     *
+     * @param Collection<string, AbsoluteQuantificationSample> $samples
+     *
+     * @return array<string, string> a map of coordinate -> replicationOfCoordinate
+     */
+    private function calculateReplicationMapping(Collection $samples): array
+    {
+        $replicationKeyMap = [];
+        $mapping = [];
+
+        foreach ($samples as $coordinate => $sample) {
+            if (! isset($replicationKeyMap[$sample->replicationOfKey])) {
+                // The First occurrence replicates to itself
+                $replicationKeyMap[$sample->replicationOfKey] = $coordinate;
+                $mapping[$coordinate] = $coordinate;
+            } else {
+                // Later occurrences replicate to the first occurrence
+                $firstOccurrenceCoordinate = $replicationKeyMap[$sample->replicationOfKey];
+                $mapping[$coordinate] = $firstOccurrenceCoordinate;
+            }
+        }
+
+        return $mapping;
+    }
+}

src/LightcyclerSampleSheet/RandomHexGenerator.php

@@ -4,6 +4,8 @@
 
 class RandomHexGenerator
 {
+    public const LIGHTCYCLER_COLOR_PREFIX = '$00';
+
     /** @var list<string> */
     private array $generatedHexCodes = [];
 

src/LightcyclerSampleSheet/RelativeQuantificationSample.php

@@ -41,7 +41,7 @@ public function toSerializableArray(string $coordinatesString): array
             "\"{$this->sampleName}\"",
             $replicationOf,
             $this->filterCombination,
-            "$00{$this->hexColor}",
+            RandomHexGenerator::LIGHTCYCLER_COLOR_PREFIX . $this->hexColor,
         ];
     }
 }