Requesting Awkward 0 → Awkward 1 cheat-sheet

[raymondEhlers]

I've recently started switching over to awkawrd1, and I'd like to create a new array with the same layout (or just shape - I'm not yet sure if different content types are considered different layouts - say int vs float or even int8 vs int32). For example, I have a constant mass hypothesis that I want with every jagged four vector. Or a constant weight for each row. I'm happy to add a concrete example if helpful.

In awkward0, I would call ones_like() and then multiply by my value. For numpy, I would use np.ones_like(...) and again multiply. But having looked through the awkward1 documentation, I can't seem to find the equivalent. As far as I understand, I can't just do this with ak.Array. I'm sure it's possible in awkward1 and that I'm overlooking the right term (I've been reading the awkward1 docs over a number of updates, so it's certainly possible that I've missed it), but some additional documentation on this could be helpful - I imagine that I won't be the only person looking for something like this. Or if it already exists, could you point me in the right direction?

Thanks!

[jpivarski]

Awkward 0's ones_like was an internal method that was technically needed for some things. The ones_like, zeros_like, etc. are useful in NumPy because NumPy's arrays are mutable in-place, but Awkward arrays are immutable—you can only derive new values from old values.

With that in mind, if you want to create a new array with the same structure as the old but all the values have been replaced by something like 5, you can multiply the old array by 0 and add 5. This works because of broadcasting, but broadcasting might also be the reason that you don't actually need an array with all the same values (depends on your problem).

As for documentation, there's already a lot of it in the Python and C++ API references, and the tutorials on awkward-array.org are growing. Where would this go? Maybe a tutorial on broadcasting? The problem might not be "enough documentation" but "finding the one that's needed," since it's hard to know these things have names.

Avoid the shape and dtype properties. They only exist so that Awkward arrays can be Pandas DataFrame columns, and that feature is being removed: see #350. The structure of an Awkward array is characterized by its ak.type.

[raymondEhlers]

Thanks for your detailed response Jim!

Ah, yes, of course - this is the super obvious approach now that you suggest it. I dunno why I didn't use this in awkward0 - I must have had some issues in discovering this, and ones_like() solved the issue, so I just moved on (I also didn't realize that ones_like() was internal). My apologies for the noise on something that is so obvious.

This works because of broadcasting, but broadcasting might also be the reason that you don't actually need an array with all the same values (depends on your problem).

Admittedly I may not have found the most elegant or best solutions, but there were at least a few times with ObjectArrays in awkward0 that I found duplicating values was the only way I could get things working. Perhaps this won't be an issue in awkward1.

The problem might not be "enough documentation" but "finding the one that's needed," since it's hard to know these things have names.

Yes, I agree - I think it's more about discovery. I've read a good deal of the Python API reference and much of it is excellent, but I've struggled at times to find the right terms. I'm certainly empathetic that it's hard to find the right term - I couldn't find the right term here. I think a tutorial on broadcasting would be helpful to address these sort of points.

More generally, even as an awkward0 user who implemented some ObjectArrays for my analysis, etc, there are some changes that are continuing to trip me up (for example, looking for ones_like()). Some docs on what changed from awkward0 to awkward1 could be also be helpful. I think there are bits and pieces of this around either in the docs or in notebooks (so at least I've gathered some heuristics in my mind), but I don't recall it being consolidated anywhere (apologies if I've overlooked it). It could be helpful as a reference for those who are updating. It doesn't need to be encyclopedic, but it feels to me that it's shifted a bit conceptually. And pointing out if common functions changed could be nice (.counts -> ak.num, for example).

I'm still getting up to speed on this, but would be happy to help in any way I can - for example, with feedback (I don't think I understand awkward1 well enough yet to write this myself)

[jpivarski]

I took the liberty of interpreting this as a request for an Awkward 0 → Awkward 1 cheat-sheet. For those users who are coming from Awkward 0, that would maximize discovery.

[raymondEhlers]

Sounds great! Thanks Jim!

[agoose77]

@jpivarski do you think that we still need this in 2022?

[jpivarski]

No, this sounds like a to-do item that gets "done" by waiting so long that it's no longer relevant. We probably have more new users of Awkward 1 than transitioning users of Awkward 0.

Sorry I fell off the ball on this, @raymondEhlers. I'll close the issue.

[raymondEhlers]

No worries at all @jpivarski! You always answer so helpfully and quickly that it makes issues like this quite minor. (Plus, I made the transition years ago). I really appreciate the effort that you and others put into such a useful package!