{"id":13773546,"url":"https://github.com/darothen/xbpch","last_synced_at":"2025-03-21T08:31:58.419Z","repository":{"id":60721926,"uuid":"89022822","full_name":"darothen/xbpch","owner":"darothen","description":"xarray interface for bpch files","archived":false,"fork":false,"pushed_at":"2023-11-27T03:15:07.000Z","size":2046,"stargazers_count":17,"open_issues_count":11,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-29T20:22:10.635Z","etag":null,"topics":["analysis","binary","climate","data","geos-chem","python","xarray"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/darothen.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-04-21T20:53:39.000Z","updated_at":"2023-11-27T03:15:12.000Z","dependencies_parsed_at":"2024-01-12T08:48:41.970Z","dependency_job_id":"6d0656e9-740b-4d7b-919c-1fe28be472b2","html_url":"https://github.com/darothen/xbpch","commit_stats":{"total_commits":84,"total_committers":3,"mean_commits":28.0,"dds":0.0357142857142857,"last_synced_commit":"adcedfb31e41749b1486eaa38872f9f514c619dc"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darothen%2Fxbpch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darothen%2Fxbpch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darothen%2Fxbpch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darothen%2Fxbpch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/darothen","download_url":"https://codeload.github.com/darothen/xbpch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244124196,"owners_count":20401685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analysis","binary","climate","data","geos-chem","python","xarray"],"created_at":"2024-08-03T17:01:16.982Z","updated_at":"2025-03-21T08:31:55.984Z","avatar_url":"https://github.com/darothen.png","language":"Python","funding_links":[],"categories":["Software"],"sub_categories":["Data Storage"],"readme":"xbpch: xarray interface for bpch files\n======================================\n\n.. image:: https://badge.fury.io/py/xbpch.svg\n    :target: https://badge.fury.io/py/xbpch\n    :alt: PyPI version\n.. image:: https://readthedocs.org/projects/xbpch/badge/?version=latest\n    :target: http://xbpch.readthedocs.io/en/latest/?badge=latest\n    :alt: Documentation Status\n.. image:: https://zenodo.org/badge/89022822.svg\n    :target: https://zenodo.org/badge/latestdoi/89022822\n    :alt: Zenodo DOI\n\n**xpbch** is a simple utility for reading the proprietary\n`binary punch format (bpch) outputs \u003chttp://wiki.seas.harvard.edu/geos-chem/index.php/GEOS-Chem_Output_Files#Binary_Punch_File_Format)\u003e`_ used in versions\nof GEOS-Chem_ earlier than v11-02. The utility allows a user to load this\ndata into an xarray_- and dask_-powered workflow without necessarily\npre-processing the data using GAMAP_ or IDL.\n\nThis package is maintained as part of a broader, community effort to\ntackle `big data problems in geoscience \u003chttps://pangeo-data.github.io/\u003e`_.\n\nWhat's the Deal?\n----------------\n\nThe `contemporary scientific Python software stack \u003chttps://speakerdeck.com/jakevdp/the-state-of-the-stack-scipy-2015-keynote\u003e`_\nprovides free, powerful tools for nearly all of your data processing, analysis,\nand visualization needs. These tools are `well supported \u003chttps://www.numfocus.org/\u003e`_\nby a large community of heavily invested users and developers from academia,\ngovernment, and industry. They are also developed (mostly) as part of community-based,\nopen-source, and user-driven projects.\n\nFor nearly any application you might have in the geosciences, you can start using\nthis powerful, free software stack *today* with minimal friction. However,\none friction point that has tripped up adoption by GEOS-Chem users is that it\nis difficult to work with legacy bpch-format diagnostics files. **xbpch**\nsolves this problem by providing a convenient and performant way to read\nthese files into a modern Python-based analysis or workflow.\n\nFurthermore, **xbpch** is 100% future-proof. In two years, when your GEOS-Chem\nsimulations are writing NetCDF diagnostics, you won't need to change more than a\nsingle line of code in any of your scripts using **xbpch**. All you'll need to do\nis swap out **xbpch**'s function for reading data and instead defer to it's parent\npackage (xarray). It will *literally* take less than 10 keystrokes to make this\nchange in your code. Plus - you'll be backwards compatible with any legacy\noutput you need to analyze.\n\nSo give **xbpch** a try, and let me know what issues you run in to! If we solve\nthem once today, they'll be solved in perpetuity, which means more time for you\nto do science and less time to worry about processing data.\n\n\nInstallation\n------------\n\nRequirements\n^^^^^^^^^^^^\n\n**xbpch** is only intended for use with Python 3, although with some\nmodifications it  would likely work with Python 2.7 (`Pull Requests are\nwelcome! \u003chttps://github.com/darothen/xbpch/pulls\u003e`_). As the package\ndescription implies, it requires up-to-date copies of xarray_\n(\u003e= version 0.9) and dask_ (\u003e= version 0.14). The best way to install\nthese packages is by using the conda_ package management system, or\nthe `Anaconda Python distribution \u003chttps://www.continuum.io/downloads\u003e`_.\n\nTo install **xbpch** and its dependencies using conda, execute from a terminal::\n\n    $ conda install -c conda-forge xbpch xarray dask\n\nAlternatively, you can install **xbpch** `from PyPI \u003chttps://pypi.python\n.org/pypi/xbpch/\u003e`_::\n\n    $ pip install xbpch\n\nYou can also install **xbpch** from its source. To do this, you\ncan either clone the source directory and manually install::\n\n    $ git clone https://github.com/darothen/xbpch.git\n    $ cd xbpch\n    $ python setup.py install\n\nor, you can install via pip directly from git::\n\n    $ pip install git+https://github.com/darothen/xbpch.git\n\nPlease note that if you locally clone the repository from GitHub but do not\nexplicitly install the package using ``setup.py``, the file ``xbpch/version.py``\nwill not get written properly and you will not be able to use the package. \nWe strongly recommend you install the package using traditional techniques to\nensure that all dependencies are properly added to your environment.\n\nQuick Start\n-----------\n\nIf you're already familiar with loading and manipulating data with\nxarray_, then it's easy to dive right into **xbpch**. Navigate to a\ndirectory on disk which contains your ``.bpch`` output, as well as\n``tracerinfo.dat`` and ``diaginfo.dat``, and execute from a Python\ninterpeter:\n\n.. code:: python\n\n    from xbpch import open_bpchdataset\n    fn = \"my_geos_chem_output.bpch\"\n    ds = open_bpchdataset(fn)\n\nAfter a few seconds (depending on your hard-drive speed) you should be\nable to interact with ``ds`` just as you would any *xarray.Dataset*\nobject.\n\nCaveats and Future Notes\n------------------------\n\n**xbpch** should work for most simple workflows, especially if you need\na quick-and-dirty way to ingest legacy GEOS-Chem_ output. It is **not**\ntested against the majority of output grids, including data for the Hg\nmodel or nested models. Grid information (at least for the vertical) is\nhard-coded and may not be accurate for the most recent versions of\nGEOS-Chem_.\n\nMost importantly, **xbpch** does not yet solve the problem of manually\nscanning bpch files before producing a dataset on disk. Because the bpch\nformat does not encode metadata about *what its contents actually are*,\nwe must manually process this from any output file we wish to load. For\nthe time being, we do **not** short-circuit this process because we\ncannot necessarily predict file position offsets in the bpch files we\nread. In the future, I hope to come up with an elegant solution for\nsolving this problem.\n\nAcknowledgments\n---------------\n\nThis utility packages together a few pre-existing toolkits which\nhave been floating around the Python-GEOS-Chem community. In particular,\nI would like to acknowledge the following pieces of software which I have\nbuilt this utility around:\n\n- `PyGChem \u003chttps://github.com/benbovy/PyGChem\u003e`_ by\n  `Benoit Bovy \u003chttps://github.com/benbovy\u003e`_\n- `gchem \u003chttps://github.com/gkuhl/gchem\u003e`_ by\n  `Gerrit Kuhlmann \u003chttps://github.com/gkuhl\u003e`_\n\nFurthermore, the strategies used to load and process binary output on disk\nthrough xarray_\\'s ``DataStore`` API is heavily inspired by `Ryan\nAbernathey's \u003chttps://github.com/rabernat\u003e`_ package `xmitgcm\n\u003chttps://github.com/rabernat/xmitgcm\u003e`_. \n\n  \nLicense\n-------\n\nCopyright (c) 2017 `Daniel Rothenberg`_\n\nThis work is licensed_ under a permissive MIT License. I acknowledge\nimportant contributions from Benoît Bovy, Gerrit Kuhlmann, and Christoph\nKeller in the form of prior work which helped create the foundation for\nthis package.\n\nContact\n-------\n\n`Daniel Rothenberg`_ - darothen@mit.edu\n\n.. _`Daniel Rothenberg`: http://github.com/darothen\n.. _conda: http://conda.pydata.org/docs/\n.. _dask: http://dask.pydata.org/\n.. _GAMAP: http://acmg.seas.harvard.edu/gamap/\n.. _licensed: LICENSE\n.. _GEOS-Chem: http://www.geos-chem.org\n.. _xarray: http://xarray.pydata.org/\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarothen%2Fxbpch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdarothen%2Fxbpch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarothen%2Fxbpch/lists"}