Lightcycler sample sheet

Author: simbig

CHANGELOG.md

@@ -9,6 +9,12 @@ See [GitHub releases](https://github.com/mll-lab/php-utils/releases).
 
 ## Unreleased
 
+## v5.10.0
+
+### Added
+
+- Support creating Lightcycler Sample Sheets for Relative Quantification
+
 ## v5.9.0
 
 ### Added

src/LightcyclerSampleSheet/RandomHexGenerator.php

@@ -0,0 +1,23 @@
+<?php declare(strict_types=1);
+
+namespace MLL\Utils\LightcyclerSampleSheet;
+
+class RandomHexGenerator
+{
+    /** @var list<string> */
+    private array $generatedHexCodes = [];
+
+    public function uniqueHex6Digits(): string
+    {
+        do {
+            $randomNumber = mt_rand(0, 0xFFFFFF);
+            $hexString = dechex($randomNumber);
+            $paddedHexString = str_pad($hexString, 6, '0', STR_PAD_LEFT);
+            $uniqueHexCode = strtoupper($paddedHexString);
+        } while (in_array($uniqueHexCode, $this->generatedHexCodes, true));
+
+        $this->generatedHexCodes[] = $uniqueHexCode;
+
+        return $uniqueHexCode;
+    }
+}

src/LightcyclerSampleSheet/RelativeQuantificationSample.php

@@ -0,0 +1,47 @@
+<?php declare(strict_types=1);
+
+namespace MLL\Utils\LightcyclerSampleSheet;
+
+use MLL\Utils\Microplate\Coordinates;
+use MLL\Utils\Microplate\CoordinateSystem12x8;
+
+class RelativeQuantificationSample
+{
+    public string $sampleName;
+
+    public string $filterCombination;
+
+    public string $hexColor;
+
+    /** @var Coordinates<CoordinateSystem12x8>|null */
+    public ?Coordinates $replicationOf;
+
+    /** @param Coordinates<CoordinateSystem12x8>|null $replicationOf */
+    public function __construct(
+        string $sampleName,
+        string $filterCombination,
+        string $hexColor,
+        ?Coordinates $replicationOf
+    ) {
+        $this->sampleName = $sampleName;
+        $this->filterCombination = $filterCombination;
+        $this->hexColor = $hexColor;
+        $this->replicationOf = $replicationOf;
+    }
+
+    /** @return list<string> */
+    public function toSerializableArray(string $coordinatesString): array
+    {
+        $replicationOf = $this->replicationOf instanceof Coordinates
+            ? "\"{$this->replicationOf->toString()}\""
+            : '""';
+
+        return [
+            Coordinates::fromString($coordinatesString, new CoordinateSystem12x8())->toString(),
+            "\"{$this->sampleName}\"",
+            $replicationOf,
+            $this->filterCombination,
+            "$00{$this->hexColor}",
+        ];
+    }
+}

src/LightcyclerSampleSheet/RelativeQuantificationSheet.php

@@ -0,0 +1,29 @@
+<?php declare(strict_types=1);
+
+namespace MLL\Utils\LightcyclerSampleSheet;
+
+use Illuminate\Support\Collection;
+
+class RelativeQuantificationSheet
+{
+    protected const WINDOWS_NEW_LINE = "\r\n";
+    protected const TAB_SEPARATOR = "\t";
+    public const HEADER_COLUMNS = [
+        '"General:Pos"',
+        '"General:Sample Name"',
+        '"General:Repl. Of"',
+        '"General:Filt. Comb."',
+        '"Sample Preferences:Color"',
+    ];
+
+    /** @param Collection<string, RelativeQuantificationSample> $samples */
+    public function generate(Collection $samples): string
+    {
+        return $samples
+            ->map(fn (RelativeQuantificationSample $well, string $coordinateFromKey): array => $well->toSerializableArray($coordinateFromKey))
+            ->prepend(self::HEADER_COLUMNS)
+            ->map(fn (array $row): string => implode(self::TAB_SEPARATOR, $row))
+            ->implode(self::WINDOWS_NEW_LINE)
+            . self::WINDOWS_NEW_LINE;
+    }
+}

tests/LightcyclerSampleSheet/RandomHexGeneratorTest.php

@@ -0,0 +1,29 @@
+<?php declare(strict_types=1);
+
+namespace MLL\Utils\Tests\LightcyclerSampleSheet;
+
+use MLL\Utils\LightcyclerSampleSheet\RandomHexGenerator;
+use PHPUnit\Framework\TestCase;
+
+final class RandomHexGeneratorTest extends TestCase
+{
+    public function testGeneratesValidHexCode(): void
+    {
+        $generator = new RandomHexGenerator();
+        $hexCode = $generator->uniqueHex6Digits();
+
+        self::assertTrue((bool) \Safe\preg_match('/^[A-F0-9]{6}$/', $hexCode));
+    }
+
+    public function testGeneratesUniqueHexCodes(): void
+    {
+        $generator = new RandomHexGenerator();
+        $hexCodes = [];
+
+        for ($i = 0; $i < 1000; ++$i) {
+            $hexCodes[] = $generator->uniqueHex6Digits();
+        }
+
+        self::assertCount(1000, array_unique($hexCodes));
+    }
+}

tests/LightcyclerSampleSheet/RelativeQuantificationSheetTest.php

@@ -0,0 +1,40 @@
+<?php declare(strict_types=1);
+
+namespace MLL\Utils\Tests\LightcyclerSampleSheet;
+
+use Illuminate\Support\Collection;
+use MLL\Utils\LightcyclerSampleSheet\RelativeQuantificationSample;
+use MLL\Utils\LightcyclerSampleSheet\RelativeQuantificationSheet;
+use MLL\Utils\Microplate\Coordinates;
+use MLL\Utils\Microplate\CoordinateSystem12x8;
+use MLL\Utils\StringUtil;
+use PHPUnit\Framework\TestCase;
+
+final class RelativeQuantificationSheetTest extends TestCase
+{
+    public function testGenerate(): void
+    {
+        $samples = Collection::make([
+            'A1' => new RelativeQuantificationSample('Sample 1', '498-640', 'FF378A', null),
+            'B1' => new RelativeQuantificationSample('Sample 2', '498-640', '4899D1', null),
+            'C1' => new RelativeQuantificationSample('Sample 3', '498-640', '8528B9', null),
+            'D1' => new RelativeQuantificationSample('Sample 4', '498-640', '8E05D9', null),
+            'E1' => new RelativeQuantificationSample('Sample 5', '498-640', '4080A5', Coordinates::fromString('C12', new CoordinateSystem12x8())),
+        ]);
+
+        $sheet = new RelativeQuantificationSheet();
+        $result = $sheet->generate($samples);
+
+        $expected = <<<EOT
+"General:Pos"\t"General:Sample Name"\t"General:Repl. Of"\t"General:Filt. Comb."\t"Sample Preferences:Color"
+A1\t"Sample 1"\t""\t498-640\t$00FF378A
+B1\t"Sample 2"\t""\t498-640\t$004899D1
+C1\t"Sample 3"\t""\t498-640\t$008528B9
+D1\t"Sample 4"\t""\t498-640\t$008E05D9
+E1\t"Sample 5"\t"C12"\t498-640\t$004080A5
+
+EOT;
+
+        self::assertSame(StringUtil::normalizeLineEndings($expected), $result);
+    }
+}