disambiguate assembly chains by appending assembly id

[alex-hh]

Biotite doesn't currently distinguish between the chains produced by symmetry operations on a given asym unit in an assembly.

This can make certain selection operations slightly inconvenient (e.g. getting residue starts of a specific chain etc.) and is inconsistent with the chain naming convention employed by the PDB in assembly .cif files.

This PR follows the PDB convention of appending a '-<oper_id>' to the chain ids.

[padix-key]

Hi. First I thought that this is the same as #389, but while separating chains is also possible without changing the AtomArray annotations, this is not true if one wants to have all chains for a specific symmetry operation. So I see definitely the use case for this feature.

However, I am leaning towards keeping the original chain_id annotation here, as it represents the asym_id from the atom_site category. I think in the assembly CIF files they go this route, because they have no other way of representing this while keeping the file compatible with the PDBx dictionary.

Instead I propose to add an additional optional annotation array (what do you think about sym_id?) that tracks this information instead. Similar to the appended number in your draft it would go from 0 to N. If a user still wants to have this information in the chain_id, they could concatenate chain_id with sym_id via numpy.strings.add().

As a pointer, have a look at set_annotation() in the AtomArray class, for how to add a custom annotation.

[Croydon-Brixton]

I'd also be in favour of a separate sym_id annotation.

The one caveat I'd have is that some symmetry operations are actually 'slicing' type operations rather than copying operations, so if we wanted to add a sym_id to the asym unit we would need to decide whether we assign sym_id's based on the operation id or whether we want to assign them based on actual chemical similarity. (See 5ocm for an example). Personally I'd lean towards just using the oper_id as you suggested, @alex-hh

[alex-hh]

Hi - Thanks for the pointer to the previous issue, this also helps with some of the use cases I was considering.

Making sym_id an optional annotation makes sense to me.

I've updated the PR with one possible solution for the sym_id (concatenation of the oper ids applied to generate the sym unit), but agree it's not obvious what the value should be. I was trying to follow the convention from the assembly.cif files, but I'm not sure what they do in complex cases there.

[padix-key]

Having sym_id concatenate the different operation IDs would also be OK for me. I suspect there are no strctures where a high number of these operations are combined

[padix-key]

Hi, I would recommend a few small changes, but overall it looks good!

[alex-hh]

updated!

[codspeed-hq]

CodSpeed Performance Report

Merging #700 will not alter performance

_{Comparing alex-hh:disambiguate-assembly-chains (92f6834) with main (0acb143)}

Summary

✅ 47 untouched benchmarks

[padix-key]

I took the freedom to add some tests and documentation about the new annotation. Have a look of you like. From my side this would be ready to merge, when the discussion above is resolved.

[padix-key]

I'll merge the PR now. Thanks again @alex-hh for implementing it and to @Croydon-Brixton and @nscorley for the feedback!

[Croydon-Brixton]

Always a pleasure! Thank you for all the great work on biotite!