Why a Living Repository¶
I did not write PoolSeqFlow to accompany a paper. The tool, and this manual explaining the reasoning inside it, are the publication. That is a deliberate choice and this page is the argument for it, along with how it changes the way I work.
A study is finished by design; the methods underneath it are not¶
When a study goes into a journal it stops. It is correct as of its publication date and it stays that way — the analysis frozen, the software version frozen, the statistics frozen at whatever the field was doing that year. That is fine for a record of what was observed. It is not fine for the methods, because the methods keep moving. I read papers now about how to combine evidence across replicated experiments that describe approaches which simply did not exist when I was learning this work, and any study that used the old approach is still sitting there using it.
I want my science to stay alive rather than stop at the moment I published it. A result belongs to when it was produced. A method should not.
The clearest illustration is a tool most people in this field have used. PoPoolation is among the most widely cited pool-seq toolkits there is, and it has been essentially untouched for over a decade. Every project still running it is running that decade's statistics, and there is nothing wrong with the software — it does what it always did. The problem is that it was finished, and the field was not.
So the tool is the thing I maintain, and the tool is the thing I publish¶
A repository can do what a paper cannot: it can be corrected. If an estimator here turns out to be the wrong one, or a better one is published next year, the right response is to change it and say what changed — not to leave it in place because the paper describing it is already in print.
That is not a slogan, it is a design constraint, and it is why the analysis layer is built the way it is. Each analysis is a module with its own version, its own citations and its own tests, and modules are published separately from the pipeline. A statistic can be replaced without rewriting anything around it. That seam is the mechanism that makes "maintained" a real claim rather than a promise about my future attention — and because a module is separately versioned and separately published, someone else can ship one without waiting for me.
The obligation that comes with it is that an old result must still be explicable. Every run records the versions it ran under and every published analysis records the module and the settings that produced it, so using a current method and reproducing an old number are not in tension.
Why this is not going to a journal¶
I have lost confidence in scientific publishing as a system. I do not think paying several thousand dollars in article-processing charges to be reviewed by only a few people is what makes work valuable. This model creates an unfair system where the research from countries with limited resources goes unnoticed just because publishing wall. The code is here, the reasoning is here, and the evidence is here. People can use it if they believe this is the right tool, or leave it behind if they believe the science is not convincing. Using this method is a decision on the merits, not by two reviewers and one editor, but by the community.
I am aware that I am in a position to say all these and take a stance, and not everyone is. That is exactly why I am saying it. If someone with the freedom to take the risk does not demonstrate that the alternative exists and works, then nothing changes and we all keep paying for the privilege of being read.
This is not a refusal to publish. I publish research through the ordinary channels when the work calls for it, and a preprint of this may follow once it is more complete rather than in heavy progress. What I am refusing is the idea that the being published in a "respected" journal is what makes it real.
The same reasoning applies to working in the open. The reflex to keep a project hidden until it is finished, in case someone takes the idea, mostly just slows everything down. During my PhD I discussed my experiment freely while it was running — seventy populations, a thousand to two thousand flies in each, carried five generations — because the honest answer was that nobody else was going to run it. Do something that is hard to do, rather than something you have to hide. It is not 1920. Either we build a different way of doing this or we miss it entirely.
How I decide things¶
I do not settle design questions by argument when I can settle them with data. The depth-cutoff detector in this pipeline had two candidate algorithms and a long discussion behind it, and the discussion was going nowhere. Building twenty synthetic depth distributions — a few clean, the rest deliberately pathological — and looking at what each design did to them ended it in minutes. Two designs died on contact with cases that no amount of reasoning had produced.
I keep those distributions in the test suite rather than in a notebook, so the evidence stays executable. That is the general form of it: when I decide something on the basis of data, the data becomes part of the repository, and anyone who thinks the decision is wrong can re-run it, and propose a better alternative, if exists. This is a living project and it will only grow with feedback.
The other half is that theory has to survive contact with a real dataset. Pool-seq has plenty of estimators that are correct on paper and weak on data — because coverage is not homogeneous, because pools are not the same size, because a "reference" allele is an accident of which genome got sequenced first. Where this pipeline departs from a published formula, it is usually because the published formula assumes something a real experiment does not provide, and the manual says so at the point where it matters.
Who this is for¶
Pool sequencing is unfortunately underused outside a handful of model systems. The method itself does not care whether the organism has a reference-quality genome, a large research community or a commercial kit behind it — it works on populations, which covers a lot of biological studies. What stops people is almost never the biology. It is that the tooling makes assumptions on the data type because it was created to analyze a certain type of organism or expects a bioinformatician on the team. Creating a model-agnostic tool is a challenge and I accept the probability that I might have missed some use cases. If so bring it up, I like a good challenge to make the tool more accessible.
So accessibility is not a nice-to-have here, it is the point. A tool only its author can install and interpret is not a tool. That is why the pipeline checks its environment and explains what it is checking, why a configuration can be carried forward across releases instead of rewritten, why there is a preview that shows what a run will produce before it produces it, and why this manual explains what a number means rather than only which flag produces it.
What I am not claiming¶
- That this is finished. It is not. The point of the form is that it never quite will be.
- That maintenance is guaranteed. It is not. I am developing this in my free time with my own resources as they allow me, which is why the module seam matters more than my intentions.
- That any of it is a substitute for understanding the analysis. The pipeline can refuse a configuration that cannot be right, but it cannot tell you what your results mean in the biological context.