{"id":13948953,"url":"https://github.com/MPAS-Dev/MPAS-Analysis","last_synced_at":"2025-07-20T11:30:28.235Z","repository":{"id":9339128,"uuid":"61749446","full_name":"MPAS-Dev/MPAS-Analysis","owner":"MPAS-Dev","description":"Provides analysis for the MPAS components of E3SM","archived":false,"fork":false,"pushed_at":"2025-07-11T10:25:47.000Z","size":418035,"stargazers_count":58,"open_issues_count":35,"forks_count":52,"subscribers_count":19,"default_branch":"develop","last_synced_at":"2025-07-17T04:50:02.412Z","etag":null,"topics":["climate-analysis","climate-model","e3sm","mpas","mpas-analysis"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MPAS-Dev.png","metadata":{"files":{"readme":"README.md","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,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-06-22T20:29:57.000Z","updated_at":"2025-07-11T10:23:14.000Z","dependencies_parsed_at":"2023-09-21T19:32:22.532Z","dependency_job_id":"c8c59254-33df-482d-bf32-f00802e757c4","html_url":"https://github.com/MPAS-Dev/MPAS-Analysis","commit_stats":{"total_commits":1914,"total_committers":23,"mean_commits":83.21739130434783,"dds":0.2048066875653083,"last_synced_commit":"356d526b5276c709f915dc299a934126452d5e17"},"previous_names":[],"tags_count":73,"template":false,"template_full_name":null,"purl":"pkg:github/MPAS-Dev/MPAS-Analysis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MPAS-Dev%2FMPAS-Analysis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MPAS-Dev%2FMPAS-Analysis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MPAS-Dev%2FMPAS-Analysis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MPAS-Dev%2FMPAS-Analysis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MPAS-Dev","download_url":"https://codeload.github.com/MPAS-Dev/MPAS-Analysis/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MPAS-Dev%2FMPAS-Analysis/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265585299,"owners_count":23792714,"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":["climate-analysis","climate-model","e3sm","mpas","mpas-analysis"],"created_at":"2024-08-08T05:01:35.111Z","updated_at":"2025-07-20T11:30:28.225Z","avatar_url":"https://github.com/MPAS-Dev.png","language":"Python","funding_links":[],"categories":["Climate Change"],"sub_categories":["Climate Data Processing and Analysis"],"readme":"# MPAS-Analysis\n\nAnalysis for simulations produced with Model for Prediction Across Scales\n(MPAS) components and the Energy Exascale Earth System Model (E3SM), which\nused those components.\n\n![sea surface temperature](docs/users_guide/_static/sst_example.png)\n\n## conda-forge\n\n### Current build status\n\n\u003ctable\u003e\u003ctr\u003e\u003ctd\u003eAll platforms:\u003c/td\u003e\n    \u003ctd\u003e\n      \u003ca href=\"https://dev.azure.com/conda-forge/feedstock-builds/_build/latest?definitionId=6243\u0026branchName=main\"\u003e\n        \u003cimg src=\"https://dev.azure.com/conda-forge/feedstock-builds/_apis/build/status/mpas-analysis-feedstock?branchName=main\"\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### Current release info\n\n| Name | Downloads | Version | Platforms |\n| --- | --- | --- | --- |\n| [![Conda Recipe](https://img.shields.io/badge/recipe-mpas--analysis-green.svg)](https://anaconda.org/conda-forge/mpas-analysis) | [![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/mpas-analysis.svg)](https://anaconda.org/conda-forge/mpas-analysis) | [![Conda Version](https://img.shields.io/conda/vn/conda-forge/mpas-analysis.svg)](https://anaconda.org/conda-forge/mpas-analysis) | [![Conda Platforms](https://img.shields.io/conda/pn/conda-forge/mpas-analysis.svg)](https://anaconda.org/conda-forge/mpas-analysis) |\n\n## Documentation\n\n[https://mpas-dev.github.io/MPAS-Analysis/develop/](https://mpas-dev.github.io/MPAS-Analysis/develop/)\n\n## Installation for users\n\nMPAS-Analysis is available as an anaconda package via the `conda-forge` channel:\n\n```\nconda config --add channels conda-forge\nconda create -n mpas-analysis mpas-analysis\nconda activate mpas-analysis\n```\n\n## Installation for developers\n\nTo use the latest version for developers, get the code from:\n [https://github.com/MPAS-Dev/MPAS-Analysis](https://github.com/MPAS-Dev/MPAS-Analysis)\n\nThen, you will need to set up a conda environment from the MPAS-Analysis repo.\nThis environment will include the required dependencies for the development\nbranch from `dev-spec.txt` and will install the `mpas_analysis` package into\nthe conda environment in a way that points directly to the local branch (so\nchanges you make to the code directly affect `mpas_analysis` in the conda\nenvironment):\n\n``` bash\nconda config --add channels conda-forge\nconda config --set channel_priority strict\nconda create -y -n mpas_analysis_dev --file dev-spec.txt\nconda activate mpas_analysis_dev\npython -m pip install --no-deps --no-build-isolation -e .\n```\n\nIf you are developing another conda package at the same time (this is common\nfor MPAS-Tools or geometric\\_features), you should first comment out the other\npackage in `dev-spec.txt`.  Then, you can install both packages in the same\ndevelopment environment, e.g.:\n``` bash\nconda create -y -n mpas_analysis_dev --file tools/MPAS-Tools/conda_package/dev-spec.txt \\\n    --file analysis/MPAS-Analysis/dev-spec.txt\nconda activate mpas_analysis_dev\ncd tools/MPAS-Tools/conda_package\npython -m pip install --no-deps --no-build-isolation -e .\ncd ../../../analysis/MPAS-Analysis\npython -m pip install --no-deps --no-build-isolation -e .\n```\nObviously, the paths to the repos may be different in your local clones.  With\nthe `mpas_analysis_dev` environment as defined above, you can make changes to both\n`mpas_tools` and `mpas-analysis` packages in their respective branches, and\nthese changes will be reflected when refer to the packages or call their\nrespective entry points (command-line tools).\n\n## Download analysis input data\n\nIf you installed the `mpas-analysis` package, download the data that is\nnecessary to MPAS-Analysis by running:\n\n```\ndownload_analysis_data -o /path/to/mpas_analysis/diagnostics\n```\n\nwhere `/path/to/mpas_analysis/diagnostics` is the main folder that will contain\ntwo subdirectories:\n\n* `mpas_analysis`, which includes mapping and region mask files for\n  standard resolution MPAS meshes\n* `observations`, which includes the pre-processed observations listed in the\n  [Observations table](https://mpas-dev.github.io/MPAS-Analysis/latest/observations.html)\n  and used to evaluate the model results\n\nOnce you have downloaded the analysis data, you will point to its location\n(your equivalent of `path/to/mpas_analysis/diagnostics` above) in the config\noption `baseDirectory` in the `[diagnostics]` section.\n\n## List Analysis\n\nIf you installed the `mpas-analysis` package, list the available analysis tasks\nby running:\n\n```\nmpas_analysis --list\n```\n\nThis lists all tasks and their tags.  These can be used in the `generate`\ncommand-line option or config option.  See `mpas_analysis/default.cfg`\nfor more details.\n\n## Running the analysis\n\n  1. Create and empty config file (say `myrun.cfg`), copy `example.cfg`,\n     or copy one of the example files in the `configs` directory (if using a\n     git repo) or download one from the\n     [example configs directory](https://github.com/MPAS-Dev/MPAS-Analysis/tree/develop/configs).\n  2. Either modify config options in your new file or copy and modify config\n     options from `mpas_analysis/default.cfg` (in a git repo) or directly\n     from GitHub:\n     [default.cfg](https://github.com/MPAS-Dev/MPAS-Analysis/tree/develop/mpas_analysis/default.cfg).\n  3. If you installed the `mpas-analysis` package, run:\n     `mpas_analysis myrun.cfg`.  This will read the configuration\n     first from `mpas_analysis/default.cfg` and then replace that\n     configuration with any changes from from `myrun.cfg`\n  4. If you want to run a subset of the analysis, you can either set the\n     `generate` option under `[output]` in your config file or use the\n     `--generate` flag on the command line.  See the comments in\n     `mpas_analysis/default.cfg` for more details on this option.\n\n  **Requirements for custom config files:**\n  * At minimum you should set `baseDirectory` under `[output]` to the folder\n    where output is stored.  **NOTE** this value should be a unique\n    directory for each run being analyzed.  If multiple runs are analyzed in\n    the same directory, cached results from a previous analysis will not be\n    updated correctly.\n  * Any options you copy into the config file **must** include the\n    appropriate section header (e.g. '[run]' or '[output]')\n  * You do not need to copy all options from `mpas_analysis/default.cfg`.\n    This file will automatically be used for any options you do not include\n    in your custom config file.\n  * You should **not** modify `mpas_analysis/default.cfg` directly.\n\n## List of MPAS output files that are needed by MPAS-Analysis:\n\n  * mpas-o files:\n      * `mpaso.hist.am.timeSeriesStatsMonthly.*.nc` (Note: since OHC\n        anomalies are computed wrt the first year of the simulation,\n        if OHC diagnostics is activated, the analysis will need the\n        first full year of `mpaso.hist.am.timeSeriesStatsMonthly.*.nc`\n        files, no matter what `[timeSeries]/startYear` and\n        `[timeSeries]/endYear`  are. This is especially important to know if\n        short term archiving is used in the run to analyze: in that case, set\n        `[input]/runSubdirectory`, `[input]/oceanHistorySubdirectory` and\n        `[input]/seaIceHistorySubdirectory` to the appropriate run and archive\n        directories and choose `[timeSeries]/startYear` and\n        `[timeSeries]/endYear` to include only data that have been short-term\n        archived).\n      * `mpaso.hist.am.meridionalHeatTransport.0001-03-01.nc` (or any\n        `hist.am.meridionalHeatTransport` file)\n      * `mpaso.rst.0002-01-01_00000.nc` (or any other mpas-o restart file)\n      * `streams.ocean`\n      * `mpaso_in`\n  * mpas-seaice files:\n      * `mpasseaice.hist.am.timeSeriesStatsMonthly.*.nc`\n      * `mpasseaice.rst.0002-01-01_00000.nc` (or any other mpas-seaice restart\n        file)\n      * `streams.seaice`\n      * `mpassi_in`\n\nNote: for older runs, mpas-seaice files will be named:\n  * `mpascice.hist.am.timeSeriesStatsMonthly.*.nc`\n  * `mpascice.rst.0002-01-01_00000.nc`\n  * `streams.cice`\n  * `mpas-cice_in`\n  Also, for older runs `mpaso_in` will be named:\n  * `mpas-o_in`\n\n\n## Purge Old Analysis\n\nTo purge old analysis (delete the whole output directory) before running run\nthe analysis, add the `--purge` flag.  If you installed `mpas-analysis` as\na package, run:\n\n```\nmpas_analysis --purge \u003cconfig.file\u003e\n```\n\nAll of the subdirectories listed in `output` will be deleted along with the\nclimatology subdirectories in `oceanObservations` and `seaIceObservations`.\n\nIt is a good policy to use the purge flag for most changes to the config file,\nfor example, updating the start and/or end years of climatologies (and\nsometimes time series), changing the resolution of a comparison grid, renaming\nthe run, changing the seasons over which climatologies are computed for a given\ntask, updating the code to the latest version.\n\nCases where it is reasonable not to purge would be, for example, changing\noptions that only affect plotting (color map, ticks, ranges, font sizes, etc.),\nrerunning with a different set of tasks specified by the `generate` option\n(though this will often cause climatologies to be re-computed with new\nvariables and may not save time compared with purging), generating only the\nfinal website with `--html_only`, and re-running after the simulation has\nprogressed to extend time series (however, not recommended for changing the\nbounds on climatologies, see above).\n\n## Running in parallel via a queueing system\n\nIf you are running from a git repo:\n\n  1. If you are running from a git repo, copy the appropriate job script file\n     from `configs/\u003cmachine_name\u003e` to the root directory (or another directory\n     if preferred). The default script, `configs/job_script.default.bash`, is\n     appropriate for a laptop or desktop computer with multiple cores.\n  2. If using the `mpas-analysis` conda package, download the job script and/or\n     sample config file from the\n     [example configs directory](https://github.com/MPAS-Dev/MPAS-Analysis/tree/develop/configs).\n  3. Modify the number of parallel tasks, the run name, the output directory\n     and the path to the config file for the run.\n  4. Note: the number of parallel tasks can be anything between 1 and the\n     number of analysis tasks to be performed.  If there are more tasks than\n     parallel tasks, later tasks will simply wait until earlier tasks have\n     finished.\n  5. Submit the job using the modified job script\n\n\n\nIf a job script for your machine is not available, try modifying the default\njob script in `configs/job_script.default.bash` or one of the job scripts for\nanother machine to fit your needs.\n\n## Customizing plots or creating new ones\n\nThere are three main ways to either customize the plots that MPAS-Analysis\nalready makes or creating new ones:\n\n1. customize the config file. Some features, such as colormaps and colorbar\n   limits for color shaded plot or depth ranges for ocean region time series,\n   can be customized: look at `mpas_analysis/default.cfg` for available\n   customization for each analysis task.\n2. read in the analysis data computed by MPAS-Analysis into custom scripts. When\n   running MPAS-Analysis with the purpose of generating both climatologies\n   and time series, the following data sets are generated:\n   * `[baseDirectory]/clim/mpas/avg/unmasked_[mpasMeshName]`: MPAS-Ocean\n     and MPAS-seaice climatologies on the native grid.\n   * `[baseDirectory]/clim/mpas/avg/remapped`: remapped climatologies\n     for each chosen task (climatology files are stored in different\n     subdirectories according to the task name).\n   * `[baseDirectory]/clim/obs`: observational climatologies.\n   * `[baseDirectory]/clim/mpas/avg/mocStreamfunction_years[startYear]-[endYear].nc`.\n   * `[baseDirectory]/clim/mpas/avg/meridionalHeatTransport_years[startYear]-[endYear].nc`.\n   * `[baseDirectory]/timeseries`: various time series data.\n   Custom scripts can then utilize these datasets to generate custom plots.\n3. add a new analysis task to MPAS-Analysis (see below).\n\n## Instructions for creating a new analysis task\n\nAnalysis tasks can be found in a directory corresponding to each component,\ne.g., `mpas_analysis/ocean` for MPAS-Ocean. Shared functionality is contained\nwithin the `mpas_analysis/shared` directory.\n\n1. create a new task by `copying mpas_analysis/analysis_task_template.py` to\n   the appropriate folder (`ocean`, `sea_ice`, etc.) and modifying it as\n   described in the template.  Take a look at\n   `mpas_analysis/shared/analysis_task.py` for additional guidance.\n2. note, no changes need to be made to `mpas_analysis/shared/analysis_task.py`\n3. modify `mpas_analysis/default.cfg` (and possibly any machine-specific\n   config files in `configs/\u003cmachine\u003e`)\n4. import new analysis task in `mpas_analysis/\u003ccomponent\u003e/__init__.py`\n5. add new analysis task to `mpas_analysis/__main__.py` under\n   `build_analysis_list`, see below.\n\nA new analysis task can be added with:\n```\n   analyses.append(\u003ccomponent\u003e.MyTask(config, myArg='argValue'))\n```\nThis will add a new object of the `MyTask` class to a list of analysis tasks\ncreated in `build_analysis_list`.  Later on in `run_analysis`, it will first\ngo through the list to make sure each task needs to be generated\n(by calling `check_generate`, which is defined in `AnalysisTask`), then,\nwill call `setup_and_check` on each task (to make sure the appropriate AM is\non and files are present), and will finally call `run` on each task that is\nto be generated and is set up properly.\n\n## Generating Documentation\n\nCreate a development environment as described above in \"Installation for\ndevelopers\".  Then run:\nTo generate the `sphinx` documentation, run:\n```\ncd docs\nDOCS_VERSION=test make clean versioned-html\n```\nThe results can be viewed in your web browser by opening:\n```\n_build/html/index.html\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMPAS-Dev%2FMPAS-Analysis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMPAS-Dev%2FMPAS-Analysis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMPAS-Dev%2FMPAS-Analysis/lists"}