Allow passing in pandas dataframes to x2sys_cross

[weiji14]

Description of proposed changes

Run crossover analysis directly on pandas.DataFrame inputs instead of having to write to tab-separated value (TSV) files first!

Example code:

import pygmt
from tempfile import TemporaryDirectory

dataframe: pd.DataFrame = pygmt.datasets.load_sample_bathymetry()
dataframe.columns = ["x", "y", "z"]  # longitude, latitude, bathymetry

os.environ["X2SYS_HOME"] = os.getcwd()

with TemporaryDirectory(prefix="X2SYS", dir=os.environ["X2SYS_HOME"]) as tmpdir:
    tag = os.path.basename(tmpdir)
    pygmt.x2sys_init(tag=tag, fmtfile="xyz", suffix="xyz", force=True)
    output: pd.DataFrame = pygmt.x2sys_cross(tracks=[dataframe], tag=tag, coe="i", verbose="i")

This isn't a trivial thing to implement, because:

• x2sys requires those TSV files in quite a specific format (especially for the datetime columns)
• The TSV files cannot be in any arbitrary directory like /tmp, it must be stored either in the current working directory or in specific locations listed in the TAG_paths.txt file.

Support for pandas DataFrame inputs into x2sys_cross was originally left out in the original implementation at #546 because we wanted to wait for GenericMappingTools/gmt#3717. But seeing as it's not a trivial matter, this is an interim solution.

Fixes #

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

[weiji14]

Is there a better way to check if -Exyz is in the string, and if not, fallback to parsing from Dxyz?

[seisman]

What about this one?

lastline = "-Dxyz -Etsv -I1/1"
#lastline = "-Dxyz -I1/1"

for item in lastline.split():
    for key in ['-E', '-D']:
        if item.startswith(key):
            suffix = item[2:]
            break
print(suffix)

Note: the code may be wrong, but maybe some codes like this one.

[weiji14]

Hmm, this gives me some ideas. I'll play around with it, thanks!

[weiji14]

Ok ready for review! I understand that this isn't easy to review properly, but would really appreciate getting this in for v0.2.0 tomorrow as I'll be using it for my PhD research. There's two unit tests added, one for internal crossovers (i.e. on 1 track) and one for external crossovers (2 tracks). I'll add a tutorial example for this over the weekend to explain things better.

[weiji14]

The original implementation using GMTTempFile/NamedTemporaryFile didn't work because of some permissions issues (on macOS/Windows), which is why this try-finally block is used.

[seisman]

The code quality looks good. As you're the one who develops and uses these functions, we have to trust you. 😄

Just one suggestion, add the comment to the codes, explaining why you use unique_name here.

That's the first question when I read your codes before I see your comment here.

[weiji14]

The code quality looks good. As you're the one who develops and uses these functions, we have to trust you. smile

It's all Paul's work done a decade ago, I'm just wrapping it in Python so more people can use it easily 😃 You won't believe how many 'crossover analysis' tools have been written again and again, but that's another story.

Just one suggestion, add the comment to the codes, explaining why you use unique_name here.

That's the first question when I read your codes before I see your comment here.

Ok, will do.