feat: use NucleotidePosition value object, add 0-based coordinate conversion (#85)

* Feat: Use nucleotide position instead of integer. Therefore, the interger is already validated

* Apply php-cs-fixer changes

* fix: enforce 1-based coordinates, add 0-based half-open conversion

NucleotidePosition must reject position 0 to stay consistent with
the 1-based closed coordinate system used by length(), containsPosition(),
intersection() and HGVS g. notation.

Add GenomicRegion::fromZeroBasedHalfOpen() and toZeroBasedHalfOpen()
for BED/BAM/bigWig interoperability: convert at the I/O boundary,
work internally in 1-based closed coordinates.

🤖 Generated with Claude Code

* Implement 1-based and 0-based logik into NucleotidePosition.php

* Add function genomicPositions to GenomicRegion.php
Change function name parse to parseOneBased

* Apply php-cs-fixer changes

---------

Co-authored-by: Dennis Haupt <dennis.haupt@mll.com>
Co-authored-by: KingKong1213 <168984406+KingKong1213@users.noreply.github.com>
Co-authored-by: Simon Bigelmayr <simon.bigelmayr@mll.com>

Author: 3 people

.gitignore

@@ -4,3 +4,4 @@
 /vendor
 /composer.lock
 /.phpunit.result.cache
+/.claude/settings.local.json

src/GenomicPosition.php

@@ -10,24 +10,20 @@ class GenomicPosition
 
     public int $position;
 
-    public function __construct(Chromosome $chromosome, int $position)
+    public function __construct(Chromosome $chromosome, NucleotidePosition $position)
     {
-        if ($position < 1) {
-            throw new \InvalidArgumentException("Position must be positive, got: {$position}.");
-        }
-
         $this->chromosome = $chromosome;
-        $this->position = $position;
+        $this->position = $position->value;
     }
 
-    /** @example GenomicPosition::parse('chr1:123456') */
-    public static function parse(string $value): self
+    /** @example GenomicPosition::parseOneBased('chr1:123456') */
+    public static function parseOneBased(string $value): self
     {
         if (preg_match('/^([^:]+):(g\.|)(\d+)$/', $value, $matches) === 0) {
             throw new \InvalidArgumentException("Invalid genomic position format: {$value}. Expected format: chr1:123456.");
         }
 
-        return new self(new Chromosome($matches[1]), (int) $matches[3]);
+        return new self(new Chromosome($matches[1]), NucleotidePosition::fromOneBased((int) $matches[3]));
     }
 
     public function equals(self $other): bool

src/GenomicRegion.php

@@ -14,36 +14,28 @@ class GenomicRegion
 
     public function __construct(
         Chromosome $chromosome,
-        int $start,
-        int $end
+        NucleotidePosition $start,
+        NucleotidePosition $end
     ) {
-        if ($start < 1) {
-            throw new \InvalidArgumentException("Start must be positive, got: {$start}.");
-        }
-
-        if ($end < 1) {
-            throw new \InvalidArgumentException("End must be positive, got: {$end}.");
-        }
-
-        if ($start > $end) {
-            throw new \InvalidArgumentException("End ({$end}) must not be less than start ({$start}).");
+        if ($start->value > $end->value) {
+            throw new \InvalidArgumentException("End ({$end->value}) must not be less than start ({$start->value}).");
         }
 
         $this->chromosome = $chromosome;
-        $this->start = $start;
-        $this->end = $end;
+        $this->start = $start->value;
+        $this->end = $end->value;
     }
 
-    public static function parse(string $value): self
+    public static function parseOneBased(string $value): self
     {
         if (preg_match('/^([^:]+):(g\.|)(\d+)(-(\d+)|)$/', $value, $matches) === 0) {
             throw new \InvalidArgumentException("Invalid genomic region format: {$value}. Expected format: chr1:123-456.");
         }
 
         return new self(
             new Chromosome($matches[1]),
-            (int) $matches[3],
-            (int) ($matches[5] ?? $matches[3])
+            NucleotidePosition::fromOneBased((int) $matches[3]),
+            NucleotidePosition::fromOneBased((int) ($matches[5] ?? $matches[3]))
         );
     }
 
@@ -98,13 +90,40 @@ public function intersection(self $other): ?self
 
         return new self(
             $this->chromosome,
-            max($this->start, $other->start),
-            min($this->end, $other->end)
+            NucleotidePosition::fromOneBased(max($this->start, $other->start)),
+            NucleotidePosition::fromOneBased(min($this->end, $other->end))
+        );
+    }
+
+    /** Constructs a 1-based closed region from 0-based half-open coordinates (BED, BAM, bigWig). */
+    public static function fromZeroBasedHalfOpen(string $chromosome, int $start, int $end): self
+    {
+        return new self(
+            new Chromosome($chromosome),
+            NucleotidePosition::fromZeroBased($start),
+            NucleotidePosition::fromOneBased($end)
         );
     }
 
+    /** @return array{Chromosome, int, int} Chromosome, 0-based start, half-open end. */
+    public function toZeroBasedHalfOpen(): array
+    {
+        return [$this->chromosome, $this->start - 1, $this->end];
+    }
+
     private function containsCoordinate(int $position): bool
     {
         return $position >= $this->start && $position <= $this->end;
     }
+
+    /** @return array<int, GenomicPosition> */
+    public function genomicPositions(): array
+    {
+        $items = [];
+        for ($genomicPosition = $this->start; $genomicPosition <= $this->end; ++$genomicPosition) {
+            $items[] = new GenomicPosition($this->chromosome, NucleotidePosition::fromOneBased($genomicPosition));
+        }
+
+        return $items;
+    }
 }

src/NucleotidePosition.php

@@ -0,0 +1,35 @@
+<?php declare(strict_types=1);
+
+namespace MLL\Utils;
+
+class NucleotidePosition
+{
+    public int $value;
+
+    private function __construct(int $oneBasedPosition)
+    {
+        $this->value = $oneBasedPosition;
+    }
+
+    public static function fromOneBased(int $position): self
+    {
+        if ($position < 1) {
+            throw new \InvalidArgumentException("Position must be positive, got: {$position}.");
+        }
+
+        $instance = new self($position);
+
+        return $instance;
+    }
+
+    public static function fromZeroBased(int $position): self
+    {
+        if ($position < 0) {
+            throw new \InvalidArgumentException("Position must not be negative, got: {$position}.");
+        }
+
+        $instance = new self($position + 1);
+
+        return $instance;
+    }
+}

tests/GenomicPositionTest.php

@@ -1,63 +1,71 @@
 <?php declare(strict_types=1);
 
-use MLL\Utils\Chromosome;
 use MLL\Utils\GenomicPosition;
 use MLL\Utils\NamingConvention;
+use MLL\Utils\NucleotidePosition;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 
 final class GenomicPositionTest extends TestCase
 {
     public function testParseUCSC(): void
     {
-        $position = GenomicPosition::parse('chr11:1');
+        $position = GenomicPosition::parseOneBased('chr11:1');
         self::assertSame('chr11:1', $position->toString(new NamingConvention(NamingConvention::UCSC)));
     }
 
     public function testParseEnsembl(): void
     {
-        $position = GenomicPosition::parse('11:1');
+        $position = GenomicPosition::parseOneBased('11:1');
         self::assertSame('11:1', $position->toString(new NamingConvention(NamingConvention::ENSEMBL)));
     }
 
     public function testParseHGVSg(): void
     {
-        $position = GenomicPosition::parse('chr11:g.1');
+        $position = GenomicPosition::parseOneBased('chr11:g.1');
         self::assertSame('chr11:1', $position->toString(new NamingConvention(NamingConvention::UCSC)));
     }
 
     public function testOutputInBothConventions(): void
     {
-        $position = GenomicPosition::parse('chr11:12345');
+        $position = GenomicPosition::parseOneBased('chr11:12345');
         self::assertSame('chr11:12345', $position->toString(new NamingConvention(NamingConvention::UCSC)));
         self::assertSame('11:12345', $position->toString(new NamingConvention(NamingConvention::ENSEMBL)));
     }
 
     public function testEquals(): void
     {
         self::assertTrue(
-            GenomicPosition::parse('chr11:100')->equals(GenomicPosition::parse('11:100'))
+            GenomicPosition::parseOneBased('chr11:100')->equals(GenomicPosition::parseOneBased('11:100'))
         );
         self::assertFalse(
-            GenomicPosition::parse('chr11:100')->equals(GenomicPosition::parse('chr11:101'))
+            GenomicPosition::parseOneBased('chr11:100')->equals(GenomicPosition::parseOneBased('chr11:101'))
         );
         self::assertFalse(
-            GenomicPosition::parse('chr11:100')->equals(GenomicPosition::parse('chr12:100'))
+            GenomicPosition::parseOneBased('chr11:100')->equals(GenomicPosition::parseOneBased('chr12:100'))
         );
     }
 
-    public function testConstructorRejectsNonPositivePosition(): void
+    public function testConstructorRejectsZeroPosition(): void
     {
         self::expectException(\InvalidArgumentException::class);
         self::expectExceptionMessage('Position must be positive, got: 0.');
-        new GenomicPosition(new Chromosome('chr1'), 0);
+        NucleotidePosition::fromOneBased(0);
+    }
+
+    public function testConstructorRejectsNegativePosition(): void
+    {
+        self::expectException(\InvalidArgumentException::class);
+        self::expectExceptionMessage('Position must be positive, got: -1.');
+        NucleotidePosition::fromOneBased(-1);
     }
 
     /** @return iterable<array{string}> */
     public static function invalidFormats(): iterable
     {
         yield ['11:1test'];
         yield ['chr1:0'];
+        yield ['chr1:-1'];
         yield ['chr1:'];
         yield ['chr1'];
     }
@@ -67,6 +75,6 @@ public static function invalidFormats(): iterable
     public function testParseRejectsInvalidFormat(string $value): void
     {
         self::expectException(\InvalidArgumentException::class);
-        GenomicPosition::parse($value);
+        GenomicPosition::parseOneBased($value);
     }
 }