diff --git a/.github/workflows/manual-pages-deploy.yml b/.github/workflows/manual-pages-deploy.yml index 5cd3b985..af1840dc 100644 --- a/.github/workflows/manual-pages-deploy.yml +++ b/.github/workflows/manual-pages-deploy.yml @@ -12,6 +12,8 @@ jobs: runs-on: ubuntu-latest permissions: contents: write + pages: write + id-token: write steps: - name: Checkout repository uses: actions/checkout@v4 @@ -21,7 +23,7 @@ jobs: sed -i "s/PACKAGE_VERSION/0.0.1/" setup.py sed -i "s/PACKAGE_VERSION/0.0.1/" CHAP/__init__.py sed -i "s/PACKAGE_VERSION/0.0.1/" docs/conf.py - sed -i "s/PACKAGE_VERSION/0.0.1/" docs/installation.md + cat setup.py - name: Setup Miniconda uses: conda-incubator/setup-miniconda@v3 diff --git a/.github/workflows/pages-deploy-from-docs.yml b/.github/workflows/pages-deploy-from-docs.yml new file mode 100644 index 00000000..56e58af2 --- /dev/null +++ b/.github/workflows/pages-deploy-from-docs.yml @@ -0,0 +1,75 @@ +name: Deploy Sphinx documentation to Pages from docs branch push + +on: + push: + branches: + - docs + +defaults: + run: + shell: bash -l {0} + +jobs: + build_and_deploy: + runs-on: ubuntu-latest + permissions: + contents: write + pages: write + id-token: write + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Update docs configuration with version (tag) name + run: | + sed -i "s/PACKAGE_VERSION/0.0.1/" setup.py + sed -i "s/PACKAGE_VERSION/0.0.1/" CHAP/__init__.py + sed -i "s/PACKAGE_VERSION/0.0.1/" docs/conf.py + cat setup.py + + - name: Setup Miniconda + uses: conda-incubator/setup-miniconda@v3 + with: + python-version: '3.10' + environment-file: docs/environment.yml + auto-activate: true + activate-environment: sphinx + conda-remove-defaults: true + use-mamba: true + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install sphinx + pip install sphinx-math-dollar + pip install sphinx-rtd-theme + pip install myst-parser + #pip install autodoc_pydantic + + - name: Install package + run: | + pip install -e . + conda list + + - name: Generate .rst files with sphinx-apidoc + run: | + sphinx-apidoc -M --tocfile api_documentation --module-first -o docs CHAP CHAP/hdrm CHAP/inference CHAP/sin2psi CHAP/test + + - name: Build Sphinx HTML documentation + run: | + make clean + make html + working-directory: ./docs + + - name: List generated files + run: | + pwd + ls -lha + ls -lha ./docs/_build/html + cat ./docs/_build/html/index.html + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/_build/html diff --git a/.github/workflows/pages-deploy.yml b/.github/workflows/pages-deploy.yml index 66c2c8d9..d4c09044 100644 --- a/.github/workflows/pages-deploy.yml +++ b/.github/workflows/pages-deploy.yml @@ -4,10 +4,6 @@ on: push: tags: - v*.*.* -#on: -# push: -# branches: -# - docs defaults: run: @@ -18,6 +14,8 @@ jobs: runs-on: ubuntu-latest permissions: contents: write + pages: write + id-token: write steps: - name: Checkout repository uses: actions/checkout@v4 @@ -27,7 +25,7 @@ jobs: sed -i "s/PACKAGE_VERSION/${{ github.ref_name }}/" setup.py sed -i "s/PACKAGE_VERSION/${{ github.ref_name }}/" CHAP/__init__.py sed -i "s/PACKAGE_VERSION/${{ github.ref_name }}/" docs/conf.py - sed -i "s/PACKAGE_VERSION/${{ github.ref_name }}/" docs/installation.md + cat setup.py - name: Setup Miniconda uses: conda-incubator/setup-miniconda@v3 diff --git a/AUTHORS b/AUTHORS new file mode 100644 index 00000000..5b59353e --- /dev/null +++ b/AUTHORS @@ -0,0 +1,8 @@ +AUTHORS + +# The official list of Cornell High Energy Synchrotron Source (CHESS) authors of the CHESSComputing organization for copyright purposes + +- Valentin Kuznetsov, Cornell University +- Keara L Soloway, Cornell University +- Werner Sun, Cornell University +- Rolf Verberg, Cornell University diff --git a/CHAP/edd/models.py b/CHAP/edd/models.py index d224a69e..e2a9cad7 100755 --- a/CHAP/edd/models.py +++ b/CHAP/edd/models.py @@ -64,7 +64,7 @@ class BaselineConfig(CHAPBaseModel): # Fit configuration class -class _FitConfig(CHAPBaseModel): +class FitConfig(CHAPBaseModel): """Fit parameters configuration class for peak fitting. :ivar background: Background model for peak fitting, defaults @@ -237,9 +237,9 @@ def validate_materialconfig_after(self): # Avoid Pydantic "Class not fully defined" in sphinx autodoc as a # result of lazy importing by using in an _exclude pydantic instance # variable -_FitConfig.model_rebuild(_types_namespace=vars(typing)) +FitConfig.model_rebuild(_types_namespace=vars(typing)) -class MCADetectorCalibration(Detector, _FitConfig): +class MCADetectorCalibration(Detector, FitConfig): """Class representing the configuration for a single MCA detector element to perform detector calibration. @@ -547,7 +547,7 @@ def get_tth_map(self, map_shape): ] -class MCADetectorConfig(_FitConfig): +class MCADetectorConfig(FitConfig): """Class representing metadata required to configure a full MCA detector. @@ -559,7 +559,7 @@ class MCADetectorConfig(_FitConfig): 'calibration', 'diffractionvolumelength', 'strainanalysis'] detectors: Optional[conlist(min_length=1, item_type=MCADetector)] = [] - _exclude = set(vars(_FitConfig()).keys()) + _exclude = set(vars(FitConfig()).keys()) @model_validator(mode='before') @classmethod @@ -611,7 +611,7 @@ def update_detectors(self): # Processor configuration classes -class DiffractionVolumeLengthConfig(_FitConfig): +class DiffractionVolumeLengthConfig(FitConfig): """Configuration for the differential volume length processor :class:`~CHAP.edd.processor.DiffractionVolumeLengthProcessor` for an EDD setup using a steel-foil raster scan. @@ -639,7 +639,7 @@ class DiffractionVolumeLengthConfig(_FitConfig): sample_thickness: Optional[confloat(gt=0, allow_inf_nan=False)] = None sigma_to_dvl_factor: Optional[Literal[2.0, 3.5, 4.0]] = 3.5 - _exclude = set(vars(_FitConfig()).keys()) + _exclude = set(vars(FitConfig()).keys()) @model_validator(mode='after') def validate_diffractionvolumelengthconfig_after(self): diff --git a/CHAP/edd/processor.py b/CHAP/edd/processor.py index 2309ff78..5d67fc3c 100755 --- a/CHAP/edd/processor.py +++ b/CHAP/edd/processor.py @@ -1015,7 +1015,7 @@ def process(self, data): if len(sskipped_detectors) == 1: self.logger.warning( f'Skipping detector {sskipped_detectors[0]} ' - '(no raw data)') + '(no calibration data)') elif sskipped_detectors: skipped_detectors = [int(d) for d in sskipped_detectors] self.logger.warning( @@ -2747,7 +2747,7 @@ def process(self, data): if len(sskipped_detectors) == 1: self.logger.warning( f'Skipping detector {sskipped_detectors[0]} ' - '(no raw data)') + '(no calibration data)') elif sskipped_detectors: skipped_detectors = [int(d) for d in sskipped_detectors] self.logger.warning( diff --git a/LICENSE b/LICENSE index d0b1e9b5..4775e04e 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2023 Valentin Kuznetsov +Copyright (c) 2023 The ChessAnalysisPipeline (CHAP) Authors (see AUTHORS file) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index e0365822..8b49fe86 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,23 @@ ![unittests](https://github.com/CHESSComputing/ChessAnalysisPipeline/actions/workflows/unittests.yml/badge.svg) # ChessAnalysisPipeline (CHAP) -CHAP is a package that provides a framework for executing data anlaysis pipelines. The package can be found on PyPI and conda-forge. -## Subpackages -There are several subpackages within CHAP that contain specialized items to handle specific types of data processing in the CHAP framework. Dependencies for these subpackages can be found in `CHAP//environment.yml`. +## :bulb: About +The CHESS Analysis Pipeline (CHAP) package is an object-oriented python framework for executing data reduction and analysis workflows by refactoring workflows into modular pipelines composed of interchangeable, reusable code components where each basic pipeline block consists of a reader, processor, and/or writer. Please check the CHAP [introduction](https://chesscomputing.github.io/ChessAnalysisPipeline/introduction.html) for a broad outline of its basic framework. -## Documentation -Documentation for the latest version can be found on [this project's github pages site](https://chesscomputing.github.io/ChessAnalysisPipeline/). +## :hammer_and_wrench: Installation +The package is available over PyPI and conda-forge. See the [installation instructions](https://chesscomputing.github.io/ChessAnalysisPipeline/installation.html) for installing CHAP on any Linux system. + +#### :package: Subpackages +There are several subpackages within CHAP that contain specialized items to handle specific types of data processing workflows in the CHAP framework. Dependencies for these subpackages can be found in `CHAP//environment.yml`. Details on how to install a conda environment for each of these subpackages are also included in the [installation instructions](https://chesscomputing.github.io/ChessAnalysisPipeline/installation.html) + +## :books: Documentation +Documentation for the latest release version can be found on [this project's github pages site](https://chesscomputing.github.io/ChessAnalysisPipeline/). + +## :handshake: Contributing +We welcome feedback, suggestions, issues and bug reports. + +Feel free to fork the [repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub and send a pull request, or to contribute by [submitting an issue](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues). Each contribution helps CHAP grow and improve. +When submitting an issue, please have a look at the [contribution guidelines](https://chesscomputing.github.io/ChessAnalysisPipeline/CONTRIBUTIONS.html). Following these guidelines grately helps us to address each issue promptly and effectively. + +We appreciate your support! diff --git a/docs/CONTRIBUTIONS.md b/docs/CONTRIBUTIONS.md new file mode 100644 index 00000000..c88551fb --- /dev/null +++ b/docs/CONTRIBUTIONS.md @@ -0,0 +1,234 @@ +(contributions)= +# Contributions + +We welcome feedback, suggestions, issues and bug reports. + +Feel free to fork the [repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub and send a pull request, or to contribute by [submitting an issue](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues). Each contribution helps CHAP grow and improve. + +We appreciate your support! + +## How to contribute + +CHAP is an open source project and we encourage and gratefully receive feedback or contributions to improve our product. Please follow these guidelines to contribute to CHAP. Doing so grately helps us to address each contribution promptly and effectively. + +There are many ways to contribute, from supplying examples, improving the documentation, submitting bug reports and feature requests or writing code that can be incorporated into CHAP itself. +Please [submit an issue](submit_chap_issue) to report a bug or request new features. Actual bug fixes or other types of contributions to the source code or documentation should be submitted after [creating a fork](create_chap_fork) and making a [pull request](make_chap_pull_request). Please do not use the issue tracker for support questions or to leave feedback. Instead, feel free to contact any of the administators directly. + +Please only report a bug or request a new feature after checking the [existing open issues](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) and verifying that it has not yet been reported, requested or addressed! + +(submit_chap_issue)= +### Submitting an issue + +If you find a security vulnerability, do NOT open an issue. Contact any of the administators instead. + +#### Reporting a bug + +Report a bug by following these step to submit an issue: + +1. Click on the green "New issues" botton on the [issues tab of the CHAP Github repository](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) to open a new issue. + +1. Select the "CHAP CLI Bug report" option to open a template to provide us with information to help us track and reproduce the error. + +1. After the "CHAP CLI Bug report" interface opens: + + a. Supply a clear and concise title to identify the issue. + + b. Edit and fill out the description form, being as specific as you can in answering each of the following items: + + - Give a clear and concise description of the nature of the bug. + + - Provide a minimal pipeline configuration in which the bug appears. + + - Describe what you expected to happen. + + - Describe what actually happens and if possible add a record or a screen shot of the (relevant part of the) CHAP logger output to show the error or explain the problem. + + - Provide information of the OS, CHAP version and python/conda environment. + + - Provide any additional information that can help in tracking down the issue. + + c. Click on the green "Create" botton on the right bottom corner of the dialogue interface. + +#### Suggesting or requesting a new feature or enhancement + +Request a new feature by following these step to submit an issue: + +1. Click on the green "New issues" botton on the [issues tab of the CHAP Github repository](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) to open a new issue. + +1. Select the "New PipelineItem request" option to open a template to provide us with information that helps us to modify existing or create new CHAP `PipelineItem`s to implement the feature. + +1. After the "New PipelineItem request" dialogue interface opens: + + a. Supply a clear and concise title to describe the feature. + + b. Edit and fill out the description form, being as specific as you can in answering each of the following items: + + - Describe the intended use of the requested feature. + + - Describe the feature's inputs. + + - Describe the feature's optional interaction points. + + - Describe the feature's output. + + - Provide any additional information that can help in implementing the new feature. + + c. Click on the green "Create" botton on the right bottom corner of the dialogue interface. + +#### Reporting any other issue + +Follow these these step to submit any other issue, not covered by either option above: + +1. Click on the green "New issues" botton on the [issues tab of the CHAP Github repository](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) to open a new issue. + +1. Select the "Blank issue" option to open a template to provide us with information to help us resolve the issue. + +1. After the new issue interface opens: + + a. Supply a clear and concise title to identify the issue, + + b. Edit and fill out the description form, being as specific as you can. + + c. Click on the green "Create" botton on the right bottom corner of the dialogue interface. + +Check out the [Github documentation](https://docs.github.com/en) on [creating an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue) for additional helpful hints. + +### Directly contributing to the source code or documentation + +Actual bug fixes or other types of contributions to the source code or documentation should be submitted by making a pull request from your own fork. +Whether you are fixing bugs, adding features, or improving documentation, following the steps below ensures that any contributions can be verified and vetted by the administrators before incorporation into the main code base. To contribute directly to CHAP, you will need your own account on [Github](https://github.com). + +(create_chap_fork)= +#### Create your own fork + +Start by creating your own copy or "fork" of the CHAP repository before starting to contribute directly to the source code or documentation. This creates a copy of the repository that shares the code and documentation with the original CHAP repository, but that lets you make modifications or additions without directly affecting the source. + +Create a fork by following these steps: + +1. In a web browser, navigate to the [CHAP repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub. + +1. In the top-right corner of the page, click "Fork". + +1. After the "Create a new fork" interface opens: + + a. Select your own personal Github account under "Choose an owner". By default, forks are named the same as their upstream repositories. To follow this convention, leave the Repository name unchanged as "ChessAnalysisPipeline". + + b. Optionally, in the "Description" field, type a description of your fork. + + c. It is strongly recommended to select "Copy the main branch only" (its default setting). + + d. Click on the green "Create fork" button. + +#### Clone your fork to your computer + +After creating your own CHAP fork, you also need to create a local copy of the project or "clone" on your own computer. To clone your forked repositiory: + +1. Click on the green "<> Code" botton. + +1. Copy the URL for the repository: Under the "Local" tab choose to clone the repository using HTTPS or using an SSH key by selecting the respective tab and clicking the "Copy URL to clipboard" button to the right of the corresponding link. Choose HTTPS for a fast and easy setup if you just want to inspect the code base. Choose SSH if you plan to contribute frequently and want to avoid needing to enter your credentials for every push or pull. + +1. On Mac or Linux, open a Terminal. On Windows, open Git Bash. + +1. Change to the location where you want the cloned directory. + +1. Type git clone, and then paste the URL you copied earlier. It should look like: + ```bash + $ git clone https://github.com//ChessAnalysisPipeline.git + ``` + or + ```bash + $ git clone git@github.com:/ChessAnalysisPipeline.git + ``` + for cloning with HTTPS or SSH, respectively. + +1. Press Enter + +#### Create a branch to work on + +It is STRONGLY recommended to create your own development branch instead of working directly with a fork of the main branch: + +1. Navigate into the cloned CHAP repository directory: + ```bash + $ cd ChessAnalysisPipeline + ``` + +2. Create your development branch: + ```bash + $ git branch BRANCH-NAME + $ git checkout BRANCH-NAME + ``` + after choosing a suitable name for BRANCH-NAME, e.g., "dev_". + +3. Create and track a copy of your newly created branch on your forked remote repository: + ```bash + $ git push --set-upstream origin BRANCH-NAME + ``` + +#### Make and push changes + +You can now add to or make changes to the code or documentation. + +When you're ready to submit your changes, stage and commit your changes and push your changes to your forked remote repository on Github. +Best practice principles teach us to keep changes small, incremental and as logically grouped as possible within individual commits. There is no limit to the number of commits in any single pull request and it is much easier to review changes that are split across multiple commits. + +Stage any files that are changed or added to be committed by executing: +```bash +$ git add +``` +telling Git what to include in the next commit. When ready, commit these changes with: +```bash +$ git commit -m "a short description of the change" +``` +and push your locally saved changes to your forked remote repository on Github: +```bash +$ git push +``` + +(make_chap_pull_request)= +#### Make a pull request + +Making a pull request is the final step in contributing directly to the CHAP code base. After making changes or adding features to the code or documentation and pushing them to your forked remote Github repository you have to make a request to the CHAP administrators to have them included or "pulled" into the main code base. + +To do return to your web browser and navigate again to the [CHAP repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub. Then: + +1. You may see a banner indicating that your branch is ahead of the main CHAP branch or you may have to select your branch from the pull down box in the top left corner. Click the "contribute" button and the then the green "Open a pull request" button. + +1. After Github brings you to the pull request interface: + + a. Verify on the top that the base repository is CHESSComputing/ChessAnalysisPipeline and its base is "main", that the head repository is your branch on your forked repository and that Github display "Able to merge" in green right underneath this (contact the CHAP administrators if Github is not able to merge the changes). + + b. Add a clear and descriptive title for your pull request in the "Add a title" box. + + c. Add a clear description of your changes or additions "Add a description" +e" box. Making the title and description clear and consise will greatly help the administrators to determine whether your contribution is useful and needed for everyone to be included in the main code base. + + d. Click the green "Create pull request" button. + +## Code review process + +After submitting a pull request, changes will be reviewed by the administrators. Once approved, the pull request will be merged by the administrators and you can update your local branch by: + +1. Navigating in your web browser to your forked CHAP repository. + +1. Selecting your forked main branch from the pull down list on the top left, which should then say that it is ahead of CHESSComputing/ChessAnalysisPipeline:main. + +1. Click the "Sync fork" button to synchronize or update your local main branch with that on the main CHAP repository. + +1. Returning to your Terminal, navigating to the directory containing the clone of your forked repository and: + + a. Changing to your local main branch and pulling the updated remote one: + ```bash + $ git checkout main + $ git pull + ``` + + b. Changing to your local development branch and merging the chamges from the main branch into your local development branch: + ```bash + $ git checkout BRANCH-NAME + $ git merge main + ``` + +At this point, you are fully synchronized with the main CHAP code base, ready for a new cycle of making and submitting changes. + + +Please, check the [Github documentation](https://docs.github.com/en) on [creating your own personal account](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github), [adding an SSH key to your account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account), [creating an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue), [forking a repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo), or [submitting a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) for additional helpful hints. diff --git a/docs/_templates/breadcrumbs.html b/docs/_templates/breadcrumbs.html new file mode 100644 index 00000000..9c21555f --- /dev/null +++ b/docs/_templates/breadcrumbs.html @@ -0,0 +1,8 @@ +{% extends "!breadcrumbs.html" %} + +{% block breadcrumbs_aside %} +
  • + GitHub +
    • +{% endblock %} + diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 00000000..1dec2699 --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,17 @@ +{% extends "!layout.html" %} + +{% block menu %} + {{ super() }} +

    External Links

    + +{% endblock %} + diff --git a/docs/conf.py b/docs/conf.py index 7deea7df..fc5555b0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,6 +22,7 @@ extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', 'sphinx.ext.doctest', 'sphinx.ext.githubpages', 'sphinx.ext.intersphinx', @@ -93,5 +94,12 @@ ], } +# Add Github repo link for `sphinx_rtd_theme` theme +# See also _templates/breadcrumbs.html and _templates/layout.html +templates_path = ['_templates'] +html_context = { + 'display_github': True, +} + # If true, links to the reST sources are added to the pages. html_show_sourcelink = False diff --git a/docs/index.rst b/docs/index.rst index dc243a67..ad78c2d2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,12 @@ Chess Analysis Pipeline (CHAP) introduction +.. toctree:: + :titlesonly: + :caption: Contributions + + CONTRIBUTIONS + .. toctree:: :titlesonly: :caption: Installation diff --git a/docs/workflows/EDD.md b/docs/workflows/EDD.md index 688e85f9..d6d72fae 100644 --- a/docs/workflows/EDD.md +++ b/docs/workflows/EDD.md @@ -224,7 +224,7 @@ The "config" block defines the CHAP generic configuration parameters: - `log_level`: The [Python logging level](https://docs.python.org/3/library/logging.html#levels). -The remainder of the file contains the actual workflow pipeline, in this example it consists of four blocks, `energy`, `tththeta`, `map`, and `strain`, which can be executed individually or all at once [as described here](chap_pipeline). In addition to the readers and writers of the intermediate results, nine toplevel processes get executed successively in the combined four pipeline blocks: +The remainder of the file contains the actual workflow pipeline, in this example it consists of four blocks, `energy`, `twotheta`, `map`, and `strain`, which can be executed individually or all at once [as described here](chap_pipeline). In addition to the readers and writers of the intermediate results, nine toplevel processes get executed successively in the combined four pipeline blocks: - The EDD/XRF energy calibration consists of two processes: @@ -254,6 +254,204 @@ The remainder of the file contains the actual workflow pipeline, in this example Note that the energy calibration can also be obtained ahead of time and used for multiple strain analyses. In this case remove the first two blocks in the pipeline and read the detector channel energy/$2\theta$ calibration info in what is now the third block in the pipeline, labelled `map`. +### Creating the CHESS stype strain analysis map without a par-file + +The above strain analysis workflow example can also be executed without availablity of a CHESS style experiment par-file, by reading the raw data information directly from the SPEC log file. In this case the map construction part description of the workflow in the `pipeline.yaml` file must be replaced by the following: +```yaml +map: + + # Create a CHESS style map + - common.MapProcessor: + config: + title: # Enter an appropriate name (like the BTR) + station: id1a3 + experiment_type: EDD + sample: + name: # Enter the sample name + description: '' + spec_scans: # Edit both SPEC log file path and EDD scan numbers + # Path can be relative to inputdir or absolute + - spec_file: /spec.log + scan_numbers: 1-4 + scalar_data: # Add or modify as appropriate + - label: SCAN_N + units: n/a + data_type: smb_par + name: SCAN_N # Change as needed + independent_dimensions: + # Add or modify as appropriate + - label: labx + units: mm + data_type: smb_par + name: labx # Change as needed + - label: laby + units: mm + data_type: smb_par + name: laby # Change as needed + - label: labz + units: mm + data_type: smb_par + name: labz # Change as needed + presample_intensity: + label: presample_intensity + units: counts + data_type: scan_column + name: a3ic1 # Change as needed + dwell_time_actual: + label: dwell_time_actual + units: s + data_type: scan_column + name: sec # Change as needed + postsample_intensity: + label: postsample_intensity + units: counts + data_type: scan_column + name: diode # Change as needed + detector_config: + detectors: # Use available detector elements when omitted + - id: 0 + - id: 11 + - id: 22 + - common.NexusWriter: + filename: map.nxs # NeXus map output filename + force_overwrite: true +``` + +### Specifying the detector configuration in the EDD workflow + +#### Selecting detectors for detector calibration + +In the example above, the raw data for both the energy and the $2\theta$ calibration is read by the `common.SpecReader` pipeline item, while which detectors to include in the calibration is specified in the `detectors` field under `detector_config` in the `edd.MCAEnergyCalibrationProcessor` and `edd.MCATthCalibrationProcessor` pipeline items, respectively. +However, this is not the only way to specify the detectors to use. As can be seen from the documentation for [`SpecReader`](https://chesscomputing.github.io/ChessAnalysisPipeline/CHAP.common.html#CHAP.common.reader.SpecReader), the detectors for which raw data is read can also be specified by adding a `detector_config` field to the `SpecReader`. For example, by using the following in the pipeline file for the EDD workflow above: +```yaml + - common.SpecReader: + config: + station: id1a3 # Change as needed + experiment_type: EDD + spec_scans: # Edit both SPEC log file path and EDD scan numbers + # Path can be relative to inputdir (line 3) or absolute + - spec_file: /spec.log + scan_numbers: 1 + detector_config: + detectors: # Choose the detectors + # Use all available detector elements when omitted + - id: 0 + - id: 11 + - id: 22 +``` +When the `detector_config` or `detectors` field is omitted in the `MCAEnergyCalibrationProcessor` configuration, the energy calibration will be performed for all detectors for which raw data is read. With the `detectors` field specified, the energy calibration is performed for only *those detectors* that are selected there that are *also* read by `SpecReader`. Any detector selected in the `MCAEnergyCalibrationProcessor` configuration that is not read by `SpecReader` will be *omitted* (resulting in a "no raw data" warning). +The same detector selection mechanism is valid for $2\theta$ calibration, with the added feature that any detector selected during the energy calibration will be included automatically during $2\theta$ calibration, *irrespective* of it being selected in the `MCATthCalibrationProcessor` configuration (contingent upon the reading of the appropriate raw data by the preceeding `SpecReader`). + +#### Selecting detectors for Strain analysis + +A similar detector selection approach is available for the strain analysis among the `MapProcessor` and the `StrainAnalysisProcessor` configurations and the availablity of calibrated detector data. When the `detector_config` or `detectors` field is omitted in the `StrainAnalysisProcessor` configuration, the strain analysis will be performed for all detectors for which both raw data is read by `MapProcessor` and for which calibrated detector data is read by the `common.YAMLReader` pipeline item under the `strain` block in the pipeline file above. With the `detectors` field specified, the detectors that are used are further restricted to only those that are listed in its field under the `edd.StrainAnalysisProcessor` pipeline item. Any detector selected in the `StrainAnalysisProcessor` configuration for which raw data from `MapProcessor` is missing is skipped accompanied by a "no raw data" warning. Similarly, any selected detector for which detector calibration input is missing is skipped accompanied by a "no calibration data" warning. + +#### Selecting other parameters in the detector configuration + +In addition to which detectors to include, the user also has the choice to pick many other parameters that affect the detector configuration and the EDD workflow. Some are specific to certain processors in the EDD workflow, but a certain set, those in the [`FitConfig`](https://chesscomputing.github.io/ChessAnalysisPipeline/CHAP.edd.html#CHAP.edd.model.FitConfig) configuration class, can be specified both on a *per-detector-basis* as well as on a *for-all-detectors basis*. This is evident from the fact that both [`MCADetectorConfig`](https://chesscomputing.github.io/ChessAnalysisPipeline/CHAP.edd.html#CHAP.edd.model.MCADetectorConfig) as well the list entries in its `detectors` field are derived from `FitConfig`. The generic behavior for each of these parameters is that those specified on the *for-all-detector* level, i.e. as items of the `detector_config` fields, superseed those that are specified on a *per-detector-basis*. + +Take for example two scenarios for the detector configuration in the energy calibration step: + +- as specified in the pipeline file above: + ```yaml + detector_config: + baseline: true + mask_ranges: [[650, 850]] + detectors: + - id: 0 + - id: 11 + - id: 22 + ``` + +- or specified as follows: + ```yaml + detector_config: + mask_ranges: [[650, 850]] + detectors: + - id: 0 + baseline: true + - id: 11 + mask_ranges: [[600, 850]] + - id: 22 + baseline: + lam: 1.e-5 + mask_ranges: [[650, 900]] + ``` + +The first case will set `baseline` and `mask_range` for each detector to the *same* value specified by the respective values in the `detector_config` configuration. The same happens for `mask_range` in the second case, where its entries for detector 11 and 22 are ignored. Whereas, the `baseline` parameter for detector 0, 11 and 22 is set to `True`, `False` (its default value), and `True` with a smoothness parameter, lam, of $10^{-5}$, respectively. + +#### Recommended XPS23 detector configuration +Below is good configuration for the CHESS XPS23 detector. Use it as a starting point for the XPS23 configuration in your workflow. It can be used either as a `detector_config` parameter directly in your `pipeline.yaml` file and/or as the contents of a separate `detector_config.yaml` file that can be read into the data in your pipeline with a `YAMLReader` and `schema: common.models.map.DetectorConfig`): +```yaml +detectors: +- id: 0 + attrs: + eta: -180.0 +- id: 1 + attrs: + eta: -171.8181818181818 +- id: 2 + attrs: + eta: -163.63636363636363 +- id: 3 + attrs: + eta: -155.45454545454544 +- id: 4 + attrs: + eta: -147.27272727272728 +- id: 5 + attrs: + eta: -139.0909090909091 +- id: 6 + attrs: + eta: -130.9090909090909 +- id: 7 + attrs: + eta: -122.72727272727272 +- id: 8 + attrs: + eta: -114.54545454545455 +- id: 9 + attrs: + eta: -106.36363636363636 +- id: 11 + attrs: + eta: -98.18181818181819 +- id: 10 + attrs: + eta: -90.0 +- id: 12 + attrs: + eta: -81.81818181818181 +- id: 13 + attrs: + eta: -73.63636363636364 +- id: 14 + attrs: + eta: -65.45454545454545 +- id: 15 + attrs: + eta: -57.27272727272728 +- id: 16 + attrs: + eta: -49.09090909090909 +- id: 17 + attrs: + eta: -40.90909090909091 +- id: 18 + attrs: + eta: -32.72727272727272 +- id: 19 + attrs: + eta: -24.54545454545456 +- id: 21 + attrs: + eta: -8.181818181818187 +- id: 22 + attrs: + eta: 0.0 +``` + ## Additional notes on energy calibration As mentioned above a standard EDD experiment needs calibration of the detector channel energies. Experiments have shown that the channel energies $E_j$ vary linearly with the channel index $j$ within the energy range of typical EDD experiments: $E_j = mj+b$, where the slope $m$ and intercept $b$ can be determined in one or a combination of two experiments: @@ -270,7 +468,7 @@ $$ \frac{1}{d_{hkl}} = \frac{2m\sin(\theta)}{hc} j_{hkl} + \frac{2b\sin(\theta)}{hc} = m'j_{hkl}+b' $$ -which says that given a set of known Bragg peaks corresponding to lattice spacings $d_{hkl}$ occuring at channel indices $j_{hkl}$, a linear fit will uniquely determine $m'$ and $b'$. For a known takeoff angle $2\theta$, this uniquely determines $m$ and $b$ as well. Note that this also implies that without an accurately known value of $2`theta$, one *cannot* uniquely determine $m$ and $b$ from Bragg diffraction alone! +which says that given a set of known Bragg peaks corresponding to lattice spacings $d_{hkl}$ occuring at channel indices $j_{hkl}$, a linear fit will uniquely determine $m'$ and $b'$. For a known takeoff angle $2\theta$, this uniquely determines $m$ and $b$ as well. Note that this also implies that without an accurately known value of $2\theta$, one *cannot* uniquely determine $m$ and $b$ from Bragg diffraction alone! This leads to the above mentioned two-step detector channel energy calibration procedure: diff --git a/index.md b/index.md deleted file mode 100644 index 9ecb870b..00000000 --- a/index.md +++ /dev/null @@ -1,18 +0,0 @@ -### CHAP installation -- [Installation](docs/installation.md) - -### Workflow introductions -- [Energy Dispersive Diffraction (EDD)](docs/workflows/EDD.md) -- [Tomography](docs/workflows/Tomo.md) - -