Adding weightHP query option to functions

[umayaml]

Adding weightHP query option to fetch_shortest_paths and fetch_simple_connections, etc.

See #25

TODO

The following functions will all need to be updated to support a high-precision option.

• fetch_adjacencies()
• fetch_traced_adjacencies()
• fetch_simple_connections()
• fetch_common_connectivity()
  • Add roi parameter, too.
  • Fix pre-existing bug (see below).
• fetch_shortest_paths()
• fetch_output_completeness()
• fetch_downstream_orphan_tasks()
  • Let's not bother with this one for now.

Updating the following functions will require a more significant change to the API, since they don't use weightHP. They inspect synapses individually, but I think it would be best to aim for conceptual consistency with the above functions if possible. Perhaps these updates should be deferred for now, and implemented in a separate pull request.

• fetch_synapse_connections()
• fetch_connection_mitochondria()

Documentation updates:

• Update docstrings for all edited functions.
• Update docs/source/changelog.rst
• Maybe add a new entry in docs/source/faq.rst?

[stuarteberg]

Thinking about this a little more...

Right now, the neuprint datamodel only provides weight and weightHP, but soon we'll be introducing weightHR. To future-proof this API for those changes, perhaps we should rename the argument to weight_tuning (or a better name if you can think of one). Instead of True/False, it would accept a string, which must be either default, high-precision, or (eventually) high-recall.

Also, as a side note, I'm wondering if we should make this new argument a keyword-only argument, just to avoid breaking existing code that calls it using the current argument order.

On a related point, apparently fetch_common_connectivity() contains a pre-existing bug, because it calls fetch_simple_connections() with the wrong arguments. Can you fix that while you're at it?

And on a related point to that: I think fetch_common_connectivity() should probably be updated to accept the new weight_tuning argument, and (now that I think about it) also an roi argument.

[stuarteberg]

I've edited the PR description above to add a TODO checklist.

Thanks again for posting this draft PR immediately for the first two functions (as we discussed), rather than implementing everything in one go. This gives us a chance to nail down some API details before you change all of the relevant functions.

[stuarteberg]

@umayaml I reorganized the contents of queries.py, splitting it across multiple files. When you come back to this PR, you should rebase from the current master branch (or start over).