{'fraction_non_alphanumeric': 0.029453546737380435, 'fraction_numerical': 0.0025570603276825455, 'mean_word_length': 5.230088495575221, 'pattern_counts': {'":': 0, '<': 0, '<?xml version=': 0, '>': 0, 'https://': 3, 'lorem ipsum': 0, 'www.': 1, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
Typesafe Coordinate Systems in High-Throughput Sequencing Applications

High-throughput sequencing file formats and tools encode coordinate intervals with respect to a reference sequence in at least four distinct, incompatible ways. Integrating data from and moving data between different formats has the potential to introduce subtle off-by-one errors. Here, we introduce the notion of typesafe coordinates: coordinate intervals are not only an integer pair, but members of a type class comprising four types: the Cartesian product of a zero or one basis, and an open or closed interval end. By leveraging the type system of statically and strongly-typed, compiled languages we can provide static guarantees that an entire class of error is eliminated. We provide a reference implementation in D as part of a larger work (dhtslib), and proofs of concept in Rust, OCaml, and Python. Exploratory implementations are available at https://github.com/blachlylab/typesafe-coordinates.


Background
Bioinformaticians working in genomics employ a broad variety of file formats to aid in definition, organization, aggregation, and analysis of sequencing data. One universal aspect of myriad formats is the use of coordinates and intervals based on a reference sequence, typically a genome. Troublingly, different standards do not represent coordinates' relationship to the underlying reference sequence uniformly. This discordance among formats which are otherwise frequently used together in workflows is a common stumbling block for junior practitioners, and off-by-one errors may affect even experienced bioinformaticians and computational biologists.
While sequence graphs will play an increasingly important role in the future, [1] the vast majority of sequence analysis work presently operates on coordinate systems with respect to a linear reference. These coordinate systems are defined on the one-dimensional axis of the reference sequence (which is given an integral or string identifier), with sequence intervals describing a range of positions within the reference. These systems inherently rely on two characteristics: the basis (a zero or one indexed counting of the reference sequence), and-when considering intervals-by openness: whether the end coordinate of a range is included or excluded (i.e., whether the interval is closed or open). The Cartesian product of the 2 values each of basis and openness yields four distinct potential coordinate systems (Figure 1).

2
The adoption of different systems across different high-throughput sequencing (HTS) file formats may reflect the format's intended consumer, as a way to optimize understanding, programming logic/arithmetic, or optimal computation. For example, many-but not all-text-based formats intended for human consumption use a 1-based system and are closed with respect to intervals, which may feel more natural to the human reader. On  Unfortunately, the use of alternative systems in different files and application programming interfaces (APIs) which must interoperate sets the stage for subtle off-by-one errors, which are a well-recognized class of problems, but also hard to avoid and sometimes difficult to detect. [2] We propose the use of compilers' type systems to aid bioinformatics software developers and to enforce correctness in a guaranteed way. By applying the principles we describe, the use of a statically typed, compiled programming language for the development of bioinformatics software has the potential to provide these guarantees essentially for free. We provide a reference implementation in D, 3 and proofs of concept in Rust, OCaml, and Python.

Methods
First, we define the possible values of basis as "zero-based" and "one-based", according to whether the first element of the reference sequence is counted from zero or one. Thus, a single coordinate as well as an interval may be "zero-based" or "one-based". Second, we define the possible values of openness as "half-open", in which the end coordinate of the interval is excluded as a member of the range, or "closed", where "closed" means that the end coordinate of the interval is encompassed within the the range. Because coordinates represent an integralnot real-valued index into a sequence, the beginning of a genomic interval is always considered to be closed.
Taking these two values on two axes yields four possible combinations, which we will call and abbreviate as follows: zero- Functions accessing HTS files and records can then be defined to safely take (and return) only the appropriate coordinate/interval type. Passing 6 the wrong coordinate or interval type to a function would thus result in a compile-time error. Alternatively, shifting the burden from library consumer to producer, functions could be defined polymorphically so as to take coordinates or intervals of any type, as long as they include an initial conversion to the correct type within the function body.
We implemented a typesafe coordinate system in the D language using parametric polymorphism on top of our existing dhtslib [3]

Results
We created dhtslib,[3] a collection of high-level abstractions, convenience functions, and bindings over the widely-used and low-level htslib C li-brary. [4] At a high level, dhtslib provides object-oriented readers and writers for BAM/CRAM/SAM, BCF/VCF, BED, and GFF3 with support for region-based queries and filtering via standard indexes.
To effectively deal with the problem of different coordinate systems across these file formats, read and write functions take and receive only typesafe coordinates as described above, which effectively guarantees correctness at compile-time. Through the use of parametric polymorphism and metaprogramming, these readers' and writers' function parameters may be coordinate intervals of any type, and are automatically converted -at compile timeto the requisite representation for the format in question. Thus, coordinates and ranges from one file acquired via the dhtslib API may be directly and transparently passed to another file, whether or not the two share a common coordinate system, and without any specific intervention on the library user's part.
As a concrete example, consider reading a coordinate range encompassing a gene or exon of interest from a GFF3 gene annotation file. In a typesafe coordinate system-enabled library such as dhtslib, the return value of any GFF3 reader will be of a type encoding its one-based closed (OBC) nature.
Suppose then that the software must query a BAM file for alignments falling within the range just queried. In a typesafe coordinate system, the prior result can be passed directly to query function which is generic over the type of input coordinates and at compile time has logic injected to perform any necessary conversion of basis and/or openness.
A pseudocode excerpt is shown below. In this way, a developer using dhtslib (and by extension htslib) needn't explicitly be aware of the coordinate space that they receive from one file type or know what coordinate system it should be converted to for use with another file type or API. From dhtslib version 0.12.0 onward, the Typesafe Coordinate System is enforced for all high-level interfaces.
We also explored the feasibility of Typesafe Coordinates in other statically-

Discussion
Software engineering and bioinformatics are relatively newer disciplines among the applied sciences. In the same way that other engineering fields may apply and benefit from fundamental advances in mathematics and physics, the integrity, safety, and performance of software systems can be improved by applying lessons from computer science. These principles have also made their way to bioinformatics and computational biology, where authors have recognized the Rust language (https://www.rust-lang.org) for its mem-ory safety attributes and its potential contributions to safer and more correct bioinformatics tools. [5,6] Here, we demonstrate that leveraging the type system and compile-time guarantees of strongly typed languages like D, Rust, and others can reduce the error surface of software in the computational biology and bioinformatics space. These principles could also be extended to more loosely typed language such as Python, albeit with much weaker guarantees and a runtime overhead.
The reference implementation of Typesafe Coordinates as part of dhtslib [3] -to our knowledge the first such polymorphic implementation of this concept in any bioinformatics tooling -is written in D (https://dlang.org/), a statically-typed, compiled language. We found D's compile-time introspection and metaprogramming features ideal for construction of such a system.
We also implemented Typesafe Coordinates in other languages, including Rust, OCaml, and Python, albeit with language-specific limitations in each of these.
In the thrall of safety, dhtslib does not permit circumvention of the system by accepting integer coordinates directly in functions that operate on files or records. This ensures that a software developer cannot create a situation involving off-by-one errors without specific and significant effort. Importantly, this safety is statically guaranteed and therefore comes without any runtime branching penalty. In the case that coordinates must be hardcoded or accepted as untrusted user input, type constructors accept integers, 13 and the explicit initialization of a named type carries distinct advantages.
First, it forces the developer in these cases to be sure about the coordinate system (depending on the data's downstream use). Second, it is implicitly self-documenting. Finally, correctness (or lack thereof) of the coordinates is deterministically transmitted through the call chain and program flow, simplifying debugging.
In conclusion, we have introduced the concept of Typesafe Coordinate Systems for bioinformatics and computational biology, and provided a reference implementation as part of a larger and more comprehensive highthroughput sequencing package dhtslib. We have also provided additional proofs-of-concept in various languages including Rust, an emerging language for bioinformatics. We hope that these safety concepts will be adopted by others and implemented either as standalone packages (leveraging macros and metaprogramming), or directly integrated into popular libraries and packages such as SeqAn, [7] BioPython, [8], Rust-Bio, [5] and hts-nim. [9] Using type systems to eliminate error in specific problem domains is a powerful safety concept and should become routine in bioinformatics.