Request for a high level overview of what works and what doesn't.

[pkvamme]

Apologies for raising all these questions as an issue. If there is a better forum for questions like this, please let me know.

This is not meant as complaints about missing features in an otherwise great product. What I am trying to do is to understand the current status. Some of the answers might be "Sure you can do this; just read the documentation better". Or, "This is so complicated that you are better off just waiting for us to implement".

• Is mdio v0.9 no longer supported and not recommended to use at all?

• Is mdio v1 considered stable enough for production use?

• Confirm: When you update documentation from v0.9 to v1, the changes seem to become visible in the "stable" readthedocs in spite of that being tagged v0.9.3. There is no pulldown that lets me switch to v1. Note: If I am wrong and I have been missing out of many documentation updates then some of my other questions might have been answered...

• Can somebody provide a precise list of 3rdparty package versions that is known to work together? E.g. just the output of "pip freeze" for both v0.9 and v1. I have not bee able to find a combination of package versions that doesn't crash ever so often. At least not for v0.9. Should I have fsspec==2024.10.0? Or not?

• Is there a create_empty() function and example usage for v1? If not, is there example code anywhere that shows how to create and write mdio using a presumably lower level api? I found two branches belonging to Dmitriy Repin that both add create_empty() but neither seem to have been merged. I don't know whether that code would just confuse me if I tried to use it. See pull request 687 and pull request 736

• Is there a high level api to do coordinate conversion from (inline,crossline) to (world_x, world_y)? Issue 112 already indicates that something is missing. I am trying to understand what I need to do to get this to work.

• Confirm: Dealing with world coordinates in v0.9 requires knowledge of which Seg-Y dialect was used when ingesting using "mdio segy import". Specifically, where in the trace headers are the world coordinates? This is not an issue in v1 as far as I can see.

• Confirm: If I need a matrix for converting (il,xl) to world(x,y) then I need to extract this information myself from the Seg-Y headers. This is simple for a rectangular survey with no dead traces. I would just look at the 4 corner points. For oddly shaped surveys it gets trickier. Depending on how pedantic I need to be.

• Confirm: After calculating the matrix, I cannot store it as such in the mdio file. The only way to store world coordinates is to store the 240-byte Seg-Y trace header for every trace in the survey. Even if the data to be written wasn't originally read from Seg-Y.

• Confirm: The v1 example code for ingesting teapot ends up with the world coordinates being wrong by a factor of 10. The reason is that teapot has stored the world coordinates both as unscaled integers and as int(coordinate*10). The MDIO code knows that it should (in this case) divide by 10. So it should be using offset 73 and 77.

Name in Seg-Y rev1	Offset in rev1	What Teapot stores here
cdp_x, cdp_y	181, 185	Inline,Crossline
inline, crossline	189, 193	Unscaled world X,Y
source_coord-{x,y}	73, 77	Scaled world X,Y
group_coord-{x,y}	81, 85	Scaled world X,Y

[BrianMichell]

Hi, thanks for taking the time to share all of your questions here. I'll do my best to answer them but please feel free to follow up on any questions, comments, or concerns you may have!

Is mdio v0.9 no longer supported and not recommended to use at all?

• That is correct, 0.9.3 is considered end-of-life for the v0 API.

Is mdio v1 considered stable enough for production use?

• I would consider the core MDIO V1 API stable enough for production use. The backend behind the MDIO V1 API is xarray with the zarr-python handling the actual I/O. What the V1 API brings in addition to that is it's own Dataset Model and convenience functions crafted for seismic data.

When you update documentation from v0.9 to v1

• The Stable and Latest tags from the RTD currently both point towards v1 (master). We keep docs up for v0.9.3 specifically for legacy usage documentation.

Can somebody provide a precise list of 3rdparty package versions that is known to work together?

• It is not recommended to keep both V0 and V1 installed. I suspect that library requirements have diverged enough that they are incompatible without some clever hacking.

Is there a create_empty() function and example usage for v1?

• There is no MDIO API implementation for the create_empty() functionality yet. We were looking at it and discussing best practices but it has been a low priority feature. If it is necessary for any testing we have this nasty workaround internally. If there's a need for this feature, though, I can take a look at getting it implemented into the API.

Is there a high level api to do coordinate conversion from (inline,crossline) to (world_x, world_y)?

• This is where the power of the xarray backend comes! We can use a Dataset sel command to slice the entire dataset by value (e.g. inline 1001) and then retrieve the resulting Dataset (all crosslines at inline 1001, as well as all cdp_x and cdp_y values). You can read more about that from the xarray docs, although we should probably include a reference to this in the official MDIO documentation as well.

Confirm: Dealing with world coordinates in v0.9 requires knowledge of ... Seg-Y...

• Mostly correct. If ingesting from a SEG-Y file, it is still necessary for the user to understand where the real world X/Y values are located. If dealing with MDIO only, however, we are free of SEG-Y trace header baggage.

Confirm: If I need a matrix for converting (il,xl) to world(x,y)...

• We can use the cdp_x and cdp_y coordinate Variables directly, along with the trace_mask which indicates where live vs dead traces are. Note that trace_mask calculation does not take into account SEG-Y standard byte 29-30 "Trace identification code".

For oddly shaped surveys it gets trickier. Depending on how pedantic I need to be.

• This should be a fairly straight forward process of calculating a hull and applying any transformations as needed. We have some example code of how to do this in our sister mdio-cpp repo.

Confirm: After calculating the matrix, I cannot store it as such in the mdio file.

• You are free to add any Variables or Coordinates you want to your MDIO files at any point in its lifecycle, however we do not have a clean way to handle this as part of the MDIO API. Again, if this is a necessary feature for testing you should take a look at the optimize source code as it demonstrates the safe way to add a Variable without some pitfalls like accidentally deleting your metadata.

Confirm: The v1 example code for ingesting teapot ends up with the world coordinates being wrong by a factor of 10.

• This should not be the case. The value of of the coordinate_scalar (SEG-Y standard byte 71-72) will be applied to special case Coordinates such as cdp_x and cdp_y. Note that coordinate_scalar enforces the SEG-Y standard's actual definition. You can see more about how the coordinate scalar is handled in the Handling Corrupt SEG-Y Files section.