Document migration steps from 3.x to 4.x

[luizirber]

Can be on the changelog, or in another document linked to it.

current document here, https://hackmd.io/KktN0rK0SHqbbZoKsRwBmw

will eventually be part of #1283

[ctb]

perhaps we can suggest that people using the Python API should install the last 3.x release and look for deprecation warnings? I don't really like the thought of bothering to document all of the Python API changes in detail.

the big things to document in my mind are the "invisible" CLI changes, like "lca summarize now is abundance weighted." I don't think most people will read those in detail, but we should do them anyway.

[ctb]

In #1129, note:

The only tricky bit here for migration is that the user will need to choose similarity or jaccard in the future.

similarity is the more general code that does Jaccard calculations on MinHashes w/o abundance or angular similarity on MinHashes with; jaccard is a method that always ignores abundance.

[ctb]

see comments in #1128 (comment) around turning deprecations and future warnings into errors.

[ctb]

For #1178, changes in --traverse-directory behavior:

• minor impact, error messages will happen appropriately. To fix:
• to migrate CLI, remove --traverse-directory from your command line invocations
• to migrate Python code, remove traverse argument from calls to sourmash_args.load_dbs_and_sigs(...), .load_file_as_index(...), and .load_file_as_signatures(...)

For #1175, changes in lca summarize behavior:

• major changes in command line behavior: no longer merges provided signatures, and by default weights output by abundances in query sig;
• major change in command line output: a new column, filename, is in the CSV output.
• to migrate CLI: for old behavior, merge signatures before calling lca summarize using sourmash sig merge, and use --ignore-abundance;
• to migrate parsing code: use --singleton to generate new-style output, and/or make sure your parsing code handles (or properly ignores) the second column named filename

[bluegenes]

#1186 makes signatures arg optional for index, which impacts argument positioning:

• positional args must now be ordered properly: first the index name, then zero or more signature files.
• to fix failing tests/code, change the order of args provided to index.

[ctb]

#1179 changes the way we output signature names --

• use str(sig) instead of sig.name

[luizirber]

#1229 removed 10x support, point users to kmermaid (as discussed in #1159 (comment))

[ctb]

#1128

• get_mins -> hashes
• downsample(...) changes
• is_molecule_type deprecated

[ctb]

#1279

In particular,

• sourmash.load_signatures to sourmash.load_file_as_signatures
• note that sourmash.load_file_as_signatures doesn't take a string as possible input any more; need to use internal API, sourmash.signature.load_signatures.
• deprecates create_sbt_index and load_sbt_index at top level.

[ctb]

will be added in #1316 and #1283.

[ctb]

Closed in #1283.