Stdpopsim: CLI vs API syntax chromosome

[agladstein]

I just noticed that the CLI syntax is --chromosome, while the API syntax is contig. Is there a reason for this? Might be a little confusing for users.

[jeromekelleher]

No, probably no good reason for this. We should probably change the CLI to use contig (but keep chromosome as an alias).

What do you think @grahamgower?

[grahamgower]

I see why this seems inconsistent, but I'm not so sure it is. Looking at the canonical API example docs/examples.py:
https://github.com/popsim-consortium/stdpopsim/blob/8a813621d808697da91b7cb896e8e82320ff0aa7/docs/examples.py#L11-L17

And the docs for Species.get_contig():
https://github.com/popsim-consortium/stdpopsim/blob/8a813621d808697da91b7cb896e8e82320ff0aa7/stdpopsim/species.py#L154-L175

What we do at the CLI matches the call to get_contig(), in the sense that one can request a chromosome, a genetic_map, and a length_multiplier. The CLI just hides the "get contig" action. If we wanted more consistency and added a --contig CLI option, it would more correctly take three parameters.

[agladstein]

I don't get it. How are they different?

[grahamgower]

CLI:

$ stdpopsim HomSap --chromosome chr22 --genetic-map HapMapII_GRCh37 --length_multiplier 0.1 10

API:

species = stdpopsim.get_species("HomSap") 
contig = species.get_contig(chromosome="chr22", genetic_map="HapMapII_GRCh37", length_multiplier=0.1)
model = stdpopsim.PiecewiseConstantSize(species.population_size) 
samples = model.get_samples(10)
...

Although the first argument to get_contig() is allowed to be used without the keyword (i.e. chromosome="chr22" can be written "chr22"). But when you use the keyword version, the API and CLI look quite consistent to my eyes.

I don't have any strong opposition to including --contig as a CLI alias for --chromosome. But I wouldn't consider this to be more consistent with the API, because the --contig option below is only taking a single parameter (whereas get_contig() can take three).

$ stdpopsim HomSap --contig chr22 --genetic-map HapMapII_GRCh37 --length_multiplier 0.1 10

Is using --chromosome at the CLI really going to confuse users?

[agladstein]

I see, I see. I think as a user both --chromosome and contig make sense independently. It's just that when switching from CLI to API or vs versa you would probably think the syntax would be the same.
I think we'll see from the workshop and when more people start using it if there is any confusion.
I'm going to leave the issue open for a bit after the workshop to see if there is any confusion about that.