From 43cad547ba163fc33ed18d4902f4a55aeadabd82 Mon Sep 17 00:00:00 2001 From: Jerome Kelleher Date: Wed, 18 Dec 2019 17:09:59 +0000 Subject: [PATCH 1/4] Added installation docs. Closes #147 --- docs/installation.rst | 85 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 84 insertions(+), 1 deletion(-) diff --git a/docs/installation.rst b/docs/installation.rst index 934e628ba..dbe995bb1 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -4,6 +4,89 @@ Installation ============ +There are two basic options for installing ``stdpopsim`` and its dependencies: either +using :ref:`sec_installation_conda` or :ref:`sec_installation_pip`. +We recommend conda for most users (particularly those using OSX or Windows), +although pip can be more convenient in certain cases. + +.. _sec_installation_requirements: + +************ +Requirements +************ + +Library requirements for stdpopsim should be installed automatically when using +either conda or pip. + +Stdpopsim requires Python 3.5 or later. + + +.. _sec_installation_conda: + +***** +Conda +***** + +.. todo:: The conda package for stdpopsim is currently under development and will + be available shortly. Please use pip for now. + + +.. _sec_installation_pip: + +*** +Pip +*** + +Installing using pip is usually as simple as:: + + $ python -m pip install stdpopsim --user + +This will install ``stdpopsim`` into your local user Python packages +(on some systems you will need to use ``python3`` rather than +``python``). Please see the Python `package installation +`_ +tutorial for more details on the various installation options. In particular, +we recommend using a `virtual environment +`_ +to improve reproducibility. + +It may also be necessary to update your PATH to run the command +line interface. See `here +`_ +for details on what this means and how to do it. + +We use `msprime `_ as the +default simulation engine, which has some system level dependencies +and requires a functioning compiler. Please see the msprime +`installation documentation +`_ for +instructions if you encounter errors during installation. + +.. _sec_installation_running_cli: + +*************** +Running the CLI +*************** + +After installation is complete it should be possible to run the +:ref:`command line interface `. This can be done in one +of two ways: + +1. The most reliable way is to use :: + + $ python -m stdpopsim + + Once the ``python`` executable is the same one as was used when installing + ``conda`` or ``pip``, this is guaranteed to work. + +2. It is also possible to run ``stdpopsim`` like a regular Unix program + using:: + + $ stdpopsim + + However, this requires that your `PATH `_ + environment variable contains the directory where conda or pip installed the + executable. Please see the specific documentation on these methods above for + details on how to do this. -.. todo:: Add installation docs. Should be as simple as ``pip install stdpopsim``. From f2fd2c93cbb14599e086d27a70dbc89cbea08744 Mon Sep 17 00:00:00 2001 From: Jerome Kelleher Date: Wed, 18 Dec 2019 17:51:40 +0000 Subject: [PATCH 2/4] Change species/model summary to field list. Closes #294 --- docs/_ext/speciescatalog.py | 112 ++++++++++++------------------------ docs/docutils.conf | 5 ++ 2 files changed, 41 insertions(+), 76 deletions(-) create mode 100644 docs/docutils.conf diff --git a/docs/_ext/speciescatalog.py b/docs/_ext/speciescatalog.py index b9a8ce2c3..f50e8e4f3 100644 --- a/docs/_ext/speciescatalog.py +++ b/docs/_ext/speciescatalog.py @@ -45,86 +45,46 @@ def get_target(self, tid): self.state.document.note_explicit_target(target) return target - def species_summary_table(self, species): - table = nodes.table() - tgroup = nodes.tgroup(cols=2) - colspec = nodes.colspec(colwidth=1) - tgroup.append(colspec) - colspec = nodes.colspec(colwidth=1) - tgroup.append(colspec) - colspec = nodes.colspec(colwidth=1) - tgroup.append(colspec) - - table += tgroup - - data = [ - ("id", species.id, ""), - ("name", species.name, ""), - ("generation_time", species.generation_time, - "TODO: Notes for generation_time"), - ("population_size", species.population_size, - "TODO: Notes for population_size"), - ] - - rows = [] - for row_data in data: - row = nodes.row() - rows.append(row) - for entry_data in row_data: - entry = nodes.entry() - entry += nodes.paragraph(text=entry_data) - row += entry + def make_field_list(self, data): - tbody = nodes.tbody() - tbody.extend(rows) - tgroup += tbody + field_list = nodes.field_list() + for name, text, citation in data: + field = nodes.field() + field_name = nodes.field_name(text=name) + field_body = nodes.field_body() + para = nodes.paragraph(text=text) - return table + if citation is not None: + text = f" ({citation.author}, {citation.year})" + para += nodes.reference( + internal=False, refuri=citation.doi, text=text) - def model_table(self, model): - table = nodes.table() - tgroup = nodes.tgroup(cols=2) + field_body += para + field += field_name + field += field_body + field_list += field - colspec = nodes.colspec(colwidth=1) - tgroup.append(colspec) - colspec = nodes.colspec(colwidth=1) - tgroup.append(colspec) + return field_list - table += tgroup - - rows = [] - row = nodes.row() - rows.append(row) - entry = nodes.entry() - entry += nodes.paragraph(text="ID") - row += entry - entry = nodes.entry() - entry += nodes.paragraph(text=model.id) - row += entry - - row = nodes.row() - rows.append(row) - entry = nodes.entry() - entry += nodes.paragraph(text="Description") - row += entry - entry = nodes.entry() - entry += nodes.paragraph(text=model.description) - row += entry - - row = nodes.row() - rows.append(row) - entry = nodes.entry() - entry += nodes.paragraph(text="Num populations") - row += entry - entry = nodes.entry() - entry += nodes.paragraph(text=model.num_populations) - row += entry - - tbody = nodes.tbody() - tbody.extend(rows) - tgroup += tbody + def species_summary(self, species): + data = [ + ("ID", species.id, None), + ("Name", species.name, None), + ("Common name", species.common_name, None), + ("Generation time", species.generation_time, + species.generation_time_citations[0]), + ("Population size", species.population_size, + species.population_size_citations[0]), + ] + return self.make_field_list(data) - return table + def model_summary(self, model): + data = [ + ("ID", model.id, None), + ("Description", model.description, None), + ("Num populations", model.num_populations, None), + ] + return self.make_field_list(data) def citation_list(self, citable): bullet_list = nodes.bullet_list() @@ -411,7 +371,7 @@ def model_section(self, species, model): section += nodes.title(text=model.description) section += nodes.paragraph(text=model.long_description) section += nodes.rubric(text="Details") - section += self.model_table(model) + section += self.model_summary(model) section += nodes.rubric(text="Populations") section += self.population_table(model) section += nodes.rubric(text="Citations") @@ -427,7 +387,7 @@ def run(self): species_target = self.get_target(sid) section = nodes.section(ids=[sid], names=[sid]) section += nodes.title(text=species.name) - section += self.species_summary_table(species) + section += self.species_summary(species) genome_section = nodes.section(ids=[f"sec_catalog_{species.id}_genome"]) genome_section += nodes.title(text="Genome") diff --git a/docs/docutils.conf b/docs/docutils.conf new file mode 100644 index 000000000..58feea34d --- /dev/null +++ b/docs/docutils.conf @@ -0,0 +1,5 @@ +# This is used to make sure that we don't split lines when field names +# are long in the speciescatalog extension. See +# https://stackoverflow.com/questions/13029207/overriding-the-default-field-name-limit-in-sphinx-docutils +[html4css1 writer] +field_name_limit: 40 From b7b318f26547546d5cafc02a81af216c3046a916 Mon Sep 17 00:00:00 2001 From: Jerome Kelleher Date: Wed, 18 Dec 2019 18:10:11 +0000 Subject: [PATCH 3/4] Fixup IDs in the documentation. Closes #336 --- docs/catalog.rst | 2 +- docs/tutorial.rst | 18 +++++++++--------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/catalog.rst b/docs/catalog.rst index 5e4052af8..a4fcb1f26 100644 --- a/docs/catalog.rst +++ b/docs/catalog.rst @@ -29,7 +29,7 @@ and saves the output to a file called ``test.trees``: .. code-block:: console - $ stdpopsim HomSap -c chr22 -o test.trees -g HapmapII_GRCh37 --model ooa_3 2 2 2 + $ stdpopsim HomSap -c chr22 -o test.trees -g HapMapII_GRCh37 --model OutOfAfrica_3G09 2 2 2 (To learn more about using ``stdpopsim`` via the command-line, read our :ref:`sec_tutorial` about it.) diff --git a/docs/tutorial.rst b/docs/tutorial.rst index e4993b891..b7b859102 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -70,7 +70,7 @@ This gives all of the possible demographic models we could simulate. We choose the two population out-of-Africa :ref:`model ` from `Tennesen et al. (2012) `_ . By looking at the model help we -find that the name for this model is ``ooa_2`` and that we can specify it using +find that the name for this model is ``OutOfAfrica_2T12`` and that we can specify it using the ``--model`` option. We choose to draw two samples from the African population and three samples from the European population. To increase simulation speed we can also chose to simulate a sequence a fraction of the @@ -81,7 +81,7 @@ uniform recombination map. The command now looks like this: .. code-block:: console - $ stdpopsim HomSap -c chr22 -l 0.05 -o foo.ts --model ooa_2 2 3 + $ stdpopsim HomSap -c chr22 -l 0.05 -o foo.ts --model OutOfAfrica_2T12 2 3 Note that there are now two numbers after the model option. This is because the model simulates two populations so we have to specify a number of samples to @@ -98,14 +98,14 @@ the ``-l`` option. (NOTE: this may a minute or so to run). .. code-block:: console - $ stdpopsim HomSap -g HapmapII_GRCh37 -c chr22 -o foo.ts --model ooa_2 2 3 + $ stdpopsim HomSap -g HapMapII_GRCh37 -c chr22 -o foo.ts --model OutOfAfrica_2T12 2 3 For reproducibility we can also choose set seed for the simulator using the ``-s`` flag. .. code-block:: console - $ stdpopsim HomSap -s 1046 -g HapmapII_GRCh37 -c chr22 -o foo.ts --model ooa_2 2 3 + $ stdpopsim HomSap -s 1046 -g HapMapII_GRCh37 -c chr22 -o foo.ts --model OutOfAfrica_2T12 2 3 Lastly, the CLI also outputs the relevant citations for both the simulator used and the resources used for simulation scenario. @@ -262,8 +262,8 @@ This prints detailed information about all of the available models to the terminal. In this tutorial, we will use the model of African-American admixture from `2011 Browning et al `_. -From the help output (or the :ref:`Catalog `), -we can see that this model has id ``america``, +From the help output (or the :ref:`Catalog `), +we can see that this model has id ``AmericanAdmixture_4B11``, and allows samples to be drawn from 4 contemporary populations representing African, European, Asian and African-American groups. @@ -272,7 +272,7 @@ are available: .. command-output:: stdpopsim HomSap --help-genetic-maps -Let's go with ``HapmapII_GRCh37``. +Let's go with ``HapMapII_GRCh37``. The next command simulates 4 samples of chromosome 1 from each of the four populations, and saves the output to a file called ``afr-america-chr1.trees``. For the purposes of this tutorial, we'll also specify a random seed using the @@ -281,8 +281,8 @@ For the purposes of this tutorial, we'll also specify a random seed using the .. code-block:: console - $ stdpopsim HomSap -c chr1 -o afr-america-chr1.trees -s 13 -g HapmapII_GRCh37\ - --model america 4 4 4 4 + $ stdpopsim HomSap -c chr1 -o afr-america-chr1.trees -s 13 -g HapMapII_GRCh37\ + --model AmericanAdmixture_4B11 4 4 4 4 -------------------------- 2. Calculating divergences From b6e94f4c3081f00e661a4bb332b1ef16506b0bac Mon Sep 17 00:00:00 2001 From: Jerome Kelleher Date: Wed, 18 Dec 2019 18:13:51 +0000 Subject: [PATCH 4/4] Final updates for 0.1.0. --- CHANGELOG.rst | 2 +- setup.py | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 600a904d3..61f983cbf 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,5 +1,5 @@ -------------------- -[0.0.0] - 2019-XX-XX +[0.1.0] - 2019-12-18 -------------------- Initial release. diff --git a/setup.py b/setup.py index b86e0ef97..57d5d696e 100644 --- a/setup.py +++ b/setup.py @@ -8,7 +8,7 @@ setup( name='stdpopsim', - description='Standard simulation models for msprime', + description='A library of population genetic simulation models', long_description=long_description, author='PopSim Consortium', # TODO probably should have a different email address? @@ -33,10 +33,10 @@ }, # NOTE: make sure this is the 'attrs' package, not 'attr'! install_requires=["msprime", "attrs", "appdirs", "humanize"], - url='https://github.com/popgensims/stdpopsim', + url='https://github.com/popsim-consortium/stdpopsim', project_urls={ - 'Bug Reports': 'https://github.com/popgensims/stdpopsim/issues', - 'Source': 'https://github.com/tsckit-dev/stdpopsim', + 'Bug Reports': 'https://github.com/popsim-consortium/stdpopsim/issues', + 'Source': 'https://github.com/popsim-consortium/stdpopsim', }, license="GNU GPLv3+", platforms=["POSIX", "MacOS X", "Windows"],