addition to Further Topics: Aux Factories and their Creation

[acchamber]

📚 Documentation

There's no documentation currently on how to use the iris.aux_factory module at the moment, either on creation of new factories or how to work with them in cubes. Seems a fitting topic for a Further Topics section?

See related discussion https://github.com/SciTools/iris/discussions/4780_

[trexfeathers]

Thanks @acchamber. We consider Aux Factories to be among the most complex pieces of Iris' public API, with only a few niche uses, hence why we so far haven't gone beyond writing API docstrings.

Do you have some examples of when people want to use Aux Factories? It may be that the documentation should simply advise NOT using them (!), but we'd need to know more to be sure.

[acchamber]

So, the reason I had to figure out how to create them was that I had some grib data that is in model-level format, and I needed to feed it into a suite that required input data to have a hybrid-pressure coordinate. The grib cube came with the level pressure and sigma data as coordinates and I have another cube with the surface pressure data, so had to figure out the exact syntax to add the the hybrid pressure factory to my input data.

You can see an example of this in a notebook in my user directory - /h05/achamber/ERA5_downscale/axufactory_test.ipynb

[trexfeathers]

@acchamber thanks for the extra info

Outcomes of latest discussion:

• We should improve comments in the code to make it more follow-able
• We agree that a Further Topics page, including a worked example, would be valuable. @acchamber if you have an idea for the content, we'd be happy to review a pull request from you. Does that sound OK?

[acchamber]

@trexfeathers That sounds great. I don't know when I'll be able to get around to it, but my hope is this summer to do so (along with the other topics I've raised)

[github-actions[bot]]

In order to maintain a backlog of relevant issues, we automatically label them as stale after 500 days of inactivity.

If this issue is still important to you, then please comment on this issue and the stale label will be removed.

Otherwise this issue will be automatically closed in 28 days time.

[github-actions[bot]]

This stale issue has been automatically closed due to a lack of community activity.

If you still care about this issue, then please either:

• Re-open this issue, if you have sufficient permissions, or
• Add a comment stating that this is still relevant and someone will re-open it on your behalf.