Merge pull request #128 from drbergman/development

v0.0.27

Author: drbergman

.github/workflows/CI.yml

@@ -113,6 +113,8 @@ jobs:
         PCVCT_PUBLIC_REPO_AUTH: ${{ secrets.PUBLIC_REPO_AUTH }}
 
     - uses: julia-actions/julia-processcoverage@v1
+      with:
+        directories: src,deps
 
     - uses: codecov/codecov-action@v5
       with:

.gitignore

@@ -4,6 +4,7 @@ test.jl
 *.db
 .vscode
 studio_debug.log
+/temp
 
 # from PkgTemplate.jl
 *.jl.*.cov

Project.toml

@@ -1,7 +1,7 @@
 name = "pcvct"
 uuid = "3c374bc7-7384-4f83-8ca0-87b8c727e6ff"
 authors = ["Daniel Bergman <[email protected]> and contributors"]
-version = "0.0.26"
+version = "0.0.27"
 
 [deps]
 AutoHashEquals = "15f4f7f2-30c1-5605-9d31-71845cf9641f"
@@ -20,6 +20,7 @@ LazyGrids = "7031d0ef-c40d-4431-b2f8-61a8d2f650db"
 LightXML = "9c8b4983-aa76-5018-a973-4c85ecc9e179"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MAT = "23992714-dd62-5051-b70f-ba57cb901cac"
+MacroTools = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
 MetaGraphsNext = "fa8bd995-216d-47f1-8a91-f3b68fbeb377"
 PairCorrelationFunction = "1da3c5ec-5de6-497d-83f1-8bbf7fdc92ec"
 Parameters = "d96e819e-fc66-5662-9728-84c9c7592b0a"
@@ -52,6 +53,7 @@ LazyGrids = "1"
 LightXML = "0.9"
 LinearAlgebra = "1.10 - 1"
 MAT = "0.10"
+MacroTools = "0.5.16"
 MetaGraphsNext = "0.7.2"
 PairCorrelationFunction = "0.0.11"
 Parameters = "0.12"

README.md

@@ -13,45 +13,49 @@ Make sure you are familiar with the [Best practices](https://drbergman.github.io
 See [Getting started](https://drbergman.github.io/pcvct/stable/man/getting_started/) for more details.
 
 1. [Install Julia](https://julialang.org/install).
-2. Add the PCVCTRegistry:
+2. Ensure the general registry is added:
+```julia-repl
+pkg> registry add General
+```
+3. Add the PCVCTRegistry:
 ```julia-repl
 pkg> registry add https://github.com/drbergman/PCVCTRegistry
 ```
-3. Install pcvct:
+4. Install pcvct:
 ```julia-repl
 pkg> add pcvct
 ```
-4. Create a new project:
+5. Create a new project:
 ```julia-repl
 julia> using pcvct
 julia> createProject()
 ```
-5. Import a project:
+6. Import a project:
 ```julia-repl
 julia> initializeModelManager()
 julia> importProject("path/to/project_folder") # replace with the path to your project folder
 ```
-6. Check the output of Step 5 and record your input folders:
+7. Check the output of Step 5 and record your input folders:
 ```julia-repl
 julia> config_folder = "my_project" # replace these with the name from the output of Step 5
 julia> custom_code_folder = "my_project"
 julia> rules_folder = "my_project" 
 julia> inputs = InputFolders(config_folder, custom_code_folder; rulesets_collection = rules_folder) # also add ic_cell and ic_substrate if used
 ```
-7. Run the model:
+8. Run the model:
 ```julia-repl
 julia> out = run(inputs; n_replicates = 1)
 ```
-8. Check the output:
+9. Check the output:
 ```julia-repl
 julia> using Plots # make sure to install Plots first
 julia> plot(out)
 julia> plotbycelltype(out)
 ```
-9. Vary parameters:
+10. Vary parameters:
 ```julia-repl
 julia> xml_path = configPath("some_cell_type", "apoptosis", "death_rate") # replace with a cell type in your model
 julia> new_apoptosis_rates = [1e-5, 1e-4, 1e-3]
 julia> dv = DiscreteVariation(xml_path, new_apoptosis_rates)
 julia> out = run(inputs, dv; n_replicates = 3) # 3 replicates per apoptosis rate => 9 simulations total
-```
+```

codecov.yml

@@ -1,3 +1,2 @@
 ignore:
-  - "src/public.jl"
-  - "src/up.jl"
+  - "src/up.jl"

deps/DeprecateKeywords.jl

@@ -0,0 +1,154 @@
+module DeprecateKeywords
+
+using MacroTools
+
+"""
+    @depkws [force=false] def
+
+Macro to deprecate keyword arguments. Use by wrapping a function signature,
+while using `@deprecate(old_kw, new_kw)` within the function signature to deprecate.
+
+# Examples
+
+```julia
+@depkws function f(; a=2, @deprecate(b, a))
+    a
+end
+```
+
+```julia
+# force the deprecation warning to be emitted
+@depkws force=true function f(; a=2, @deprecate(b, a))
+    a
+end
+```
+"""
+macro depkws(args...)
+    options = parse_options(args[1:end-1])
+    return esc(_depkws(args[end], options))
+end
+
+function parse_options(args)
+    options = default_options()
+    for arg in args
+        if isa(arg, Expr) && arg.head == :(=)
+            @assert arg.args[1] ∈ keys(options) "Unknown option: $(arg.args[1])"
+            options[arg.args[1]] = arg.args[2]
+        else
+            error("Invalid option: $arg")
+        end
+    end
+    return options
+end
+
+function default_options()
+    return Dict{Symbol, Any}(:force => false)
+end
+
+abstract type DeprecatedDefault end
+
+function _depkws(def, options)
+    sdef = splitdef(def)
+    func_symbol = Expr(:quote, sdef[:name])  # Double quote for expansion
+
+    new_symbols = Symbol[]
+    deprecated_symbols = Symbol[]
+    kwargs_to_remove = Int[]
+    for (i, param) in enumerate(sdef[:kwargs])
+        isa(param, Symbol) && continue
+        # Look for @deprecated macro:
+        if param.head == :macrocall && param.args[1] == Symbol("@deprecate")
+            # e.g., params.args[2] is the line number
+            deprecated_symbol = param.args[end-1]
+            new_symbol = param.args[end]
+            if !isa(new_symbol, Symbol)
+                # Remove line numbers nodes:
+                clean_param = deepcopy(param)
+                filter!(x -> !isa(x, LineNumberNode), clean_param.args)
+                error(
+                    "The expression\n    $(clean_param)\ndoes not appear to be two symbols in a `@deprecate`. This can happen if you use `@deprecate` in a function " *
+                    "definition without " *
+                    "parentheses, such as `f(; @deprecate a b, c=2)`. Instead, you should write `f(; (@deprecate a b), c=2)` or alternatively " *
+                    "`f(; @deprecate(a, b), c=2)`.)"
+                )
+            end
+            push!(deprecated_symbols, deprecated_symbol)
+            push!(new_symbols, new_symbol)
+            push!(kwargs_to_remove, i)
+        end
+    end
+    deleteat!(sdef[:kwargs], kwargs_to_remove)
+
+    # Add deprecated kws:
+    for deprecated_symbol in deprecated_symbols
+        pushfirst!(sdef[:kwargs], Expr(:kw, deprecated_symbol, DeprecatedDefault))
+    end
+
+    symbol_mapping = Dict(new_symbols .=> deprecated_symbols)
+
+    # Update new symbols to use deprecated kws if passed:
+    for (i, kw) in enumerate(sdef[:kwargs])
+        no_default_type_assertion = !isa(kw, Symbol) && kw.head != :kw
+        no_default_naked = isa(kw, Symbol)
+        no_default = no_default_naked || no_default_type_assertion
+
+        (kw, type_assertion) = if no_default_type_assertion
+            @assert kw.head == :(::)
+            # Remove type assertion from keyword; we will
+            # assert it later.
+            kw.args
+        else
+            (kw, Nothing)
+        end
+
+        new_kw, default = if no_default
+            (kw, DeprecatedDefault)
+        else
+            (kw.args[1], kw.args[2])
+        end
+
+
+        _get_symbol(new_kw) in deprecated_symbols && continue
+        !(_get_symbol(new_kw) in new_symbols) && continue
+
+        deprecated_symbol = symbol_mapping[_get_symbol(new_kw)]
+        depwarn_string = "Keyword argument `$(deprecated_symbol)` is deprecated. Use `$(_get_symbol(new_kw))` instead."
+        new_kwcall = quote
+            if $deprecated_symbol !== $(DeprecatedDefault)
+                Base.depwarn($depwarn_string, $func_symbol; force=$(options[:force]))
+                $deprecated_symbol
+            else
+                $default
+            end
+        end
+        sdef[:kwargs][i] = Expr(:kw, new_kw, new_kwcall)
+
+        if no_default_type_assertion
+            pushfirst!(
+                sdef[:body].args,
+                Expr(:(::), _get_symbol(new_kw), type_assertion)
+            )
+        end
+
+        if no_default
+            # Propagate UndefKeywordError
+            pushfirst!(
+                sdef[:body].args,
+                Expr(:if,
+                    Expr(:call, :(===), _get_symbol(new_kw), DeprecatedDefault),
+                    Expr(:call, :throw,
+                        Expr(:call, :UndefKeywordError, QuoteNode(_get_symbol(new_kw)))
+                    )
+                )
+            )
+        end
+    end
+
+    return combinedef(sdef)
+end
+
+# This is used to go from a::Int to a
+_get_symbol(e::Expr) = first(map(_get_symbol, e.args))
+_get_symbol(e::Symbol) = e
+
+end

docs/src/lib/deprecate_keywords.md

@@ -0,0 +1,21 @@
+```@meta
+CollapsedDocStrings = true
+```
+
+# Deprecate Keywords
+
+A light edit of the [DeprecateKeywords.jl](https://github.com/MilesCranmer/DeprecateKeywords.jl) package to enable the deprecation warnings for users.
+
+## Public API
+```@autodocs
+Modules = [pcvct.DeprecateKeywords]
+Pages = ["DeprecateKeywords.jl"]
+Private = false
+```
+
+## Private API
+```@autodocs
+Modules = [pcvct.DeprecateKeywords]
+Pages = ["DeprecateKeywords.jl"]
+Public = false
+```

docs/src/man/covariations.md

@@ -44,8 +44,7 @@ using pcvct
 timing_1_path = configPath("user_parameters", "event_1_time")
 timing_2_path = configPath("user_parameters", "event_2_time")
 dv1 = UniformDistributedVariation(timing_1_path, 100.0, 200.0)
-flip = true
-dv2 = UniformDistributedVariation(timing_2_path, 100.0, 200.0, flip)
+dv2 = UniformDistributedVariation(timing_2_path, 100.0, 200.0; flip=true)
 covariation = CoVariation(dv1, dv2)
 cdf = 0.1
 pcvct.variationValues.(covariation.variations, cdf) # pcvct internal for getting values for an ElementaryVariation

src/analysis/graphs.jl

@@ -1,5 +1,8 @@
 using Graphs, MetaGraphsNext
 
+include(joinpath(@__DIR__, "..", "..", "deps", "DeprecateKeywords.jl"))
+import .DeprecateKeywords: @depkws
+
 export connectedComponents
 
 """
@@ -34,25 +37,15 @@ For each key, the value is a list of connected components in the graph.
 Each component is represented as a vector of vertex labels.
 As of this writing, the vertex labels are the simple `AgentID` class that wraps the cell ID.
 """
-function connectedComponents(snapshot::PhysiCellSnapshot, graph::Symbol=:neighbors; include_cell_type_names=:all_in_one, exclude_cell_type_names=String[], include_dead::Bool=false,
-                             include_cell_types=nothing, exclude_cell_types=nothing)
+@depkws force=true function connectedComponents(snapshot::PhysiCellSnapshot, graph::Symbol=:neighbors; include_cell_type_names=:all_in_one, exclude_cell_type_names=String[], include_dead::Bool=false,
+    @deprecate(include_cell_types, include_cell_type_names), @deprecate(exclude_cell_types, exclude_cell_type_names))
     is_all_in_one = include_cell_type_names == :all_in_one
     cell_type_to_name_dict = cellTypeToNameDict(snapshot)
     cell_type_names = values(cell_type_to_name_dict) |> collect
 
-    if !isnothing(include_cell_types)
-        @assert include_cell_type_names == :all_in_one "Do not use both `include_cell_types` and `include_cell_type_names` as keyword arguments. Use `include_cell_type_names` instead."
-        Base.depwarn("`include_cell_types` is deprecated as a keyword. Use `include_cell_type_names` instead.", :connectedComponents, force=true)
-        include_cell_type_names = include_cell_types
-    end
     include_cell_type_names = processIncludeCellTypes(include_cell_type_names, cell_type_names)
-
-    if !isnothing(exclude_cell_types)
-        @assert exclude_cell_type_names == String[] "Do not use both `exclude_cell_types` and `exclude_cell_type_names` as keyword arguments. Use `exclude_cell_type_names` instead."
-        Base.depwarn("`exclude_cell_types` is deprecated as a keyword. Use `exclude_cell_type_names` instead.", :connectedComponents, force=true)
-        exclude_cell_type_names = exclude_cell_types
-    end
     exclude_cell_type_names = processExcludeCellTypes(exclude_cell_type_names)
+
     loadGraph!(snapshot, graph)
     if is_all_in_one
         G = getfield(snapshot, graph) |> deepcopy

src/analysis/substrate.jl

@@ -77,6 +77,7 @@ asts = pcvct.AverageSubstrateTimeSeries(1) # Load average substrate time series
 asts.time # Get the time points
 asts["time"] # alternative way to get the time points
 asts["oxygen"] # Get the oxygen concentration over time
+```
 """
 struct AverageSubstrateTimeSeries
     simulation_id::Int