Skip to content

Conversation

@CoolatMax
Copy link

Pull Request: Add "Quick Assistance" Section to Docs and README #53

Description

This PR addresses Issue #53 by introducing a new "Quick Assistance" section designed to help new users quickly perform common tasks with asltk.

Changes Included

1. New Documentation Page

  • Added docs/quick_assistance.md
  • Contains concise examples for:
    • Loading/saving ASL images
    • Modifying PLD and LD parameters
    • Copying ASL datasets
    • Creating T1-BLG mappings
    • Running CBF reconstruction
    • Using the logging system
  • Internal cross-links to related pages (e.g. usage_examples.md, logging.md)

2. Updated README

  • Added a short "Quick Assistance" reference block
  • Directs users to the full guide on ReadTheDocs

3. MkDocs Configuration

  • Updated mkdocs.yml to include the new quick_assistance.md in the navigation

Why This Matters

This update provides:

  • Faster onboarding for new users
  • Copy-paste ready examples
  • A centralized reference hub for common ASL tasks

Related

Closes #53
Docs link: Quick Assistance on ReadTheDocs

@acsenrafilho Please check, review and merge
Thank You

@acsenrafilho acsenrafilho changed the base branch from main to develop July 31, 2025 10:46
@codecov
Copy link

codecov bot commented Jul 31, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@acsenrafilho acsenrafilho added the documentation Improvements or additions to documentation label Jul 31, 2025
Copy link
Member

@acsenrafilho acsenrafilho left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you very much for the contribution!
I made some commentaries to fix general problema with the methods import and usage.

Please use the documentation and code docstring as reference to make the modifications.

Thank you again for helping this project!

## Load and Save an ASL Image

```python
from asltk.io import load_asl, save_asl
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please, check the asltk documentation reference to make the correct import and function usage.

---
## Modify Parameters of an ASL Image
```python
from asltk.io import load_asl
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please, check the asltk documentation reference to make the correct import and function usage.

from asltk.io import load_asl

asl_data = load_asl("image.nii.gz")
asl_data.pld_values = [1.5] # Update post-label delay
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

a sugestion is to provide more data in the list, even though that new data is randomly choosen.
It is better to assist new users to understand that the ld, pld, and so on, are actually python lists of float values

---
## Copy an ASL Dataset
```python
from copy import deepcopy
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please, check the asltk documentation reference to make the correct import and function usage.
There is a copy method in the ASLData class

## Create T1-BLG Map from MultiTE-ASL
```python
from asltk.io import load_asl
from asltk.multite import generate_t1blgm_map
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please, check the asltk documentation reference to make the correct import and function usage.
This is not he actual way to call the object. Please, revise it

---
## Modify Parameters Before Reconstruction
```python
from asltk.io import load_asl
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please, check the asltk documentation reference to make the correct import and function usage.
Same commentary as above

@@ -0,0 +1,70 @@
# **Quick Assistance**
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is also needed to be allocated the new quick_assistance.md file into the mkdocs.yml configuration.
Please modify the configuration to propagate the documentation correctly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Improvement] Add new section in documentation: Quick assistance

2 participants